Microsoft Press: Upgrading Site Customizations and Custom Site Definitions

Applies To: Windows SharePoint Services 3.0


This book excerpt is from Microsoft Office SharePoint Server 2007 Administrator’s Companion, Microsoft Press, January 2007.

Buy this book

Microsoft Office SharePoint Server 2007 Administrator’s Companion is a comprehensive reference that details features and capabilities of Microsoft Office SharePoint Server 2007. It delivers the easy-to-follow procedures, practical workarounds, and key troubleshooting tactics that you need for on-the-job results.


Bill English MCSE, MCT, CTT+, GSEC certified, is a Microsoft MVP for Microsoft Office SharePoint Server. He is president of MindSharp, a leading training and consulting company for SharePoint Products and Technologies, and the author of several books about Office SharePoint Portal Server.

The Microsoft SharePoint Community Experts include Microsoft MVPs, real-world practitioners, and members of the Microsoft teams that develop and support SharePoint Products and Technologies.

Book excerpt -- Chapter 25: Upgrading Site Customizations and Custom Site Definitions

Site definitions have changed dramatically in Microsoft Windows SharePoint Services 3.0. The first thing that you will notice is that they are much smaller. If your organization’s development team created custom site definitions in Windows SharePoint Services 2.0, they need to know how to upgrade them and map them to a new Windows SharePoint Services 3.0 site definition. This knowledge will enable you to retain customizations and also take advantage of the new functionality Windows SharePoint Services 3.0 has to offer.

Although this book is written primarily for administrators of Microsoft Office SharePoint Server 2007, we recognize that there are an increasing number of administrators who are also tasked with development-oriented activities in their job. Increasingly, in our contact with SharePoint Technologies administrators, we encounter administrators who maintain dual skill sets in both administration and development. Precisely because we know that customizing a Windows SharePoint Services 3.0 site at the site-definition level is a skill set many of the readers of this book will need, this chapter is development oriented.

Windows SharePoint Services 2.0 Site Definitions and Unghosting

SharePoint sites are different from standard Web sites that you might find on the Internet or on an intranet. Typically, when you create a Web site, you create a file for every page that you want to display. Each page in the Web site has a corresponding HTML page or an ASP.NET page (ASPX). Internet Information Services (IIS) Web sites point to the folder containing the files. But SharePoint sites are different. They are simply rows in a database table storing the metadata about each site, area, or workspace. Each site listed in the Docs table in the contents database contains the setup path to a Default.aspx file hosted on the file system of the Web server, allowing us to make a single change to one Default.aspx page that affects every site that uses the page. The Default.aspx file, along with some other XML files, make up a site definition. The 60 hive is where these site definitions live. Each site definition contains the following folders and files:

  • DOCTEMP folder The DOCTEMP folder contains subfolders for each Office application. You will notice a folder for Word, Excel, PowerPoint, FrontPage, InfoPath, Blank Web Part Pages, and Smart Pages. (These have abbreviated names. For example, Excel is XL.) Each subfolder contains the templates that are used in the document libraries to create a document when you click the New Document button. Upon creation of a document library, a default template is chosen and copied from the DOCTEMP\application_name folder and to the Forms folder in the document library. You can view the template file in the Forms folder by using the Explorer view for a document library.

  • LISTS folder The LISTS folder contains the list definitions that are used by the site definition. Each list contains a Schema.xml file and a collection of .aspx pages that are used to view, edit, and create the list items. The Schema.xml file describes the fields and views that the list will use.

  • XML folder The XML folder contains the core Site Definitions File (ONET.XML), STDVIEW.XML, and VWSTYLES.XML. STDVIEW.XML describes the views that you can create, such as Standard View, Calendar View, and DataSheet View. The VWSTYLES.XML files describe the styles that you can apply to each view, such as the Newsletter, Newsletter No Labels, Boxed, Boxed No Labels, Shaded, and Default Views styles.

  • Default.aspx file The Default.aspx file is referred to by the site in the docs table of the content database. This file is responsible for creating the table structure and Web Part zones of a site.

Figure 25-1 shows an image of the 60 hive folder and how you can access it, as well as where to find the site definitions.

Figure 25-1_ The 60 hive folder

Web server example of 60 hive folder


The term 60 hive refers to a folder location of the SharePoint Web front-end server. It can be found by browsing to %SystemDrive%\Program Files\Common Files\Microsoft Shared\Web server extensions\60. Also, LCID is an acronym for "Local Culture Identifier," and 1033 is the LCID for English (US).

IIS was modified in Windows SharePoint Services 2.0 to look in the Content database for the majority of the files it renders. If you look at the local path for the Virtual Servers Home directory, you will find a Web.config file, but you won’t find any .aspx pages. These .aspx pages are accessed by IIS from the Content database. When a site is accessed, IIS looks in the Content database for the relevant site, which then references the Default.aspx in the site definition in the 60 hive. If you need to create some custom .aspx files or some user controls, you need to create an excluded managed path by using the Define Managed Paths option in the Virtual Server Settings page in SharePoint Central Administration. UserControl Virtual Directories were common in Microsoft SharePoint Products and Technologies 2003 if your developers created user controls that were loaded by a custom Web Part.

