Developing Workflows in VS: Part 6 - Deploy and Debug your workflow

 

 

Step 4: Deploy Your Workflow

Once you have your forms and code ready to go, it’s time to compile and deploy your workflow.  To prepare for deployment:

There are two required files for workflow features:

1) Feature.xml – just like every SharePoint feature, you need one of these for high level feature information.

2) Workflow template xml file (workflow.xml) – we’ve talked about workflow templates a lot, and this is where it comes from.  Specify the aspx pages to use for your form types (for IP forms, specify our out-of-box host pages) and details about your dll, and put any extra information you need in the Metadata section. 

You’ll also need the compiled assembly and your forms.

Once you have those, you can do the actual deployment.  You will need to do the following things (if you’re using the SharePoint workflow templates, this is what the PostBuildActions batch file does):

1)      Copy the assembly to the Global Assembly Cache so that SharePoint can run it

2)      Copy your xml files and forms to the SharePoint FEATURES folder, where SharePoint features live and are installed from.  Custom aspx pages should go into the LAYOUTS folder.

3)      Call stsadm, the magic SharePoint deployment tool, with parameters installfeature and activatefeature, to make the workflow available on a site collection.

4)      Do an iisreset to refresh the assemblies and templates.

A couple more things to keep in mind:

• Deployment for workflow goes to an entire site collection at a time
• InfoPath forms will be installed to the server automatically during deployment if you have the <Property Key="RegisterForms" Value="*.xsn" /> tag in the feature.xml.  ASPX forms need to be copied manually to the LAYOUTS directory.

The following diagram shows how the parts of the workflow.xml map to what you’d see in the SharePoint UI and workflow forms ( = an aspx page and a hosted IP form;)):

 

Step 5: Debug Your Workflow

With the feature ready to run on your server, you can now debug it live by adding break points, attaching your Visual Studio project to the IIS (w3wp.exe) processes and clicking through the workflow.  Associate your workflow to a list and try running it.  When you find a bug, recompile, redeploy, and reset.  Repeat until satisfiedJ.

FAQ: Debugger setup woes

• Visual Studio crashes when I “attach to process” – in the attachment dialog, only attach to Workflow or Managed Code. 
• My breakpoints aren’t activating – be sure the dll in the GAC is the exact same one in your project.  If you change a file in your project, even without recompiling, Visual Studio will think the dll is out of date and won’t link it to the project.  Also, don’t forget to iisreset to reload a new assembly.

FAQ: Tedious debugging

Debugging can be somewhat tedious because of the deployment steps, so here is some advice to speed up the process:

·         The VS templates for SharePoint Workflow can automatically run the stsadm deployment commands for you when you build.  Just prep your xml files, sign the assembly, and set the DEPLOY parameter in the project Post Build Actions command line in your project to turn it on.

·         If you’ve only changed the assembly, just reinstall it to the GAC and call iisreset.  (no need to reinstall the feature).  The PostBuildActions.bat file in the SharePoint Workflow VS templates has a QUICK parameter that does exactly that.

·         If you’ve changed your forms or template, you’ll need to reinstall the feature.  Don’t forget to deactivate/uninstall before reactivating.

·         The <AssociateOnActivate> tag in the metadata section of the workflow.xml will automatically associate a workflow with the Document content type.  Setting this to “true” can save time setting up or reactivating an association.  Just be sure you test on a doc lib that uses the Document content type.

·         Upload a bunch of documents so that don’t have to keep cancelling workflows that error out to run them again. 

Other debugging tips:

• Failed on Start usually means an error is happening in SharePoint before your workflow code spins up, such as not being able to find the workflow dll.  Error Occurred usually means the workflow started and the error is somewhere in the code.
• Check the SharePoint ULS logs! – fatal workflow errors might happen outside of your workflow, so they aren’t always visible in the debugger.  Consult the logs to see if this is the case by opening the latest log and searching from the bottom up for “Workflow”.  The logs are awesome resources that often get overlooked.  Logs can be found in %Program Files%/Common Files/Microsoft Shared/web server extensions/12/LOGS.

Next time: Summary and Final Thoughts