Develop new custom site definitions and create upgrade definition files (Windows SharePoint Services)
Updated: February 12, 2008
Applies To: Windows SharePoint Services 3.0
Topic Last Modified: 2008-02-11
In this article:
Before you upgrade sites based on custom site definitions, you must take the following steps to ensure that each list and page that is derived from your custom site definitions will continue working after upgrade.
|If you are not yet ready to upgrade the sites based on a custom site definition (for example, if you obtained the site definition from a solution provider and a new version of that site definition is not yet available), you can use a gradual upgrade to upgrade other sites, and leave the sites based on the previous custom site definition running in the previous environment. Later, when you have a new custom site definition, you can create the upgrade definition file and upgrade only the sites that are based on the new custom site definition.|
Obtain or develop new custom site definitions and custom elements If you want to retain the functionality of sites that are based on a custom site definition, you need a new custom site definition that includes all of the functionality you need, plus any of the new capabilities you want to use. If you obtained a custom site definition or custom elements from a solution provider, check to see if the provider has a new version. If your solution provider does not provide a new version, you might need to develop your own.
Create a site upgrade definition file You also need to create a file that maps the custom elements from your old custom site definition to the new custom site definition, so that each element in your site (for example, a custom page) can upgrade to the appropriate new element.
During the pre-upgrade process, you copy the new custom site definition and any upgrade definition files to the installation directory so that they are available when you upgrade the site collections.
Use this process to create custom site definitions in a development environment. For more information, see the Windows SharePoint Services Software Development Kit (SDK) on MSDN.
Create custom site definitions by starting from a site definition provided with the new environment.
Site definitions are stored in the following folder:
%COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\NAME
Where NAME matches the site definition name (for example, ACTION). Create a folder for your new site definition, and name the new folder using all uppercase letters.
The XML files used to register the site templates are stored in the following location:
%COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\TEMPLATE\LCID\XML\webtempname.xml
Where name matches the site definition name, except that it is in lowercase letters, (for example, action), and where LCID is the locale identifier for the language of the template, (for example, 1033 for United States English).
Test your site definitions in the development environment by creating a new site based on the site definition.
After you have created and tested your new site definitions, you can create the upgrade definition files that map your previous site definitions to the new site definitions.
A site upgrade definition file describes how to map a previous custom site definition to a new site definition. The goal of a site upgrade definition file is to give developers a tool to transform their previous sites into new equivalents that take advantage of all the improvements the new environment has to offer.
An upgrade definition file for a site definition has the following sections:
WebTemplate Specifies upgrade information for the Web template as a whole. In this section, you need one WebTemplate tag per upgrade definition file.
Lists Specifies upgrade information for each list or library in the template. In the Lists section, you need one List tag per list or library.
Files Specifies upgrade information for the individual pages in the template. In the Files section, you need one File tag for each ghosted (uncustomized) page in the template.
AppliedSiteFeature Specifies upgrade information for any site collection-level or subsite-level features included in the template. In the AppliedSiteFeature and AppliedWebFeature sections, you need one Feature tag for each feature at that level in the template.
AppliedWebFeature Specifies upgrade information for any subsite-level features included in the template. In the AppliedWebFeature section, you need one Feature tag for each feature at that level in the template.
Give the upgrade definition file a unique name that begins with the name of the site definition. For example, for a site definition named "STS1," name the upgrade definition file "STS1_upgrade.xml."
Upgrade definition files must be installed in the following folder:
%COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\Config\Upgrade
For more information about creating upgrade definition files, including a sample upgrade definition file, see the Upgrade Definition Files (http://go.microsoft.com/fwlink/?LinkId=109945&clcid=0x409) and Upgrade Definition Schema (http://go.microsoft.com/fwlink/?LinkId=109946&clcid=0x409) topics in the Windows SharePoint Services 3.0 SDK on MSDN.
For more information about deploying upgrade definition files and new site definitions, see Deploy upgrade definition files and new site definitions (Windows SharePoint Services). For additional information about creating upgrade definition files, such as what to include in the files and the schema, see Upgrading Windows SharePoint Services (http://go.microsoft.com/fwlink/?LinkId=98404&clcid=0x409) in the Windows SharePoint Services 3.0 SDK on MSDN.
Record the file names and paths for each upgrade definition file that you need to create on the Custom templates and mapping files worksheet (http://go.microsoft.com/fwlink/?LinkID=73751&clcid=0x409).
This topic is included in the following downloadable book for easier reading and printing:
See the full list of available books at Downloadable books for Windows SharePoint Services.