Team Sites, Blank Sites, and Document Workspaces are site definition configurations that are stored in the 60\TEMPLATE\LCID\STS folder. Meeting Workspaces—such as Basic Meeting Workspace, Blank Meeting Workspace, Decision Meeting Workspace, Social Meeting Workspace, and MultiPage Meeting Workspace—are all configurations of the 60\TEMPLATE\LCID\MPS folder. STS and MPS contain a Default.aspx file and a collection of XML files, including the ONET.XML file, which forms the site definition. Ghosted site is the term used for a site that doesn’t actually have its own copy of the Default.aspx and instead points to the Default.aspx on the file system of the SharePoint server.

Windows SharePoint Services 2.0 allows each user who has Contributor rights to modify her own personal view of each page, and also modify the personal properties of a Web Part. SharePoint keeps track of these changes by storing them in a Personalization table in the Content database. If the permission has been granted, users who have at least contributor rights can also create their own sites in Windows SharePoint Services 2.0. Site definitions empower users to create sites for themselves through the user interface, meaning they no longer need to ask Web developers to create a site for them.

Unghosted pages are the result of modifying a ghosted, or default, page in Microsoft FrontPage 2003 or any Web-page editing tool that can edit Windows SharePoint Services 2.0–based pages. Unghosting a page means that instead of saving changes to the Default.aspx file in the 60 hive, a copy of the file is made and stored as a customized page for that site in the content database. Microsoft, therefore, had to address this in SharePoint Server 2007 so that when we upgrade from Windows SharePoint Services 2.0 to version 3.0, the customized default.aspx pages that are in the Content database that require updating can be updated in such a manner to include the 2007 functionality.

The upgrade action on the SharePoint code base changes the default.aspx in the site definition, allowing ghosted sites to receive new functionality. If the default.aspx page is copied and stored in the content database, the unghosted page won’t receive the new SharePoint Server 2007 functionality.

Microsoft has provided better ways of customizing sites in Windows SharePoint Services 3.0. Master pages are used across all Web sites, which means that developers can change a master page to effect changes across multiple Web sites from a single location instead of changing each site directly. SharePoint Designer 2007 is the replacement for Microsoft FrontPage 2003. It provides developers and power users with even more tools for customizing their sites, allowing them to perform such tasks as creating and applying workflows, using the Data Form Web Part, and customizing master pages. Although unghosting still occurs, it is less of a problem if the customization results are something you don’t like because the site can be reset to its original site definition using the Site Settings option of Reset To Site Definition. Selecting this option will undo all the changes that have been made to the site in a single administrative action. This feature gives us a way to undo customizations that have been committed on the site.

Custom Site Definitions

In this section, you will learn about Windows SharePoint Services 2.0 custom site definitions so that you have a better understanding of how to upgrade them later in this chapter.

A custom site definition is usually created by a developer and involves an understanding of Collaborative Application Markup Language (CAML). The process usually involves heavily modifying XML files. In Windows SharePoint Services 2.0, custom site definitions are created so that you could incorporate the following:

  • Custom cascading style sheet (CSS) files

  • Additional or modified Web Part zones

  • Custom list definitions

  • Modified navigation

  • Custom Web Parts

  • Additional resources, such as ASPX pages

  • Changes to the base types of the lists

In Figure 25-2, you can see how a custom list named Targets has been added into the ONET.XML file so that the Custom List can be created from the Create page in a team site.

Figure 25-2_ STSCONTOSOSALES Custom Site Definition ONET.xml file including a Custom List

Custom Site Definition example inclu custom list

Making these changes usually involves modifying the ONET.XML or Default.aspx file stored in each site definition, but it can also involve deploying extra .aspx pages, CSS files, XML files, and Web Parts.

Custom site definitions are created by copying and pasting an existing site definition, such as STS, to a neutral location and then making changes to the copy. For example, you can copy the STS folder in 60\TEMPLATE\LCID to 60\TEMPLATE\LCID\STSCUSTOM. This avoids overwriting the changes to the contents of the STS folder by Microsoft in the form of a service pack or upgrade. It also preserves the default site definition so that it can be copied to other locations and modified differently for different purposes.

The custom site definition is then made available to the Template Selection page by creating a copy of the WEBTEMP.XML file found in 60\TEMPLATE\1033\XML in 60\TEMPLATE\1033\XML\WEBTEMPCUSTOM.XML. Remember, it is the WEBTEMP.XML file that is responsible for making custom site definitions available to the Template Selection page. You can name it anything, as long as it is prefixed with “WEBTEMP” (without the quotation marks). SharePoint Portal Server 2003 has a similar file called WEBTEMPSPS.XML. Figure 25-3 is an illustration of a WEBTEMP.XML file. You can see the two site definitions that are referred to: STS and MPS. Note that each site definition has multiple configurations.

Figure 25-3_ The WEBTEMP.XML file

The WEBTEMP.XML file screen

Real World

  Using SharePoint Template Packages Instead of Site Definitions

