Feature upgrade (part 3) – introducing SPFeatureUpgrade kit

In this article series:

1. Feature upgrade (part 1) – fundamentals
2. Feature upgrade (part 2) – a sample to play with
3. Feature upgrade (part 3) – introducing SPFeatureUpgrade kit (this article)
4. Feature upgrade (part 4) – advanced scenarios
5. Feature upgrade (part 5) – using PowerShell to upgrade Features

This is the third article in my Feature upgrade series. I wanted to post this earlier but (typical developer) I got caught up in doing some more work on the tool I’m introducing here. Back in the ‘Feature upgrade fundamentals’ post, I mentioned that although we now have this great framework for versioning and upgrading Features (thus providing a great vehicle to roll out new/modified functionality to our SharePoint sites), there are no tools out-of-the-box to help manage this process. This often confuses people when they start to look at Feature upgrade – no amount of redeploying/upgrading solutions or deactivating/reactivating Features will trigger the upgrade event (because reactivation is *not* upgrade, by design!), and SharePoint 2010 does not ship with any user interface, STSADM command or PowerShell cmdlet to do this. In other words, a situation also known as a “partner opportunity”! What you do get is a series of methods in the API – although it doesn’t take too much to throw together a console app which will fill most of this gap, there are a few permutations and there is some complexity around handling failed upgrades. And anyway, in my world it’s always nice to have the option of doing things visually.

So, just like the Content Deployment Wizard plugged the gap of SharePoint’s content deployment framework not having a rich UI, my SPFeatureUpgrade kit on Codeplex might be useful if you start to version/upgrade Features in your environment. The kit installs as a WSP and all source code is published on the Codeplex site.

The following is a slightly expanded version of the Codeplex blurb – any of the images can be clicked on to enlarge.

What's in the kit

The kit is comprised of 3 things:

• An application page in Central Admin - administrators can use this to upgrade Features of any scope across the entire farm
• An OPTIONAL page in each site collection's Site Settings area - this can be used to devolve responsibility for upgrading Features (and therefore updating functionality provided by developers) to local site administrators. A Feature must be enabled on each site to enable this.
• [Coming soon] - a PowerShell cmdlet which allows Feature upgrade to be run from script. (This is the final piece and will be ready shortly, since I’ve got the core logic implemented already.)

One useful thing that the application pages allow you to do is selectively upgrade Features – it could be that you don’t want all sites or webs to receive the new functionality in the upgraded Feature. These pages display checkboxes next to each Feature instance so you can control what gets upgraded where. This is also useful if you plan to ‘phase’ the rollout of new functionality deployed using Feature upgrade.

[Sidenote – Feature upgrade is typically a developer-led thing, since it’s developers who build Features. If developers do not have permissions to to use the admin pages (or PowerShell) then clearly some communication will be required with the administrators who do. Note also that, as I discussed in Upgrading sandboxed solutions, the Feature upgrade concept does not apply in the sandbox since all Features instances there are automatically upgraded when a sandboxed solution is updated.]

Usage

Central Admin page

After deploying updates to a Feature, this page can be used to find and upgrade instances of the Feature across the farm. The tool is accessed from the ‘System Settings’ area with Central Admin:

Farm administrators can then select the scope (Farm, WebApplication, Site or Web) and then find Feature instances which require upgrade (this uses a set of methods named QueryFeatures() in the SharePoint API). In the image below I've selected 'WebApplication' as the scope and clicked 'Search' to display the results – I get a table of Features in different web applications which need upgrade (i.e. an updated version has been deployed but not yet upgraded):

(click any image to see larger/clearer version) 
I can use the checkboxes to selectively upgrade some instances and not others (by default all will be upgraded, but this can be controlled by deselecting checkboxes). In the image below I've upgraded 1 of the 2 web application Features found previously - the success/failure result of all feature instances are shown on the page:

In the example above, the selected Feature has now been upgraded.

To help the experience when used in larger farms, when the Central Admin page is used to upgrade Site or Web scoped Features, additional filters appear to allow you to restrict the scope of the query. [Sidenote - this uses some gratuitous jQuery to slide the filter controls in – I can practically hear a couple of server admins (or Spence :)) complaining about things sliding around, but hey I’ve got to have somewhere to practice!]. So for upgrading Site-scoped Features, a selector appears allowing to select the parent web application:

Similarly for Web-scoped Features, you filter on parent site collection:

Usage

Site Settings page

The Site Settings page works in a very similar way, except only Site and Web-scoped Features can be upgraded (in the current site collection). The ‘COB.SharePoint.Utilities.SiteSettingFeatureUpgrade’ Feature must be activated against each site collection which should show a link to this page. When enabled, the tool is accessed from the Site Settings area for the site collection:

Site collection administrators can then select the scope (e.g. Site or Web) and then find the Features which require upgrade. In the image below I've selected 'Web' as the scope and clicked 'Search' to display the results:

As before, I can use the checkboxes to selectively upgrade some instances and not others (by default all will be upgraded, but this can be controlled by deselecting checkboxes). In the image below I've upgraded 2 of the 4 web Features found previously - the success/failure result of all feature instances are shown on the page:

Summary

SharePoint 2010 introduces the ability to version and upgrade Features, but doesn’t provide any high-level tools to manage this process. I’m providing tools for farm administrators and (optionally) site collection administrators to do this. At the time of writing this article, a final piece in the form of a PowerShell cmdlet is still in progress but should be available soon.

The kit can be downloaded from http://spfeatureupgrade.codeplex.com/