So you just built this compelling Visual Studio workflow and deployed it into production. Things go great for a few months, but then the business requests a small change to the workflow. You go back into the workflow code, add a few activities to fulfill the request, and redeploy the workflow into production. To your shock, all the workflows start breaking! You're frantic because you're certain you adequately unit tested the changes, and can't figure out what might be going wrong. If this is you, you didn't version your workflow.
Workflow versioning is a very important technique. When a workflow goes idle, the state of the workflow is and saved (hydrated) into the database. This saving of a workflow's state is called hydration. When the workflow resumes, the state is dehydrated out of the database and the workflow starts processing again. Versioning is important because if you change the assembly while the workflow is hydrated (saved in the database), there's no guarantee that when the workflow dehydrated it will match the construct of the new assembly. If it doesn't match the construct upon de-serialization, the workflow will break. Changes like adding or removing activities and changing property values may necessitate a new workflow version. The best practice is to create a new version every time rather than just push the assembly and cross your fingers.
A new workflow version is essentially a new workflow. The basic technique is to make your assembly increment the version number with each build (rather than just leave it at 1.0.0.0 forever). Then, for each upgrade you create a new feature for that "version" of the workflow, pointing to the new assembly. You add the new assembly into the GAC alongside the old assembly. Lastly you specify that the old version cannot start new instances of the workflow and you add the new workflow onto the list. This way the old version of the assembly never changes, so there's no risk of hydrated workflows breaking when they are dehydrated. All you ever do is deploy another version of the assembly and add the new workflow to the list and disable previous versions. You don't want to remove the previous versions because that will orphan those running instances. For the full set of procedures, follow these steps to create a new version for an existing workflow:
Note: Old version overwritten
If you do not create a new version, and rather just upgrade the solution, all running instances of the workflow will be deleted. The old version of the workflow will be removed, and the new version will be added with zero running instances. Don't upgrade without creating a new version unless you're entirely sure you don't need to retain the running instances.
STEP 1 Create version 1.0.0.0 in your workflow's elements file
A) In the Elements.xml file of your workflow, replace $assemblyname$ in CodeBesideAssembly with the following:
[assembly name], Version=1.0.0.0, Culture=neutral, PublicKeyToken=[token]
B) Replace [assembly name] with your assembly name.
C) Replace [token] with your public key token. You can do this by finding your assembly in the GAC (c:\windows\assembly) and right clicking it, choosing Properties, and coping the token.
D) Change the name of the workflow in the Elements file to reference the new version.
Note: this is just so the user working with the workflow knows what version it is… it has no technical implications. For example:
E) Add a copy of version 1.0.0.0 to solution package by double clicking on the Package, and under the Advanced tab, add an existing assembly and browse to your 1.0.0.0 assembly version:
Note: notice how the Location and Source of the assembly is in a path under "Version 1.0.0.0". When the package is created, the 1.0.0.0 version is put in its own path because it cannot be in the same path as the current version since they both have the same name.
STEP 2: With version 1.0.0.0 established, you can now simulate the need to create version 2.0.0.0. Change the version of the assembly to 2.0.0.0
A) Under the Properties folder in the solution, open the AsseblyInfo.cs file.
B) Scroll to the bottom of the file and change the two versions to be 2.0.0.0.
STEP 3: Update the workflow's Elements.xml file to reference both the version 1.0.0.0 workflow and now the new 2.0.0.0 version.
A) Under the workflow, open the Elements.xml file.
B) Copy the Workflow element in its entirety and paste it directly after the </workflow> tag.
C) Change the name and the version (in the CodeBesideAssembly) of the second workflow to reference version 2.0.0.0.
D) Change the ID in the 2.0.0.0 version to be a new GUID. You can create a new GUID by using the Create GUID tool under the tools menu.
E) Build and deploy the solution.
STEP 4: Activate version 2.0.0.0
A) Within the root site in the site collection click Site Actions and click Site Settings.
B) Click Site Collection Features.
C) Deactivate and reactivate your workflow's feature.
STEP 5: With version 2.0.0.0 deployed and activated, we now need to prevent any new instances of version 1.0.0.0 from being created:
A) Navigate to the workflow settings page of the List or Site you're working on.
B) Click Remove a workflow.
C) Change version 1.0.0.0 to not allow new instances and click Ok (figure below)
Phil