Visual Studio 2010 SharePoint Developer Tools ‘Import’ Templates

With Visual Studio 2010, Microsoft has introduced in-the-box tools for SharePoint development. Included in those tools are various templates for you guys to start off with e.g. Visual Webparts, Content Type, List Instances, Workflows etc. There are two templates provided which support what our team has come to call the continuum between SharePoint Designer and Visual Studio. The two templates are the ‘Import SharePoint Solution Package’ template and the ‘Import Reusable Workflow’ template.

There seems to be some confusion around when to use the Import SharePoint Solution Package vs. Import Reusable Workflow templates. This blog post will get into the details of the differences and when we would want to use each of the templates. The key difference between the Import Reusable Workflow and the Import Solution Package is that the Import Reusable Workflow project template actually converts your declarative SharePoint Designer workflow into a VS code workflow that we can then open in the Visual Studio workflow designer, make edits, add code activities, debug and even add association or initiation forms to. The Import SharePoint Solution Package template on the other hand allows us to import reusable workflows (like the Import Reusable Workflow template), but the key difference is that it does not convert the workflow to a code workflow. This means we won’t be make edits, code additions or debug the workflow.

The primary scenarios for wanting to use the Import Solution Package template are:

• Importing custom SharePoint items (lists, content types, fields etc.) from an existing site
• Importing entire existing site into Visual Studio and customizing it

The primary scenarios for wanting to use the import Reusable Worklfow templates are:

• Importing and converting Reusable Workflows (made in SharePoint Designer) into code workflows for the purposes of customizing the Workflow with custom activities and code.
• Adding initiation and association forms to your converted Workflow

The rest of the blog shows the step by step of how the VS ‘import’ templates differ.

We will be using a solution package which was exported from a SharePoint Foundation site. This solution package contains a very simple workflow and a custom list instance both created in SharePoint Designer (SPD).

The workflow looks like the following in SharePoint Designer:

This is a very simple Workflow which checks if the title field contains the words ‘New task’ and if it does the task is then assigned to the person who created it.

The list instance looks like the following in SharePoint Designer:

Once we have created the Workflow and the Custom List, we can export the entire site via SharePoint (Site Actions -> Site Settings -> Save Site as Template). SharePoint will save this site as a WSP (SharePoint Solution Package) file and we will be using this solution package with the aforementioned templates and pointing out how they differ and when to use them.

Import SharePoint Solution Package

We start off by creating a new project in Visual Studio 2010 and use the ‘Import SharePoint Solution Package’ template from new project dialog:

For this blog, we’ll be using Visual Basic, but all SharePoint development templates are available in both C# and VB. I just like VB better :).

After naming the project (‘wspimportblog’ in this case) we press “OK” and we see the SharePoint Customization Wizard page:

This wizard, which is the same for every SharePoint project template in VS, gives us the option of selecting which local site we want to choose for debugging and the trust level of this particular SharePoint solution. After pressing “Next” we get to a wizard which is specific to the Import Solution Package template. This particular page allows us to select the solution package we want to import from the file system:

After selecting the solution package that we exported above, we are presented with a list of items that are available within.

The wizard parses through the entire solution package and lists out all available items in the solution package along with their types .

We can select the items we want to import using the checkbox next to each item. The checked items will be imported into your Visual Studio 2010 project by default, which means that if we went ahead with the wizard without changing the default selection we would end up importing the entire exported site into your VS project. For the purposes of this blog we just selected custom list instance (Shopping List), and the workflow created in SharePoint Designer (the workflow appears as a module instead of a workflow, I’ll explain why this happens later on):

If we scroll through the list of items to be imported in the wizard we will notice that there is a Workflow list instance in the list as well. This list instance is created when SharePoint designer is installed on the SharePoint server and SharePoint designer is used to deploy a Workflow. This list is where all the workflows (declarative or code) are deployed to. If we did not have SharePoint designer deployed Workflows on the machine we were deploying to, we would have to import the Workflow list instance as well in order to successfully deploy the imported workflow module on the target site.

Hint: We can press Ctrl+A (select all) when one of the items in the list is selected. This will select all the available entries in this list and allow us to select or unselect all of the items in the list with a single click; something which is very useful when we just want to select a few items from the list unless you want to go and select or unselect every item individually :).

Once we press Finish we might be presented with a ‘Selection Dependency Warning’ dialog:

When we make the selection of items we want to import (previous image) the wizard detects the dependencies of the selected items and prompts the user to ask if they want the dependencies imported along with the actual items. If we are importing a solution package which was generated on a site different to where we will deploy it back (target site), then it will be probable that all the required dependencies are not available on the target site and importing them will enable successful deployment of the selected items. In this case, we want all the dependencies to come into the project, so we should press “Yes” . The wizard parses out the items that are to be imported and builds a Visual Studio 2010 project containing all those items. This is what the Solution explorer should look like once the solution package has been successfully imported:

Notice how Visual Studio 2010 recognizes what is being imported. List Instances, Fields and Modules are placed under the List Instances, Field and Module folders etc. Furthermore the required features are created (3 in this case). One feature would contain the List, the other the workflow and finally there will be one feature for the imported property bags. Property bags, which can be required while deploying, will always be brought in and handled by VS i.e. they will not show up in the dependency warning dialog or in the item selection dialog, but they will be imported.

