SharePoint Foundation Upgrade Object Model
Applies to: SharePoint Foundation 2010
This topic describes how Microsoft SharePoint Foundation 2010 and Microsoft SharePoint Server 2010 applications use the Microsoft.SharePoint.Upgrade object model to upgrade deployments. The information provided in this topic is descriptive and is not meant for general public use.
SharePoint Foundation 2010 and SharePoint Server 2010 use the object model of the Microsoft.SharePoint.Upgrade namespace to define upgrade actions for server applications that are built on the SharePoint Foundation 2010 platform when upgrading to the next version or build of SharePoint Foundation. The object model is used to define a sequence of actions to perform various specific tasks in a consistent manner, as required by a server application to upgrade to a new version or build of SharePoint Foundation.
Warning
If you attempt to include custom code as part of the SharePoint Foundation upgrade pipeline, you may cause various problems. For example, because namespace naming must be unique and not overlap with default product names, schema versioning may become confused and lead to a corrupt environment whenever SharePoint Foundation service packs are released. Also, using this object model in a custom upgrade application can have serious effects on performance. The only contexts in which you might use this object model are in build-to-build upgrades of the current version of SharePoint Foundation, or in version-to-version upgrade between the current version and the next version, such as for service packs or a build-to-build upgrade for a custom application.
Instead of using this object model to define upgrade logic, use other means provided in SharePoint Foundation to upgrade a deployment. For example, Feature deployment event handlers allow you to implement custom code for upgrading Features. Whenever possible, use a declarative action in SharePoint Foundation to accomplish a task, rather than writing code. Modify Web Parts individually so that they work in Microsoft SharePoint Foundation 2010. And to upgrade a site definition, use an upgrade definition file (UDF) to define upgrade actions.
Upgrade Classes
The SPAction class is the base class from which other classes are derived for specific needs in an upgrade. For example, the SPDatabaseAction class inherits from SPAction for the specific purpose of defining actions for upgrading databases. An upgrade application may require, for example, that SharePoint Foundation perform 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.
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 implements resources such as the SPManager and SPMigrator classes to access upgrade properties and migrate installations. The SPUpgradeException class is used to trap exceptions specific to SharePoint Foundation.
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 that specifies 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("14.0.1.0")]
[ActionBaseType(typeof(MyWebAppAction))]
[TargetUpgradableObject(typeof(SPWebApplication))]
The TargetSchemaVersion attribute of the sequence matches the TargetSchemaVersion attribute of the latest update action in the action module.
Upgrade Sequences
The SharePoint Foundation upgrade infrastructure defines an interface to upgrade a specific resource or service instance of an application. Each action module is paired with a similarly named action sequence module in a separate directory that defines the appropriate sequence for the action. An upgrade sequence defines a class that inherits from one of the sequence classes provided through the SharePoint Foundation object model and implements or overrides its members. The infrastructure calls upgrade code in a consistent and deterministic manner, in other words, as an upgrade sequence, which means a logical chunk of upgrade code for a single resource.
Warning
SharePoint Foundation does not support overwriting or attempting to append to one of its default upgrade sequences.
Upgrading proceeds sequentially, beginning with items that are positioned higher in the logical hierarchy (closer to the root), but the process actually upgrades items at lower levels first (for example, the database before other objects) until an entire server farm has been upgraded. The upgrade process starts by upgrading the configuration database and SharePoint Central Administration, as well as data specific to each server in the farm, and then runs on each Web application to upgrade each site collection until all Web sites in all the site collections of each Web application are upgraded. Each Web application of the previous version is thereby upgraded one-by-one to a Web application in the current version, as are the content databases that support their site collections.
An upgrade sequence consists of one or more upgrade actions discovered at run time that need to be taken to upgrade a specific feature. SharePoint Foundation accepts a resource instance or a set of resource instances, determines which upgrade sequences need to operate on the resources based on loaded assemblies that are specified in configuration files, and runs the sequences on the selected resources. The sequences are ordered according to the information specified in the configuration files.
SharePoint Foundation upgrade is data-driven, which means that resources registered as upgradeable in the configuration database are upgraded in a specific order. Objects such as site collections may have several upgrade sequences. There may be upgrade sequences for Web applications (virtual servers), content databases, or shared services, and so on. An upgradeable object has built-in schema versioning, allows for provisioning of upgrade dependencies, and has properties that determine whether the current object needs to be upgraded and whether to upgrade it.
The upgrade infrastructure includes an interface definition for upgradeable objects that upgrades a specific resource. Based on resources that need to be upgraded, upgrade sequences (or plug-ins) implement this interface so that upgrade code can be called. Upgrade sequences can be run any number of times on a given server. An upgrade sequence determines whether any action needs to be taken at any given time, and it also, in case of errors, provides adequate check-pointing to allow resumption of upgrade from a certain point the next time the upgrade code is run. Upgrade sequences create logs and report errors and progress back to the user interface.
Configuration Files
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. SharePoint Foundation includes default configuration files in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\Config\Upgrade folder that it uses to define the range of product versions and schema versions to which an upgrade applies, to register the assembly that defines classes for upgrade, to map old files to specified locations in the SharePoint Foundation 2010 setup directory, and to deprecate features that are included in the old version.
See Also
Reference
Concepts
Sample Outline for Upgrade Actions