SPFeature.Upgrade Method
Upgrades this Feature to the currently installed version of the Feature definition, optionally ignoring an exception if one is thrown.
Namespace: Microsoft.SharePoint
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: No
Available in SharePoint Online
Syntax
'Declaration
<SubsetCallableExcludeMemberAttribute(SubsetCallableExcludeMemberType.GenericMethod)> _
Public Function Upgrade ( _
force As Boolean _
) As IEnumerable(Of Exception)
'Usage
Dim instance As SPFeature
Dim force As Boolean
Dim returnValue As IEnumerable(Of Exception)
returnValue = instance.Upgrade(force)
[SubsetCallableExcludeMemberAttribute(SubsetCallableExcludeMemberType.GenericMethod)]
public IEnumerable<Exception> Upgrade(
bool force
)
Parameters
force
Type: System.BooleanIf true and an exception occurs that would normally block the upgrade of the Feature, the exception is logged and ignored. An attempt is then made to upgrade the Feature despite the exception. This attempt may or may not succeed, depending on which exception is ignored.
Return Value
Type: System.Collections.Generic.IEnumerable<Exception>
A collection of exceptions thrown during the upgrade. Because the exceptions occurred but did not block the upgrade of the Feature, they are essentially warnings that can be logged and reviewed if desired. If an exception occurs that does block the upgrade, the exception is not included in this collection but instead is passed directly to the caller for handling.
Remarks
You can use this method on each Feature in the collection returned by the QueryFeatures method of the SPSite, SPWebApplication, SPWebService, and SPContentDatabase classes. These methods can return a collection of Features that need to be upgraded. You can iterate through that collection and call the Upgrade method to upgrade the features in the collection.
Examples
The following example gets a farm-wide collection that contains all instances of a Feature that need to be upgraded. The code then iterates through the collection and upgrades the Feature.
// Represent the ID of the Feature we want to upgrade.
Guid featureId = new Guid("1B006A62-7B92-475c-A2E5-A1CF03EE0887");
// Get the default Web service in the farm.
SPWebService webService = SPFarm.Local.Services.GetValue<SPWebService>("");
// Get all Feature instances with the specified ID that require upgrade.
SPFeatureQueryResultCollection features = webService.QueryFeatures(featureId, true);
// Get a Features enumerator.
IEnumerator<SPFeature> featureEnumerator = features.GetEnumerator();
while (featureEnumerator.MoveNext())
{
// Get current Feature.
SPFeature feature = featureEnumerator.Current;
// Upgrade the current Feature.
Console.WriteLine("Upgrading Feature {0} with ID {1}.",
feature.Definition.DisplayName, feature.DefinitionId);
Console.WriteLine("Feature Version Before Upgrade: {0}", feature.Version);
feature.Upgrade(false);
Console.WriteLine("Feature Version After Upgrade: {0}", feature.Version);
}
' Represent the ID of the Feature we want to upgrade.
Dim featureId As New Guid("1B006A62-7B92-475c-A2E5-A1CF03EE0887")
' Get the default Web service in the farm.
Dim webService As SPWebService = SPFarm.Local.Services.GetValue(Of SPWebService)("")
' Get all Feature instances with the specified ID that require upgrade.
Dim features As SPFeatureQueryResultCollection = webService.QueryFeatures(featureId, True)
' Get a Features enumerator.
Dim featureEnumerator As IEnumerator(Of SPFeature) = features.GetEnumerator()
Do While featureEnumerator.MoveNext()
' Get current Feature.
Dim feature As SPFeature = featureEnumerator.Current
' Upgrade the current Feature.
Console.WriteLine("Upgrading Feature {0} with ID {1}.", feature.Definition.DisplayName, feature.DefinitionId)
Console.WriteLine("Feature Version Before Upgrade: {0}", feature.Version)
feature.Upgrade(False)
Console.WriteLine("Feature Version After Upgrade: {0}", feature.Version)
Loop