Upgrade Definition Files
Applies to: SharePoint Foundation 2010
A site upgrade definition provides a means to transform sites that were customized in an earlier version of the SharePoint product so that they can take advantage of new features available in the latest version. An upgrade definition file maps (or "relates") the files and list data of one build or version to a subsequent build or version, as well as specifying additional items that should be included within an upgraded Web sites.
You register an upgrade definition for a site definition by giving it a unique file name, usually starting with the name of the site definition, and placing it in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\Config\Upgrade folder of the setup directory. Site upgrade definitions are registered per site definition, but multiple upgrade definitions may exist for the same site definition. A site upgrade definition also includes list upgrade templates that describe how the particular columns of a list map to content types in the new version of SharePoint Foundation 2010.
A good way to understand upgrade definitions is to study the upgrade definition files that are included in an installation of SharePoint Foundation, which are located in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\Config\Upgrade directory. This directory includes two upgrade templates: An upgrade template that upgrades from the previous version to the current version, and an upgrade template that upgrades between builds of SharePoint Foundation to its final release version.
How SharePoint Foundation Decides Between Upgrade Definitions
When determining if a site is upgradeable, SharePoint Foundation uses the following algorithm to choose which upgrade definition to use when multiple definitions are available:
If the Web site is not of the current product version, SharePoint Foundation chooses an upgrade definition that upgrades across product versions and updates the site to the latest template version. Upgrade definitions perform upgrading actions across versions, or across templates, but not both, which means that a definition cannot have both the FromProductVersion and BeginFromSchemaVersion/EndFromSchemaVersion attributes set. If a Web site is not at the current product version, and no upgrade definition can upgrade the Web site across versions, the Web site cannot be upgraded.
If #1 does not apply, SharePoint Foundation chooses an upgrade definition in which the value of the ToSchemaVersion attribute most closely matches the current template version of the site definition (without surpassing it), and in which the template version of the existing site instance falls in the range between BeginFromSchemaVersion and EndFromSchemaVersion.
If more than one site upgrade definition passes the criteria of #2, SharePoint Foundation chooses the upgrade definition with the highest BeginFromSchemaVersion value.
If there is both a generic language and a specific locale template for a specified site definition, SharePoint Foundation chooses the specific locale template.
Applying the Site Definition Upgrade
SharePoint Foundation uses an upgrade definition to provision converted sites. The process of applying a site definition upgrade must make substitutions for default items, such as follows:
If the navigation nodes for a site definition have not been modified, existing navigation nodes of a previous version are removed and replaced with navigation nodes from the current version's site definition.
The <ListTemplates> section of an Onet.xml or Feature.xml file determines the list templates from which to choose on the Create page. When a site upgrade definition is applied, SharePoint Foundation uses the set of list templates from the current version of the Onet.xml or Feature.xml file, not the files of the previous version, to determine the set of list templates.
Similarly, after upgrade, SharePoint Foundation uses the <DocumentTemplates> section of the new Onet.xml file to determine the set of free document templates that are available, rather than the set of <DocumentTemplate> files of the previous version.
Note
It is recommended that most document templates be associated with content types and not be freestanding.
By default, when you are upgrading an existing Web site, site definition upgrade does not provision modules or list instances from the new site definition. SharePoint Foundation relies on a set of <File> elements to specify how files of a previous version will be mapped to the current version; it also relies on a set of module and list instance tags in the upgrade definition that specify differential files and list data from the previous version to the current one.
Using an upgrade definition allows a Web site to be upgraded consistently to use replacement content types, forms, lists, and pages. If an upgrade definition is not available, SharePoint Foundation upgrades Web sites based on the previous product version, prioritizing as much as possible migration of data and interoperation, at the expense of potentially exposing current version Features (such as content types) to users. This is the default state for all Web sites after mainline version-to-version upgrade tasks (for example, database transforms) have been provisioned.
Assembly References
The web.config file contains policy redirects that map earlier versions of product assemblies (such as Microsoft.SharePoint.dll assemblies in Windows SharePoint Services 3.0) to their equivalents in the current (latest) product version.
Language Packs and Site Definition Upgrade
In version-to-version upgrade, if a particular language pack of a previous version is installed but the corresponding language pack of the current version is not installed before upgrade, the upgrade log records errors. However, the upgrade operation still completes.
See Also
Concepts
Architectural Approaches to Upgrading a Site Definition
Upgrading a Custom Site Definition