Upgrading Your Customized Windows SharePoint Services 2.0 Site Definitions to Windows SharePoint Services 3.0 | MicrosoftВ® Office SharePointВ® Server 2007 Administrators Companion

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:

Create or copy your custom site definition changes into a new Windows SharePoint Services 3.0 site definition.
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.
Open table as spreadsheet
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 up grade 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" ?> <!-- _lc _version="11.0.5510" _dal="1" --> <!-- _LocalBinding --> <Templates xmlns:ows="Microsoft SharePoint">  <Template Name="STSCONTOSOSALES"     >     <Configuration  Title="Contoso Sales Team Site" Hidden="FALSE" ImageUrl="/_layouts/images/stsprev.png" Description="CONTOSO Sales Team Site">   </Configuration> </Template> </Templates>

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.

image from book
Figure 25-5: The Contoso Targets custom list

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" Image="/_layouts/images/itgen.gif"> </ListTemplate>

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 WebPartZone WebPartOrder="3">  <![CDATA[ <WebPart xmlns=http://schemas.microsoft.com/WebPart/v2version 2    xmlns:iwp="http://schemas.microsoft.com/WebPart//Image">      <Assembly>Contoso.WebParts, Version=1.0.0.0, Culture=neutral,          PublicKeyToken=71e9bce111e9429c</Assembly>      <TypeName>Contoso.WebParts.ProductsPart</TypeName>      <FrameType>Standard</FrameType>      <Title>Sales Products</Title>      </WebPart>     ]]>  </AllUsersWebPart>

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:

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

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" ?> <!-- _lc _version="12.0.4017" _dal="1" --> <!-- _LocalBinding --> <Feature      Title="$Resources:core,targetslistFeatureTitle;"     Description="$Resources:core,targetslistFeatureDesc;"     Version="1.0.0.0"     Scope="Web"     Hidden="TRUE"     DefaultResourceFile="core"     xmlns="http://schemas.microsoft.com/sharepoint/">     <ElementManifests>         <ElementManifest Location="ListTemplates\targets.xml"/>     </ElementManifests> </Feature>

In the TargetsList folder, create a new folder called ListTemplates.

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" ?> <!-- _lc _version="12.0.4017" _dal="1" --> <!-- _LocalBinding --> <Elements xmlns="http://schemas.microsoft.com/sharepoint/">     <ListTemplate         Name="targets"         Type="10000"         BaseType="0"         OnQuickLaunch="TRUE"         SecurityBits="11"         Sequence="330"         DisplayName="$Resources:core,targetsList;"         Description="$Resources:core,targetsList_Desc;"         Image="/_layouts/images/itcontct.gif"/> </Elements>

Create a copy of the STS folder in the 12\TEMPLATE\SiteTemplates folder, and name it STSCONTOSOSALES.
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 Feature Type="10000" Title="$Resources:core,TargetsList;" Url="$Resources:core,lists _Folder; /$Resources:core,Targets_Folder;" /> 
```
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.
```
 <SiteFeatures>   <Feature  /> </SiteFeatures> 
```
Copy the WEBTEMP.XML file from the 12\TEMPLATE\1033\XML folder, and paste it, naming the new copy WEBTEMPCONTOSO.XML.
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.
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.

image from book
Figure 25-6: The Template Selection page

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:

Copy your Windows SharePoint Services 2.0 custom site definition to the sitetemplates folder in the 12 hive.
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.)

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:

q	custlist
q	gridlist
q	doclib
q	imglib
q	voting
q	discuss
q	favorite
q	announce
q	contacts
q	events
q	tasks
q	xmlform
q	issue

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:
Add the Team Collaboration feature to <WebFeatures>. (This feature adds other required dependent features.)
Change the SetupPath="pages\form.aspx" in the form tag of your list definition to use the new standard .aspx pages for all lists.
(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.
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.

Table 25-3: Features Required to Upgrade Your Custom Site Definition
Open table as spreadsheet
Feature name	Feature GUID
AnnouncementsList	0BFEA71-D1CE-42de-9C63-A44004CE0104
ContactsList	FEA71-7E6D-4186-9BA8-C047AC750105
CustomList	BFEA71-DE22-43B2-A848-C05709900100
DataSourceLibrary	0BFEA71-F381-423D-B9D1-DA7A54C50110
DiscussionsList	0BFEA71-6A49-43FA-B535-D15C05500108
DocumentLibrary	0BFEA71-E717-4E80-AA17-D0C71B360101
EventsList	BFEA71-EC85-4903-972D-EBE475780106
GanttTasksList	0BFEA71-513D-4CA0-96C2-6A47775C0119
GridList	BFEA71-3A1D-41D3-A0EE-651D11570120
IssuesList	BFEA71-5932-4F9C-AD71-1557E5751100
LinksList	BFEA71-2062-426C-90BF-714C59600103
NoCodeWorkflowLibrary
PictureLibrary	0BFEA71-52D4-45B3-B544-B1C71B620109
SurveysList	BFEA71-EB8A-40B1-80C7-506BE7590102
TasksList	BFEA71-A83E-497E-9BA0-7A5C597D0107
WebPageLibrary	0BFEA71-C796-4402-9F2F-0EB9A6E71B18
WorkflowProcessLibrary
WorkflowHistoryList	0BFEA71-4EA5-48D4-A4AD-305CF7030140
XmlFormLibrary	0BFEA71-1E1D-4562-B56A-F05371BB0115

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.

image from book
Figure 25-7: UPGRADE folder

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.

Note

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">     <WebTemplate                  Locale         FromProductVersion="2"         BeginFromSchemaVersion="0"         EndFromSchemaVersion="0"         ToSchemaVersion="1">

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.

Note

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:

 <Lists>    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    <List        FromTemplate        ToFeatureId="" />    </Lists>

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.

        <Files>            <File                FromPath="{LocaleId}\STS\Default.aspx"                ToPath=  "SiteTemplates\STS\Default.aspx"            />            <File                FromPath="{LocaleId}\STS\Lists\announce\AllItems.aspx"                ToPath=  "pages\viewpage.aspx"            />            <File                FromPath="{LocaleId}\STS\Lists\announce\DispForm.aspx"                ToPath=  "pages\form.aspx"            />            <File                FromPath="{LocaleId}\STS\Lists\announce\EditForm.aspx"                ToPath=  "pages\form.aspx"            />            <File                FromPath="{LocaleId}\STS\Lists\announce\NewForm.aspx"                ToPath=  "pages\form.aspx"            />            <File                FromPath="{LocaleId}\STS\Lists\contacts\AllItems.aspx"                ToPath=  "pages\viewpage.aspx"            />            <File                FromPath="{LocaleId}\STS\Lists\contacts\DispForm.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.

 <AppliedSiteFeatures>     <Feature ID="" /> </AppliedSiteFeatures> <AppliedWebFeatures>     <Feature ID="" /> </AppliedWebFeatures>

Note

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.

Create a copy of the WssUpgrade.xml file, and call it STSCONTOSOSALES.xml.
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.
Create the following <List> element for our custom Targets list, ensuring that you use the same GUID as you did in your feature:
```
 <List FromTemplate       ToFeature /> 
```
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"/> 
```
Create an <AppliedWebFeatures> element to roll out our custom Web Part, as shown in the following example:
```
 <AppliedWebFeatures>      <Feature  /> </AppliedWebFeatures> 
```
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.

image from book
Figure 25-8: Reset To Site Definition option

Note

If you used the Ghost Hunter Web Part (part of the Web Part Toolkit downloadable from http://www.bluedoglimited.com) 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:WebPart-Zone> 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.