Upgrading a Farm Solution in SharePoint 2010

Last modified: January 11, 2011

Applies to: SharePoint Foundation 2010

This topic explains how farm solutions can be updated.

There are two ways to upgrade a farm solution. Which one is used depends on what kinds of changes have been made in the newer version of the solution.

  • Replacement: The old version of the solution is retracted, and optionally removed from the farm solution store. The new version is then added to the solution store and deployed. It is not necessary that the new solution package (.wsp file) have the same name or GUID as the old version, however, if the old version is retracted but not removed from the solution store, then the new version must have a different filename and GUID. This kind of upgrade must be used if the new version of the solution differs from the installed version in any of the following ways.

    • The new version removes a Feature that was in the old version or adds a Feature that was not in the old version.

    • The new version changes the ID of a Feature.

    • The new version changes the scope of a Feature.

    • The new version has a changed version of a Feature Receiver.

    • The new version adds a new elements.xml file, removes an elements.xml file, or changes the contents of an existing elements.xml file.

    • The new version adds a new Property element to a Feature.xml file, removes a Property element from a Feature.xml file or changes the value of a Property element in a Feature.xml file.

    For details on retraction and deployment, see Uninstallation and Retraction of a Farm Solution and Installation and Deployment of a Farm Solution in SharePoint 2010.

  • Update: A new version of the solution package is installed and deployed which has a different file name but the same GUID as the old version. The Microsoft SharePoint Foundation deployment infrastructure detects that the GUIDs are the same. It automatically retracts the old version before deploying the new version. If there are Features in the solution, then the new and old versions have the same set of Features and they remain activated but assemblies and certain other files in them are updated with the versions from the new solution package.

    Each time a solution is successfully upgraded, the previous version of the solution is backed up and stored in the configuration store. This backup is used by the solution framework in the case of an upgrade failure. Only a single backup copy is stored per solution.

    Farm administrators perform an update type of upgrade with the Update-SPSolution command in SharePoint Management Shell.

Performing a Replacement upgrade programmatically is the same as programmatically retracting the old solution and then adding and deploying the new version. To perform an Update type of upgrade programmatically, your code calls one of the overloads of the SPSolution.Upgrade() method. For this method to run, a solution must be present in the solution store. It may or may not already be deployed.

If the solution is not deployed, call the SPSolution.Upgrade(String) method to update the solution in the solution store. If the solution is deployed, call the SPSolution.Upgrade(String, DateTime) method to start the timer job for upgrade. In either case, a backup of the old version of the solution is created.