In SharePoint Products and Technologies 2003, creating custom site definitions is a developer’s responsibility, and rolling out custom site definitions is often an administrator’s responsibility because it involves having access to the server and requires resetting IIS.

Custom site templates (STPs) are often created as an alternative to custom site definitions because they can be created using the SharePoint user interface and are basically a modification to the underlying site definition. The STP file is saved to the Site Template Gallery in the top-level site of a site collection. STP files can be made available globally using STSADM.exe (""C:\Program Files\Common Files\Microsoft Shared\Web server extensions\60\BIN\STSADM.exe" -o addtemplate -filename "templatename.stp" -title "templatetitle" -description "templatedescription" ").

Custom site definitions will always perform better than a site template. However, using site templates doesn’t involve heavy modification of XML files, and you don’t need to be a programmer to create them. If you just want to make a small change to a site but reuse the changes for future sites, a site template can be an ideal solution.

Exploring Windows SharePoint Services 3.0 Site Definitions

In Windows SharePoint Services 3.0, site definitions are now streamlined. Lists, Document Library templates, and View styles are no longer part of a site definition. All these files have now moved to a more centralized location in the 12 hive. List definitions are now features and can be found in the Features folder under 12\TEMPLATE. List pages are in a Pages folder under 12\TEMPLATE, and the DOCTEMP folder is available in 12\TEMPLATE\1033\STS folder, even though the STS site definition itself is stored in the 12\TEMPLATE\sitetemplates folder. Features are reusable components that can be used to roll out list definitions, content types, workflow, custom actions, Web Parts, and even services such as the Excel Server Service. Rather than each site definition having its own copy of all the list definitions, each site definition simply installs and activates the required features for that particular type of site. This leaves a Site Definition folder with just the Default.aspx file and an ONET.XML file to form the STS site definition. Figure 25-4 displays some of the features in the FEATURES folder.

Figure 25-4_ The FEATURES folder

Features listed Features folder

Some site definitions do contain a LISTS folder. These site definitions include WIKI, BLOG, CENTRALADMIN, MPS, SPSMSITEHOST, SPSREPORTCENTER, SPSSITES, and SRCHCEN. However, site definitions do not duplicate any lists like they did in Windows SharePoint Services 2.0. They just add to the lists that are created as features, avoiding the duplication of files that occurred in Windows SharePoint Services 2.0.

Inside the ONET.XML file, there are many changes. For example, the NavBars element uses a resource for each navigation bar. The following NavBars element that has been taken from the STS site definition in Windows SharePoint Services 3.0 shows the reference to a resource for each navigation bar:

  <NavBar Name="$Resources:core,category_Top;" ID="1002" /> 
  <NavBar Name="$Resources:core,category_Documents;" ID="1004" /> 
  <NavBar Name="$Resources:core,category_Pictures;" ID="1005" /> 
  <NavBar Name="$Resources:core,category_Lists;" ID="1003" /> 
  <NavBar Name="$Resources:core,category_Discussions;" ID="1006" /> 
  <NavBar Name="$Resources:core,category_Surveys;" ID="1007" /> 
  <NavBar Name="$Resources:core,category_Sites;" ID="1026" /> 
  <NavBar Name="$Resources:core,category_People;" ID="1027" /> 

For site definitions that do have a LISTS folder, as mentioned above, a ListElement exists for each of the additional list definitions. Some Windows SharePoint Services 3.0 site definitions do contain a LISTS folder which is the same as all the Windows SharePoint Services 2.0 site definitions. The ListTemplates element isn’t used in the STS site definition, as all of its lists are rolled out using features. The following example is taken from an SPSSITES site definition in Windows SharePoint Services 3.0 and shows where the ListTemplates element registers the sites list, which is a list definition stored in SPSSITES\LISTS:

  <ListTemplate Name="siteslst"
DisplayName="$Resources:spscore,SitesOnet_SitesListName;" FolderCreation="FALSE"
 Type="300" BaseType="0" OnQuickLaunch="FALSE" SecurityBits="11"
Image="/_layouts/images/itgen.gif" />  
  <ListTemplate Name="Tabs"
DisplayName="$Resources:spscore,SitesOnet_TabsListName;" FolderCreation="FALSE"
Type="301" BaseType="0" OnQuickLaunch="FALSE" SecurityBits="11"
Image="/_layouts/images/itgen.gif" />  


You can create features to allow for customization of newly created and existing sites without having to completely create new Site Definition folders. Features are explained in more detail later in this chapter.

The purpose of the DocumentTemplates element is the same in the two versions. When you create a document library, the template that is used to create the library resides in the DOCTEMP folder. A copy of this template is then stored in a folder named Forms in the document library. The following example of the DocumentTemplateFiles element shows how the Wdtmpl.doc template is copied from the DOCTEMP folder in the 12 hive to the Forms folder in a document library and is renamed as part of the process to Template.doc:

  <DocumentTemplateFile Name="doctemp\word\wdtmpl.doc" TargetName="Forms/ template.doc" Default="TRUE" />  

