Upgrade Definition Files
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.
A site upgrade definition provides a means to transform sites customized in the previous version of Windows SharePoint Services so that they take advantage of features in the new version. An upgrade definition file maps 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 placed within 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 \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, which describe how the particular columns of a list map to content types in the new version of Windows SharePoint Services.
A good way to understand upgrade definitions is to study the upgrade definition files that are included in an installation of Windows SharePoint Services, which are located in the C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Config\Upgrade directory. This directory includes two upgrade templates: An upgrade template that upgrades from version 2 to version 3 and an upgrade template that upgrades between builds from Beta 2 of Windows SharePoint Services to its final release version.
How Windows SharePoint Services Decides Between Upgrade Definitions
When determining if a site is upgradeable, Windows SharePoint Services uses the following algorithm to choose which upgrade definition to use when multiple definitions are available:
If the Web site is not at the current product version, Windows SharePoint Services chooses an upgrade definition that upgrades across product versions and updates the site to the latest schema version. Upgrade definitions perform upgrading across versions, or across schemas, 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, Windows SharePoint Services chooses an upgrade definition in which the value of the ToSchemaVersion attribute most closely matches the current schema version of the site definition (without surpassing it), and in which the schema 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, Windows SharePoint Services chooses the upgrade definition with the highest BeginFromSchemaVersion value.
If there is both a generic language and a specific locale template for a given site definition, Windows SharePoint Services chooses the specific locale template.
Applying the Site Definition Upgrade
Windows SharePoint Services uses an upgrade definition to provision converted sites. The process of applying a site definition upgrade must make switches for default items, such as follows:
If the navigation nodes for a site definition have not been modified, existing version 2 navigation nodes are removed and replaced with navigation nodes from the version 3 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, Windows SharePoint Services uses the set of list templates from the version 3 ONET.XML or Feature.xml file, not the version 2 files, to determine the set of list templates.
Similarly, after upgrade, Windows SharePoint Services uses the DocumentTemplates section of the new ONET.XML file to determine the set of free document templates that are available, rather than the version 2 set of DocumentTemplate files.
Note
In version 3, we recommend 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. Windows SharePoint Services relies on a set of File elements to specify how version 2 files map to version 3, and on a set of module and list instance tags in the upgrade definition that specify differential files and list data from version 2 to version 3.
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, Windows SharePoint Services upgrades Web sites based on version 2, prioritizing as much as possible migration of data and interoperation, at the expense of potentially exposing version 3 Features (such as content types) to users. This is the default state for all Web sites after mainline version 2 to version 3 upgrade tasks (for example, database transforms) have been provisioned.
Assembly References
In version 3, the web.config file contains policy redirects that map version 2 Windows SharePoint Services assemblies, such as Microsoft.SharePoint.dll, to their version 3 equivalents.
Language Packs and Site Definition Upgrade
In version-to-version upgrade, if a particular version 2 language pack is installed but its corresponding version 3 language pack is not installed before upgrade, the upgrade log records errors. However, the upgrade operation still completes.