Previously I mentioned that the workflow we were importing was showing up as a Module, because of which, we can now see that the Workflow is under the “Modules” folder in the Solution Explorer. This is because of the difference between how we import workflows in the ‘Import SharePoint Solution Package’ template and the ‘Import Reusable Workflow’ template. For this template (Import SharePoint Solution Package) we bring the workflow in as a module to be able to deploy it back to SharePoint. The workflow cannot be customized or debugged (If you want to customize or extend your declarative Workflow, move on to the next section and we’ll discuss how that can be done). However other items (non-workflow) can be used. E.g. if we imported a content type, or imported a field, we could use those with other SharePoint Items that we create within the project.

When importing an entire site into Visual Studio, there may be items in the solution package that we don’t recognize. These unrecognized items will be placed in an “Other elements” folder within your solution; however this “Other elements” folder is not deployed.

Pressing F5 deploys both the List and the Workflow up to SharePoint. Since Visual Studio 2010 treats the imported workflow as a module with this template, there isn’t an option to associate this workflow to a list from within Visual Studio 2010. To use the recently deployed workflow we will have to go inside SharePoint and associate the workflow with an appropriate list.

Import Reusable Workflow

Onto using the ‘Import Reusable Workflow’ template! We use the same solution package that we used with the ‘Import SharePoint Solution Package’ template in the previous section. In the ‘New Project’ dialog we select the ‘Import Reusable Workflow’ template and give it a name (‘workflowimport’ in this case):

Upon pressing “OK” we get to the SharePoint Customization Wizard. For the ‘Import Reusable Workflow’ template the wizard always defaults to ‘Deploy as Farm Solution’. This is because code workflows can only be deployed as a farm solution and therefore ‘Deploy as sandboxed solution’ is greyed out. The second wizard page lets us choose the solution package file from the file system, similar to the ones in ‘Import SharePoint Solution Package’ template. Once we select the solution package we want and press “Next” the wizard parses through the solution package and finds all Workflows contained within:

In the previous template, the workflow was recognized as a module which keeps the workflow as a declarative workflow that can’t be edited or extended with code in VS, but in the case of the ‘Import Re-usable Workflow’ template, the wizard not only recognizes the custom Workflow (Workflow1) it also converts the declarative workflow to a code workflow, as evidenced by the screen shot above. Once we press finish the VS project containing the workflow is created and the solution explorer should look something like:

The workflow is now recognized and placed under the “Workflows” folder. For further customization we can also associate the workflow from within VS using the ‘Workflow debug settings’ which is available when we right-click the workflow in the solution explorer or we could add an initiation or association form for this Workflow (Right-click on the Workflow -> Add new item -> Initiation or Association form). Once the workflow has been converted into a code workflow, it can be opened up in the workflow designer. The workflow designer has a whole list of controls that can be used to modify the workflow and write code to customize it, put in breakpoints to debug and step through the code etc. (that is a blog for another day :))

With the ‘Import Reusable Workflow’ template we don’t need to import the Workflow list instance regardless of whether there is a SharePoint Designer deployed Workflow on the SharePoint server we are deploying to. Upon conversion and association Visual Studio 2010 makes sure that all the requirements for successful deployment of the workflow are covered.

Once the workflow has been customized and associated, we can press F5 and the converted workflow is then deployed out to the Workflow List in the target SharePoint site.

Wrap up

Hopefully this blog helps answer some questions regarding the difference between the two import templates.

The ‘Import Reusable Workflow’ template parses reusable WFs out of a solution package and converts them into code workflows so that the developer can customize and debug the workflow.

The ‘Import SharePoint Solution Package’ template gives the developer the opportunity to select some or all of the items available inside the solution package and then work with them.

For more information around the importing workflows and entire solution packages please refer to the following MSDN documentation:

• Importing Items from an Existing SharePoint Site.  It discusses what we can and can't import, what happens when we import a solution, etc. 
• Walkthrough for doing a WSP import: Walkthrough: Import Items from an Existing SharePoint Site
• This topic discusses issues to consider when importing reusable WFs: Guidelines for Importing Reusable Workflows
• Walkthrough for a reusable Workflow import: Walkthrough: Import a SharePoint Designer Reusable Workflow into Visual Studio

Please let us know if there are any questions around this topic and we can hopefully help you out. Happy Importing!

Saaid Khan

Comments

• Anonymous
  October 20, 2010
  Hello Chuck - The workflow initiation and association forms can only be added to a code-based workflow which you create in Visual Studio, not a declarative workflow that is imported from SP/SPD. If you create a new workflow in a SharePoint project within Visual Studio 2010, and then right click on the workflow node in solution Explorer and select Add New Item, you will see the workflow initiation and association form items in the dialog. Hope this helps, Mike

• Anonymous
  October 20, 2010
  For some reason, comment disappeared. I am re-posting it: Nice presentation.  A related question if I may: I've been trying to take things a step farther and add an Association Form.  All the instructions I have found say the Sharepoint 2010 node has Association and Initiation form templates in them.  Mine (Ultimate edition), does not.  Am I supposed to download these some there? Thanks so much for your help.