The STS site definition has three configurations: Team Site, Blank Site, and Document Workspace. Regardless of which of the three configurations you select from the Template Selection page, your site will still use STS. However, each configuration receives different lists and Web Parts. A configuration element is shown below, displaying the use of features to roll out lists and Web Parts:

  <Configuration ID="-1" Name="NewWeb" />  
  <Configuration ID="0" Name="Default"> 
<List Title="$Resources:spscore,SitesOnet_SitesList_Title;"
Description="$Resources:spscore,SitesOnet_SitesList_Description;" Url="SitesList"  Type="300"> 
  <Field Name="Title">$Resources:spscore,SetupMySite;</Field>  
  <Field Name="URL">~site/_layouts/ mysite.aspx?Redirect=1, $Resources:spscore,SetupMySite;</Field>  
  <Field Name="TasksAndTools"> 
  <Field Name="_ModerationStatus">0</Field>  
  <List Name="Tabs"  
Title="$Resources:spscore,SitesOnet_TabsList_Title;" Url="Tabs"
  <Field Name="TabName">$Resources:spscore,CategoriesTab;</Field>  
  <Field Name="Page">category.aspx</Field>  
  <Field Name="Comments">$Resources:spscore,CategoriesTabComment; 
  <Field Name="TabName">$Resources:spscore,CategoriesTab;</Field>  
  <Field Name="Page">categoryresults.aspx</Field>  
  <Field Name="Comments">$Resources:spscore,CategoriesTabComment; 
  <Field Name="TabName">$Resources:spscore,TopSitesTab;</Field>  
  <Field Name="Page">topsites.aspx</Field>  
  <Field Name="Comments">$Resources:spscore,TopSitesTabComment; 
  <Field Name="TabName">$Resources:spscore,SiteMapTab;</Field>  
  <Field Name="Page">sitemap.aspx</Field>  
  <Field Name="Comments">$Resources:spscore,SiteMapTabComment; 
  <Feature ID="F6924D36-2FA8-4f0b-B16D-06B7250180FA" />  
  <!--  Base site feature  
  <Feature ID="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" />  
  <Feature ID="22A9EF51-737B-4ff2-9346-694633FE4416"> 
  <Properties xmlns=""> 
  <Property Key="ChromeMasterUrl" Value="" />  
  <Property Key="WelcomePageUrl"
Value="$Resources:cmscore,List_Pages_UrlName;/category.aspx" />  
  <Property Key="PagesListUrl" Value="" />  
  <Property Key="AllowedSubSiteTemplates" Value="" />  
  <Property Key="AllowedPageLayouts" Value="" />  
  <Property Key="EnableVersioningOnPages" Value="true" />  
  <Property Key="EnableModerationOnPages" Value="true" />  
  <Property Key="EnableApprovalWorkflowOnPages" Value="false" />  
  <Property Key="RequireCheckoutOnPages" Value="true" />  
  <Feature ID="8F15B342-80B1-4508-8641-0751E2B55CA6" />  
  <Feature ID="541F5F57-C847-4e16-B59A-B31E90E6F9EA"> 
  <Properties xmlns=""> 
  <Property Key="IncludePages" Value="false" />  
  <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />  
  <Module Name="Default" />  

In comparison to a Windows SharePoint Services 2.0 site definition, this file is now much smaller and can be changed more easily through the use of features.

Windows SharePoint Services 2.0 Site Definitions versus Windows SharePoint Services 3.0 Site Definitions

Table 25-1 lists some of the major differences between the Windows SharePoint Services 2.0 site definitions and the Windows SharePoint Services 3.0 site definitions.

Table 25-1_ Comparison of Site Definitions in WSSv2 and WSSv3

Element Windows SharePoint Services 2.0 Windows SharePoint Services 3.0




NavBars element



ListTemplates element



DocumentTemplate files















Other differences between the site definitions include the following items:

  • The DOCTEMP folder is no longer stored as part of the STS site definition.

  • Defaultdws.aspx is included in the STS folder beside Default.aspx. In version 2.0, it was stored as Default.aspx in a DWS folder.


    Defaultdws.aspx is the Document Workspace version of a team sites Default.aspx file.

  • The Default.aspx file contains less code due to the use of master pages and placeholders. Every Default.aspx page is based on Default.master or mwsdefault.master, which can be found in 12\TEMPLATE\1033\Global.


    Mwsdefault.master is the master page file for the meeting workspaces.

Upgrading a site definition from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0 requires some work so that you can still incorporate your original customizations and inherit the new features of SharePoint Server 2007. In the next section, you will learn the possible methods of upgrading your site definitions.

Upgrading Your Customized Windows SharePoint Services 2.0 Site Definitions to Windows SharePoint Services 3.0

As you have learned, Windows SharePoint Services 3.0 site definitions are quite different from Windows SharePoint Services 2.0 site definitions, and therefore you must make many changes to a Windows SharePoint Services 2.0 customized site definition to make it function properly in Windows SharePoint Services 3.0.

When you upgrade your site definitions from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0, you have two options:

  1. Create or copy your custom site definition changes into a new Windows SharePoint Services 3.0 site definition.

  2. Take the functionality from Windows SharePoint Services 3.0 site definitions, and place it into your custom Windows SharePoint Services 2.0 site definition.

