3. Upgrading Features
In SharePoint 2010, one of the important new
capabilities from a packaging and deployment perspective is the ability
to upgrade features. In previous versions, an upgrade was possible, but
it was more a case of replacing an old feature with a new version. This
could leave a system in an indeterminate state, because actions
performed by the old feature would not necessarily
be undone when a new version of the feature was installed. For example,
if a feature created a list that users subsequently populated with data
and then a new version of the feature created a new version of the list
with a different name, the result of deploying the new feature would be
two lists. A better approach would be to rename the old list.
With the upgrade capabilities in SharePoint 2010, we
can define a number of upgrade actions declaratively in the feature
manifest, and for more complex upgrade processes we can also use a
feature receiver to make any changes programmatically.
Using PSCONFIG.EXE
We can trigger an upgrade in a few different ways,
including using the psconfig tool to upgrade all features within a farm.
This tool is useful when many features have been updated, since it’s a
pretty lengthy process. For example, if a service pack updates many
system features, running psconfig will ensure that instances of the
updated features are upgraded where appropriate.
Let’s look at several possible psconfig commands. This command performs a version-to-version upgrade:
psconfig.exe -cmd upgrade -inplace v2v
Feature versions are in the format major.minor.build.build.
When using a version-to-version upgrade, only features in which the
major or minor version number has changed will be upgraded. So for a
feature with version 1.0.0.0, if we deploy a new build with the version
1.0.1.234, no upgrade will be performed. However, if we deploy version
1.1.1.234, an upgrade will be performed because the minor version number
has changed.
This command performs a build-to-build upgrade:
psconfig.exe -cmd upgrade -inplace b2b
By using this mode, we ensure that any changes to the
version number will trigger an upgrade. So, for example, version
1.0.0.0 will be upgraded if version 1.0.0.1 is deployed.
Using PowerShell
A quicker way to upgrade an individual feature
instance is to use PowerShell. Follow these steps to see the upgrade
process in action:
Open
the Feature Designer for Feature2. In the Properties pane, set the
version number to 1.0.0.0. Where no version number is specified, a
default of 0.0.0.0 is assumed. Version numbers must contain four
components.
From the Build menu, select Deploy. This will deploy our version 1 solution to the farm.
In
the Feature Designer, click the Manifest button at the bottom of the
page. Expand the Edit Options section to display the Manifest Template.
Replace the template XML with the following:
<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/">
<UpgradeActions>
<VersionRange>
<CustomUpgradeAction Name="MyUpgrade"/>
</VersionRange>
</UpgradeActions>
</Feature>
By attaching this XML to the feature
definition, we’re defining the steps that should be taken to upgrade
existing features. The CustomUpgradeAction element specifies that we’re
using a feature receiver to perform the upgrade programmatically. In
this example, we haven’t specified a version range, so this upgrade
action will apply for all versions. If we needed to include different
upgrade actions for different versions we could add this:
<Feature xmlns="http://schemas.microsoft.com/sharepoint/">
<UpgradeActions>
<VersionRange BeginVersion="1.0.0.0" EndVersion="2.0.0.0">
<CustomUpgradeAction Name="V2Upgrade"/>
</VersionRange>
<VersionRange BeginVersion="2.0.0.0" EndVersion="3.0.0.0">
<CustomUpgradeAction Name="V3Upgrade"/>
</VersionRange>
</UpgradeActions>
</Feature>
In the Properties pane, change the Version number for Feature 2 to 2.0.0.0.
Note
Within the Properties pane are options to set the
Upgrade Actions Receiver Assembly and Class properties. These properties
allow a feature to use a separate assembly for handling standard
feature events such as Activate and Deactivate and a separate assembly
for handling upgrade events. This facility is useful for retrofitting
upgrade capabilities to a feature if the existing receiver assembly
isn’t available or can’t be altered for some reason.
For
the sake of simplicity, we’ll implement our upgrade code in our
existing feature receiver. In the Feature2.EventReceiver.cs file, add
the following code:
public override void FeatureUpgrading(
SPFeatureReceiverProperties properties,
string upgradeActionName,
IDictionary<string, string> parameters)
{
switch (upgradeActionName)
{
case "MyUpgrade":
if (properties.Feature.Parent is SPWeb)
{
SPWeb web = properties.Feature.Parent as SPWeb;
using (Stream s = properties.Definition.GetFile(
"FirstElement\\MyConfig.xml"))
{
using (XmlReader rdr = XmlReader.Create(s))
{
rdr.ReadToDescendant("List");
do
{
string listName = rdr.GetAttribute("name").ToString();
SPList myList = web.Lists.TryGetList(listName);
if (myList != null)
{
myList.Description += "- Updated";
myList.Update();
}
} while (rdr.ReadToNextSibling("List"));
}
}
}
break;
default:
break;
}
}
}
Notice
the use of a switch block in this code snippet to handle the
upgradeActionName. This value is specified in the Name attribute of the
CustomUpgradeAction element in the feature manifest.
If
we deploy our updated feature using Visual Studio, our existing version
will be removed first, which will make it impossible to test our
upgrade process. Instead, we’ll package our solution using Visual Studio
and deploy it manually. From the Build menu, select Package.
To
test our upgrade process quickly, we can use PowerShell to upgrade a
single feature. Choose Start | SharePoint 2010 Management Shell, and
then enter the following script:
update-spsolution -identity Example 19.wsp -literalpath c:\code\example19\→
example19\bin\debug\example19.wsp -gacdeployment
Note
This command should be entered as a single line.
This
command will upgrade the Example19 solution package to the latest
version. We can confirm this by entering the following script:
$featureName="Example19_feature2"
$latestVersion=(get-spfeature|where {$_.DisplayName -eq $featureName}).Version
$web=get-spweb http://<your Server Name>/example19
$theFeature=$web.Features|Where {$_.Definition.DisplayName -eq $featureName}
$currentVersion=theFeature.Version
write-host "Current Version: $currentVersion, Latest Version: $latestVersion"
If all is well, the resultant output should be this:
Current Version: 1.0.0.0, Latest Version: 2.0.0.0
We can upgrade a single feature using the following script:
$web=get-spweb http://<your Server Name>/example19
$theFeature=$web.Features|Where {$_.Definition.DisplayName -eq $featureName}
$theFeature.Upgrade($false)
Any
errors that occur as part of the upgrade process will be shown in the
PowerShell window. However, we can confirm that our upgrade was
successful by issuing the following command:
write-host ($theFeature).Version
The new version number should be reported as 2.0.0.0.
