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/

Renewed again as SharePoint MVP

Received the mail from Microsoft last week to say I’m a SharePoint MVP for another year (my third). Looking back over the last 12 months, it’s been fun being an MVP in the run-up and aftermath of a new release and I definitely feel privileged to have been in that position. I had some opportunities to do interesting things such as help write the 2010 exams, produce MSDN content and co-author a book, which was great. Ultimately I had to decline several of them due to the combination of full-time job, existing community commitments and the arrival of our twins, but then you can’t have everything :)

This list is mainly for me rather than you, but the main things I did were:

• Presentations on SharePoint 2010 Application Lifecycle Management at the SharePoint Evolutions conference
• Also stepping in for AC to deliver one of his sessions at the same event
• Presentation on Managed Metadata and other ECM enhancements in SharePoint 2010
• 24 blog articles - including my series’ around ribbon customization and Managed Metadata etc.
• Helping Microsoft’s SharePoint Patterns & Practices team with their recently released Developing Applications for SharePoint 2010 guidance
• Maintenance releases of my Codeplex projects
• Writing a book chapter
• Answering questions on www.sharepointoverflow.com 

One thing that does nag at me is that I know that some blog comments slipped through the net during the super-busy periods. I feel bad about this, but sometimes they just come in too thick and fast and I don’t seem to have a good system for finding unanswered ones! Apologies to those affected – by all means try again and I’ll do my best to answer.

Many thanks to those who left feedback, it’s always appreciated :)

Feature upgrade (part 2) – a sample to play with

In this article series:

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

In my last post I covered some fundamental aspects of SharePoint 2010’s Feature upgrade framework, and covered concepts such as upgrading Features using pure XML (ApplyElementManifests, AddContentTypeField) or shelling out to code (CustomUpgradeAction) to perform the necessary steps. For some reason it feels like Feature upgrade is one of those areas which is slightly harder to get up and running with, possibly because some XML will need to be cranked for some steps, or maybe because coming up with life-like upgrade scenarios with realistic artifacts takes some effort in itself. So, I thought it might be useful if I made available a sample I’ve been using (e.g. in my ALM talks and book chapter) for folks to download and use, in the hope that developers interested in seeing this stuff for themselves might have less work to do.

The sample

In addition to providing the source/XML files, I spent some time documenting the exact steps to go through when using the files to ‘execute’ my Feature upgrade scenarios. There’s a 3 page Word document which walks you through the upgrade steps, meaning the sample is effectively a “lab” of the type you might do on a training course:

 

Similarly, the files provided cover all the different “states” in the process so you can just copy and paste the bits as you go:

The upgrade examples

I came up with the following upgrade scenarios for the sample:

• Upgrade iteration 1 - using ApplyElementManifests and AddContentTypeField to add new fields to a content type and push down to lists using it.
• Upgrade iteration 2 – using CustomUpgradeAction/FeatureUpgrading to pseudo-upgrade a Text field to a Note field, by provisioning a new Note field/running code to iterate list items/copy data from old field to new/mark old field as hidden. (This scenario illustrates that many upgrades require code.)

The link

Download the files from http://sites.google.com/site/sharepointchris/sp2010_featureupgradesample

Summary

Feature upgrade is a slightly complex area, and I’m providing a sample that might help if this is an area of SharePoint 2010 you want to look more closely at. I’ve tested the documentation/files, but if anyone uses the sample and hits an issue, feel free to leave a comment here and I’ll do my best to help. The book chapter I wrote contains a rendition of this sample (along with much wider Application Lifecycle Management coverage, as you’d expect), but I thought it would be good to publish it to a wider audience.