If you create a custom list and use a site definition to roll it out, the easiest option is to add your custom list to a new Windows SharePoint Services 3.0 site definition. However, a more advanced custom site definition might warrant adding the Windows SharePoint Services 3.0 functionality into your Windows SharePoint Services 2.0 custom definition. Keep in mind that you will have to incorporate features, content types, master pages, and the SPWebPartManager control into your version 2.0 custom site definition so that you can use ASP.NET 2.0 Web Parts and get the functionality and look and feel of the version 3.0 site definition.

In most cases, you’ll end up choosing to upgrade your version 2.0 site definition to version 3.0 because overall, it will be easier to do this and result in you running on a version 3.0 platform. Table 25-2 lists the high-level steps involved in upgrading your Windows SharePoint Services 2.0 custom site definitions to Windows SharePoint Services 3.0 site definitions and the reasons for taking the steps.

Table 25-2_ Steps for Upgrading WSSv2 Custom Site Definitions to WSSv3 Custom Site Definitions.

Step Reason

Merge your Windows SharePoint Services 2.0 site definition customizations into a Windows SharePoint Services 3.0 site definition. There are two ways to do this:

Add your Windows SharePoint Services 2.0 changes to a Windows SharePoint Services 3.0 site definition, or add the new Windows SharePoint Services 3.0 features to your Windows SharePoint Services 2.0 site definition.

To incorporate your customizations and the new SharePoint Server 2007 functionality.

Transform your custom list definitions into features.

Windows SharePoint Services 3.0 rolls out list definitions as features. Users are then able to activate or deactivate the feature.

Administrators are able to re-use the features throughout SharePoint.

Build a feature to roll out any custom Web Parts.

Features can be used to roll out lists and functionality across multiple sites. Features are an excellent way to make any type of new list or functionality available to your end users without having to touch each server in the farm or each client box that will connect to your SharePoint Server 2007 implementation.

Create a custom Upgrade Schema file to upgrade your existing sites and workspaces from the old Windows SharePoint Services 2.0 site definition to the new Windows SharePoint Services 3.0 site definition that you created previously.

Even though you have created a new site definition incorporating Windows SharePoint Services 3.0 functionality, you must upgrade existing sites so that they continue to use your new site definition. Without this step, they will continue to use the Windows SharePoint Services 2.0 site definition and will lack the new functionality and look and feel of a version 3.0 site.

Let’s use an example to go through the process of upgrading your version 2.0 site definition to version 3.0. First you’ll learn the steps involved when adding your customizations to a Windows SharePoint Services 3.0 site definition. This example assumes that you have added a custom list definition and a custom Web Part to a Windows SharePoint Services 2.0 site definition named STSCONTOSOSALES. The STSCONTOSOSALES site definition is very similar to the standard STS site definition, except that is has a Sales Targets list definition and a custom Web Part that displays Products data from the Contoso Sales database.

Windows SharePoint Services 3.0 site definitions no longer have a LISTS folder containing the list definitions. Therefore, there is no ListTemplates element to register the list definitions. All the lists are added as features within the STS list definition. Web Parts are also added as features in the STS Windows SharePoint Services 3.0 site definition.

In our example, a custom WebTemp.xml file is first created to populate the Template Selection page. The file is called WEBTEMPCONTOSO.XML and contained the following XML:

On the CD   The following code example can be found on the book’s companion CD, in the \Code\Chapter 25 folder in the Code1.txt file.

   <?xml version="1.0" encoding="utf-8" ?> 
<!-- _lcid="1033" _version="11.0.5510" _dal="1" --> 
<!-- _LocalBinding --> 
<Templates xmlns:ows="Microsoft SharePoint">
 <Template Name="STSCONTOSOSALES"     ID="10001">
    <Configuration ID="0" Title="Contoso Sales Team Site"  
Hidden="FALSE" ImageUrl="/_layouts/images/stsprev.png"  
Description="CONTOSO Sales Team Site">   </Configuration> 

The ONET.XML file is then modified to register a custom list definition called Targets. Figure 25-5 shows the custom list definition in the LISTS folder of our custom site definition.

Figure 25-5_ The Contoso Targets custom list

Custom Targets list - Contoso example

The following lines of XML code makes the Targets list available to the site definition and is created in the ListTemplates element:

On the CD   The below code example can be found on the book’s companion CD, in the \Code\Chapter 25 folder in the Code2.txt file.

<ListTemplate Name="Targets" DisplayName="Sales Targets"  
Type="10000" BaseType="0" OnQuickLaunch="TRUE" SecurityBits="11"
Description="Create a Contoso Sales Target List"

A custom Web Part is also created and added to the right-hand Web Part zone on the Contoso Sales Team Site pages. The following lines of XML code makes the Web Part available on the page.

On the CD   The following code example can be found on the book's companion CD, in the \Code\Chapter 25 folder in the Code3.txt file.

  <AllUsersWebPart WebPartZoneID="Right" WebPartOrder="3"> 
 <WebPart xmlns= 2 
      <Assembly>Contoso.WebParts, Version=, Culture=neutral,  
      <Title>Sales Products</Title> 

