Develop new custom site definitions and create upgrade definition files (Windows SharePoint Services)

Applies To: Windows SharePoint Services 3.0

Topic Last Modified: 2008-02-11

In this article:

• Before you develop new custom site definitions

• Develop new custom site definitions

• About upgrade definition files

• Create upgrade definition files

• Record upgrade definition file information on a worksheet

Before you develop new custom site definitions

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.

1. **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.

2. **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.

Develop new custom site definitions

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.

1. 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).

2. 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.

About upgrade definition files

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.

Create upgrade definition files

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 (https://go.microsoft.com/fwlink/?LinkId=109945&clcid=0x409) and Upgrade Definition Schema (https://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 (https://go.microsoft.com/fwlink/?LinkId=98404&clcid=0x409) in the Windows SharePoint Services 3.0 SDK on MSDN.

Record upgrade definition file information on a worksheet

Record the file names and paths for each upgrade definition file that you need to create on the Custom templates and mapping files worksheet (https://go.microsoft.com/fwlink/?LinkID=73751&clcid=0x409).

Download this book

This topic is included in the following downloadable book for easier reading and printing:

• Upgrading Windows SharePoint Services

See the full list of available books at Downloadable books for Windows SharePoint Services.