Using the Object Model to Upgrade

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The object model of the Microsoft.SharePoint.Upgrade namespace provides a means to define upgrade actions for an application built upon the Microsoft Windows SharePoint Services platform when upgrading to the next version or build of SharePoint. You define a sequence of actions to perform various specific tasks in a consistent manner as required by an application to upgrade to a new version or build of Windows SharePoint Services.

Upgrade Classes

The SPAction class is the base class from which to derive custom classes designed for specific needs in an upgrade. You can create classes that inherit from SPAction, or use the SPDatabaseAction class in the specific case of defining actions for upgrading databases. Override the Upgrade method to execute upgrade logic.

The SPSequence class is the ultimate base class for the other sequence classes in the Microsoft.SharePoint.Upgrade namespace, which includes SPActionSequence, from which derives SPDatabaseSequence, SPIisWebSiteSequence, SPPersistedObjectSequence, and SPSiteSequence. The object model also provides resources such as the SPManager and SPMigrator classes to access upgrade properties and migrate installations. Use the SPUpgradeException class to trap exceptions specific to Windows SharePoint Services.

A good practice is to create a super class that derives from an action or sequence class of the Microsoft.SharePoint.Upgrade namespace, and create other classes that derive from your super class to perform specific upgrade actions. A custom upgrade application may require, for example, actions for upgrading a server farm, as well as actions that upgrade Internet Information Services (IIS) Web sites, databases, SharePoint site collections, Web applications, and servers.

An upgrade sequence class has attribution that specifies the base type of upgrade action to load and run. Each upgrade action has a version attribute tag like the following that helps to identify whether a particular upgrade action needs to run or not, by comparing the current version of the resource being upgraded with the target version of the upgrade action. The version attribute tag is also used in sorting the individual upgrade actions.

[TargetSchemaVersion("12.0.1.0")]
[ActionBaseType(typeof(MyWebAppAction))]
[TargetUpgradableObject(typeof(SPWebApplication))]

The TargetSchemaVersion attribute of the sequence must match the TargetSchemaVersion attribute of the latest update action in the action module.

Configuration Files

After you create classes that derive from classes in the Microsoft.SharePoint.Upgrade namespace, you can register your assembly by creating a configuration file in the Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\12\Config\Upgrade folder. A configuration file is an XML file that indicates the DLL and class names for all plug-ins. These files are used at run-time to instantiate the correct classes and execute them by using reflection.

A configuration file looks like the following:

<?xml version='1.0'?>
<Config xmlns="urn:Microsoft.SharePoint.Upgrade">
  <Assembly Name="Microsoft.Office.Server, Version=12.0.0.0, Culture=neutral, PublicKeyToken=94de0004b6e3fcc5, Custom=null">     <Order>3</Order>
  </Assembly>
</Config>

The Name attribute in the Assembly tag indicates the name of an assembly that contains the upgrade sequence for a particular upgradeable resource. The Order node indicates the order of this sequence with respect to the upgrade sequence of another resource of the same type. For example, a Windows SharePoint Services upgrade sequence has an order 1 and runs before any other upgrade sequence.