Now that we’ve illustrated the customizations that were made in version 2.0, you can now follow the steps below to re-create your modifications for a Windows SharePoint Services 3.0 site definition:

  1. Copy the Targets custom List Definition folder from the 60\TEMPLATE\1033\STSCONTOSOSALES\LISTS folder, and paste it into the 12\TEMPLATE\FEATURES\TargetsList folder.

  2. List definitions no longer have their own .aspx pages, such as AllItems.aspx, in Windows SharePoint Services 3.0. If you customized the .aspx pages in Windows SharePoint Services 2.0, leave them as they are. If you want to use the version 3.0 .aspx pages, change the SetupPath=”pages\form.aspx” in the form tag of your list definition to use the new standard .aspx pages for all lists.

  3. In the TargetsList folder, create a Feature.xml file, adding the following XML.

On the CD The following code example can be found on the book's companion CD, in the \Code\Chapter 25 folder in the Code4.txt file.

    <?xml version="1.0" encoding="utf-8" ?> 
    <!-- _lcid="1033" _version="12.0.4017" _dal="1" --> 
    <!-- _LocalBinding --> 
    <Feature Id="00BFEA71-7E6D-4186-9BA8-C047AC7510000" 
            <ElementManifest Location="ListTemplates\targets.xml"/> 
  1. In the TargetsList folder, create a new folder called ListTemplates.

  2. Inside the ListTemplates folder, create a targets.xml file and enter the following code.

    On the CD   The following code example can be found on the book's companion CD, in the \Code\Chapter 25 folder in the Code5.txt file.

    <?xml version="1.0" encoding="utf-8" ?> 
    <!-- _lcid="1033" _version="12.0.4017" _dal="1" --> 
    <!-- _LocalBinding --> 
    <Elements xmlns=""> 
  3. Create a copy of the STS folder in the 12\TEMPLATE\SiteTemplates folder, and name it STSCONTOSOSALES.

  4. Add the following new entry for you new feature to the ONET.XML file in the <Lists> element under Configuration 0.

    On the CD   The following code example can be found on the book's companion CD, in the \Code\Chapter 25 folder in the Code6.txt file.

    <List FeatureId="00BFEA71-7E6D-4186-9BA8-C047AC7510000"  
    /$Resources:core,Targets_Folder;" />
  5. Create a new feature to roll out your custom Web Part, and add the new feature to the ONET.XML file as follows.

    On the CD   The following code example can be found on the book's companion CD, in the \Code\Chapter 25 folder in the Code7.txt file.

            <Feature ID="00BFEA71-7E6D-4186-9BA8-C047AC7510001" /> 
  6. Copy the WEBTEMP.XML file from the 12\TEMPLATE\1033\XML folder, and paste it, naming the new copy WEBTEMPCONTOSO.XML.

  7. Add a new entry as you did in the Windows SharePoint Services 2.0 WEBTEMPCONTOSO.xml file, making the new site definition (STSCONTOSOSALES) available to the Template Selection page. Figure 25-6 shows the Windows SharePoint Services 2007 Template Selection page.

    Figure 25-6_ The Template Selection page

    Template Selection page

  8. The last step is to create an upgrade definition file to map the Windows SharePoint Services 2.0 files to Windows SharePoint Services 3.0. This is explained later in this chapter.

Changing a Windows SharePoint Services 2.0 Site Definition to Incorporate Version 3.0 Functionality

This method is far more difficult and not recommended unless you are going to find it less work to change your Windows SharePoint Services 2.0 site definition and add in all the new Windows SharePoint Services 3.0 functionality. You need to carry out the following steps to make this happen:

  1. Copy your Windows SharePoint Services 2.0 custom site definition to the sitetemplates folder in the 12 hive.

  2. Add the SPWebPartManager to every page within your site definition. (This is required by ASP.NET 2.0 so that it can display Web Parts and Web Part zones.)

  3. Remove the <ListTemplates> tags and contents from your ONET.xml if you are using a site definition that is based on STS. You need to remove the following list definitions from your site definition:

    • custlist

    • gridlist

    • doclib

    • imglib

    • voting

    • discuss

    • favorite

    • announce

    • contacts

    • events

    • tasks

    • xmlform

    • issue

  4. In the <Configurations> tags, add a <WebFeatures> tag and add each feature that you want to deploy with that site. You need to deploy each list as a feature and deploy the basic Web Parts. At a minimum, the features you need to add are as follows:

    Table 25-3_ Features Required to Upgrade Your Custom Site Definition

    Feature name Feature GUID







































  5. Add the Team Collaboration feature to <WebFeatures>. (This feature adds other required dependent features.)

  6. Change the SetupPath="pages\form.aspx" in the form tag of your list definition to use the new standard .aspx pages for all lists.

  7. (Optional) You might also want to take advantage of some of the new functionality in your list definition. This is optional but recommended so that your list definition gets the same functionality as all of the standard SharePoint lists. The new functionality includes the ability to work with content types and shared field definitions. To take advantage of this functionality, you need to use the <Content Types> tag to declare which content types to include in your list definition and a <Field> tag to include the GUIDs of the shared fields you are going to use. Without this step, users won’t know why they can’t add content types for your custom list definition although they can for other lists.

  8. Test your new site definition by creating a new site from it. If it works as expected, you can continue to upgrade your existing sites to the new site definition.

