SharePoint 2010 ALM – Part 2 – Upgrading your Solutions, In-Place or Side-by-Side?

So in Part 1 we talked about some of the upgrade mechanisms available in SharePoint 2010, including Assembly level and Feature level versioning.

In Part 2 we are going to look at 2 distinct versioning strategies:

• In Place Upgrade (replace old with new)
• Side-by-Side Release (allow both version to run at the same time)

In-Place Upgrade

This is going to be most common scenario for bug fixing, hotfixes and minor improvements to the solution. So you might be adding some help files, or tweaking a user interface, or perhaps fixing some JavaScript or CSS bugs in your code.

Typically you would not use this approach for major versions of products, as a major change to interface or functionality is likely to confuse existing users, and might causing existing configurations to break! There are exceptions however, your client might not want to manually swap out 500 web-parts on their portal and might want a “big bang”.. provided it has been thoroughly tested!

So what did we discuss in Part 1 that can be used in SharePoint 2010 to achieve an In-Place Upgrade?

$SharePoint.Project.AssemblyFullName$

This can allow you to easily update all of your ASCX / ASPX / CAML references with the new assembly.

Next time your Page / Web Control / Feature receiver tries to execute then it will be running the new code, seamlessly.

Assembly Binding Redirects

This allows you to pick up any code that is attempting to execute in the old version, and forces it to run through the new assembly methods instead.

This is a blanket, assembly-wide approach, typically deployed at the Web Application level (although you can go server-wide using the machine.config!)

Warning – This obviously only works from code that runs through the web.config and IIS / ASP.Net. Any other code (such as Timer Jobs and Workflows) will be completely unaware of these redirects and will happily continue running the old code!

Workflows especially should not use binding redirects this way. If you drop in a redirect for a workflow that is currently running then you will break it next time it tries to serialize itself to the database!

Feature Versions

The feature framework allows you to do incremental upgrade steps to modify existing features, upgrading and “replacing” the functionality for existing items (such as Content Types, site columns, custom actions … anything that you would provision through a Feature.xml).

You might have to be careful with custom code (and the CustomUpgradeAction element) but all in all, Feature versions are designed to do an “in place upgrade” of your features.

Side-by-Side Release

This is likely to be the most common scenario for Major Versions, functionality changes, new templates. It is important to recognise that certain elements in the SharePoint schema MUST be upgraded in this way (such as Site Definitions, List Definitions and Workflows).  For this scenario “upgrade” is probably the wrong word to use, because what we really have to do is create a copy (and in some scenarios hide the old one!).

So how would you go about creating a side-by-side upgrade? Well, the first thing to consider is that you need to leave your existing assembly in place.

Solution Package (WSP) Considerations

If you “retract” the solution package then typically it will remove your original DLLs. This will cause existing functionality to break (this is bad).

One workaround is to create a new WSP. SharePoint will treat this as a separate solution, allowing you to install it while leaving the existing one in place.

Assembly (DLL) and Package (WSP) Considerations

The assembly needs careful consideration, depending on where your assembly is going to live;

If you have a full trust package which deploys to the GAC, then you really don’t have too much of a problem. You can create your new assembly with a different version number and deploy that DLL to the GAC. The GAC has been designed that the same assembly with multiple version numbers can happily sit side-by-side.

If you have a minimal trust package which deploys to the web application BIN folder then you have more of a problem. Releasing the same assembly name is going to overwrite the file (deleting the original DLL, which will break existing functionality … also bad). Other than moving it to the GAC (which breaks the whole point of deploying for minimal trust in the first place!) there is only one practical workaround here; rename your assembly (so you have 2 different DLL file names)

So now that you have dealt with your assembly, what about other assets?

Workflows (WWF)

Workflows are a nasty one. One they are running the class gets serialized into the database, so you HAVE to leave existing code on the system until all instances of that workflow have stopped running! (you can set a workflow to “no more instances” from the remove screen). The problem is that in a typical environment you are probably going to have NO IDEA how many workflow instances are running (and even if you did, you probably won’t be able, or willing, to stop them!).

The only scenario is to provide a duplicate workflow. Copy the workflow in Visual Studio, make your changes, and provision it into SharePoint as a DIFFERENT workflow.

Again, you would hide the original (so people can’t add them to new lists) and you would probably want to perform some kind of exercise to remove any existing workflows (once all the running instances have stopped) and setup the new workflow as a new instance on the list / content type.

As you can imagine, this is NOT going to be an easy task and it’s highly likely that this will be a manual governance effort, and not something that can be easily automated.

(note – even if you are leaving the existing workflow class in place you still can’t change the assembly version … the serialization will fail and existing workflow instances will break!)

Site Definitions (onet.xml)

Microsoft very clearly states that modifying a Site Definition while it is use is not supported.

So how DO you “upgrade” them? Well, you have 2 options:

Feature Stapling

The easy solution is to use a feature stapler to add new functionality to an existing site.

This allows you to modify NEW sites that are created, although you won’t be able to impact on everything (features activate before lists and pages are created, so you won’t be able to modify those!)

This is discussed in detail on MSDN: http://msdn.microsoft.com/en-us/library/bb861862(office.12).aspx

Copy and Hide the Original

This is pretty straightforward. You copy your Site Template folder and create a new version.

You then modify your WEBTEMP*.xml file to add in your new template (using the same name / description as the original).

You then set the original template in the WEBTEMP*.xml as Hidden=TRUE.

Deploying this, your users still “see” exactly the same when they create new sites, but when they do create the site it is now provisioning using your new template!

List Definitions (schema.xml)

This is a very similar story to Site Definitions. You can change “some” things but not everything (and some of the things you change may break existing lists!).

The most reliable way is to copy your Feature (giving it a new GUID) and hide the original ListTemplate. This will stop users from using the old template to create new lists, but if you have existing sites that are provisioning them automatically then you’ll have to look at the Site Definition upgrade (see above!).

That should give you a pretty good grounding (at the very least a start!) at how to upgrade your projects, either in-place upgrade or side-by-side upgrade.

A lot of it is going to be head-scratching and sitting down to think .. don’t rush into it, take your time, and make sure you truly understand what you are trying to achieve, and what the impact is going to be on the end users!