Upgrading Existing Sites with an Upgrade Schema Definition File

Now that you have created your new site definition, you need to upgrade your sites from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0. Without this step, they will be accessible in SharePoint Server 2007 but continue to use the old site definition. As a result, they will have the look and feel of Windows SharePoint Services 2.0 sites. The purpose of the upgrade definition file is to move your version 2.0 sites to the version 3.0 platform so that those sites can take advantage of the SharePoint Server 2007 functionality.

In the 12 hive under the Config folder, you will find an UPGRADE folder consisting of multiple upgrade files, as shown in Figure 25-7.

Figure 25-7_ UPGRADE folder

UPGRADE folder in the 12 hive\CONFIG directory

One of the files is called WssUpgrade.xml. WssUpgrade.xml is the upgrade definition that SharePoint Server 2007 itself uses to upgrade existing SharePoint team sites, blank sites, and document workspaces to Windows SharePoint Services 3.0 from Windows SharePoint Services 2.0.

You can create your own upgrade definition file in this same folder by copying the WssUpgrade.xml file and giving it a unique name—for example, STSCONTOSOUpgrade.xml.

However, before you create your own upgrade definition, let’s explore the existing WssUpgrade.xml file. Under the root element of <Config>, you will find a <WebTemplate> element. The <WebTemplate> element is telling the upgrade process which versions of SharePoint and which schemas you are upgrading from and to. If you upgrade the product version, you just specify FromProductVersion=2, and the process will upgrade the product to the most recent version. You can also upgrade from one schema to another schema, but not both the product version and the schema at the same time. You can also specify the locale so that you upgrade the correct site definition if you are using multiple language packs.


Windows SharePoint Services has a schema version for each site. The schema version is a number set by a developer. This number can be incremented by developers any time they make a significant enough change to a site definition to require using an upgrade template. This allows them to upgrade sites to use a new version of a site definition and to run two versions of the site definition side by side.

Following is a snippet from the WssUpgrade.xml file in the 12 hive showing the <WebTemplate> element:

<Config xmlns="urn:Microsoft.SharePoint.Upgrade"> 

After this element will follow a <Lists> element containing multiple <List> elements. The purpose of the <List> elements is to upgrade each list, using its Type identifier (105 = contacts list, 104 = announcements, and so on), to the feature that implements the list definitions in Windows SharePoint Services 3.0.


The last three characters of the feature’s GUID match that of the old list definition type IDs.

Following is the <Lists> element from the WssUpgrade.xml file:

       ToFeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104" /> 
        ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105" /> 
        ToFeatureId="00BFEA71-DE22-43B2-A848-C05709900100" /> 
        ToFeatureId="00BFEA71-F381-423D-B9D1-DA7A54C50110" /> 
        ToFeatureId="00BFEA71-E717-4E80-AA17-D0C71B360101" /> 
        ToFeatureId="00BFEA71-EC85-4903-972D-EBE475780106" /> 
        ToFeatureId="00BFEA71-3A1D-41D3-A0EE-651D11570120" /> 
        ToFeatureId="00BFEA71-5932-4F9C-AD71-1557E5751100" /> 
        ToFeatureId="00BFEA71-2062-426C-90BF-714C59600103" /> 
        ToFeatureId="00BFEA71-52D4-45B3-B544-B1C71B620109" />
        ToFeatureId="00BFEA71-EB8A-40B1-80C7-506BE7590102" /> 
        ToFeatureId="00BFEA71-A83E-497E-9BA0-7A5C597D0107" /> 
        ToFeatureId="00BFEA71-1E1D-4562-B56A-F05371BB0115" /> 

Immediately after the <Lists> element is the <Files> element. This upgrades each list that exists on the upgraded team site. Rather than using the .aspx forms, such as AllItems.aspx and EditForm.aspx that live in the forms folder, the list will now use the standard forms stored centrally in the 12 hive. The location of some of these forms varies. In the next code block, you can see part of the <Forms> element. You will notice, by studying the WssUpgrade.xml file for yourself, that some of the entries don’t move the location of the form at all.

                ToPath=  "SiteTemplates\STS\Default.aspx" 
                ToPath=  "pages\viewpage.aspx" 
                ToPath=  "pages\form.aspx" 
                ToPath=  "pages\form.aspx" 
                ToPath=  "pages\form.aspx" 
                ToPath=  "pages\viewpage.aspx" 
                ToPath=  "pages\form.aspx" 

The last element is the <AppliedSiteFeatures> element, which rolls out other functionality within the SharePoint team site. The following list shows the basic Web Parts, which make up the first feature rolled out by the <AppliedSiteFeatures> element:

  • Content Editor Web Part

  • Image Web Part

  • XML Web Part

  • Members Web Part

  • Page Viewer Web Part

  • Simple Form Web Part

  • User Documents Web Part

  • User Tasks Web Part

The second applied feature activates even more features. Features can have dependent features, so when you apply the feature in the following code block that ends in BE5, it activates all the list features that were listed in the preceding code block and is known as the Team Collaboration feature.

            <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" /> 
            <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" /> 


As well as having a WssUpgrade.xml, the upgrade folder also contains MpsUpgrade.xml to upgrade all multipage sites (MPS). The MPS site definition is the container of the meeting workspaces.

So to complete the upgrade of your sites, you need to create a new Upgrade Definition file that upgrades your existing sites to use your new site definition. Follow these steps to upgrade our STSCONTOSOSALES site definition.

  1. Create a copy of the WssUpgrade.xml file, and call it STSCONTOSOSALES.xml.

  2. The file will upgrade all the standard lists and files, as well as install all the required Web Parts and other functionality. We need to add to the file our customizations.

  3. Create the following <List> element for our custom Targets list, ensuring that you use the same GUID as you did in your feature:

    <List FromTemplateId="100" 
          ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC7510000" />
  4. Create a <File> element for each file in the Forms folder of our Targets list, and point them to the standard forms, as shown in the following example:

    <File FromPath="{LocaleId}\STSCONTOSOSALES\Lists\targets\AllItems.aspx" 
                    ToPath=  "pages\viewpage.aspx"/>
  5. Create an <AppliedWebFeatures> element to roll out our custom Web Part, as shown in the following example:

         <Feature ID="00BFEA71-7E6D-4186-9BA8-C047AC7510001" /> 
  6. Use the Installation And Configuration Wizard, as shown in Chapter 24.

Upgrading Customized Pages

Customized pages refers to pages that have been modified using Microsoft FrontPage 2003 and are stored in the content database. Customized pages were explained in detail earlier in this chapter. In general, you have two decisions to make. First, you can just leave the customized page as a customized page, and it will always look like a Windows SharePoint Services 2.0 page rather than a Windows SharePoint Services 3.0 page.

Unfortunately, though, when you go into Site Settings or into a list, you will receive a Windows SharePoint Services 3.0 page with the up-to-date look and feel. It is only the customized page of your site that will look out of date. If you think it will save you time and if you can lose the customizations you made in your version 2.0 page, you can reset the customized site back to the original site definition. Figure 25-8 illustrates this option in the interface.

Figure 25-8_ Reset To Site Definition option

Windows SharePoint Server Site Settings page


If you used the Ghost Hunter Web Part (part of the Web Part Toolkit downloadable from in Windows SharePoint Services 2.0, you are already familiar with this process. You will lose some of the changes that you made in FrontPage, but others will remain. Navigation changes remain if you simply add a new link, but any new Web Part zones are lost and replaced with the original Web Part zones specified in the Default.aspx page in the site definition.

If your pages have any custom script or tags, SharePoint might have a problem with rendering. The SharePoint Parser automatically corrects certain known issues so that the page can be parsed. The issues that get corrected by version 3.0 are as follows:

  • Invalid control IDs are not compliant with ASP.NET (such as when a name is invalid because the ID begins with a number or unsupported character), the ID is an empty string, or the ID is not unique with respect to other IDs on the page. This modification can break the page in a case where client-side script relies on the former ID names.

  • Known attributes inserted in the page by Windows SharePoint Services (for example, __Preview, __Error, __Web PartId, Web Part) are handled by implementing the SharePoint IAttributeAccessor interface on Web Parts.

  • Removal of Trace attributes.

  • Addition of appropriate directives for registering tags such as <WebPart:WebPartZone> or <SharePoint:Theme>.

Windows SharePoint Services 3.0 does not attempt to fix the following breaking issues on pages:

  • Unknown attributes on controls

  • Presence of <object runat=server> tags

  • Databinding expressions present inside attributes (<% ... %>).

Windows SharePoint Services stores a version integer for each customized page in the database. When a customized page is browsed, SharePoint checks the version number of the page. If the version number corresponds to a default page, SharePoint fixes these various issues and updates the page behind the scenes.

The _Layouts Virtual Directory

Any pages that are stored in the \Web Server Extensions\60\TEMPLATE\LAYOUTS\LCID setup directory, such as EditAlert.aspx, are automatically redirected to use the new /_layouts/Locale_ID/nameofoldpage.aspx or to /_layouts/newpage.aspx pages.

Upgrading Web Parts

Web Parts continue to function in Windows SharePoint Services 3.0, although they require a few changes in their configuration. If you create a new Web application to host a Windows SharePoint Services 3.0 installation, the Web.config file for that Web application must be updated to include additional safe control and code access security (CAS) policy settings.

Although the general level of CAS restrictions remains the same in Windows SharePoint Services 3.0, the Windows SharePoint Services policy files have been updated to the ASP.NET 2.0 level and format. For this reason, it is not generally possible to reuse CAS policy files in Windows SharePoint Services 3.0.


In this chapter, you learned about what makes up a site definition and how to upgrade a custom site definition and any sites created using that site definition to Windows SharePoint Services 3.0. We also explored the concept of customized sites (unghosted sites) and how to upgrade them to Windows SharePoint Services 3.0.