9. Upgrading SharePoint Site Definitions from v2 to v3: CREATING THE SITE DEFINITIONS

Article
10/16/2007

Parts 1 to 8 of this series are in the August archive.

NOTE: we're having problems with specifying a custom master page on the v3 Site Definitions that correspond to the SPS Portal Upgrade site definitions (this explains the delay between Bog 8 and 9 of this series), I am getting an "Upgrade.Sequence failed" error and a "There is no file with URL 'Pages/default.aspx' in this Web." Still trying to figure this out. So unless you know what the problem is (in which case please let me know) I suggest just upgrading against the virgin SPS site definitions, and then specifying the master page after the upgrade and using the "Reset all subsites to inherit this Site Master Page" setting to apply it to all of the child upgraded portal sites.

We have the custom master page in place, custom list definitions have been created, and our web parts have been recompiled and are ready to go under SharePoint v3, so now we need to create our custom v3 Site Definitions, one for each corresponding v2 Site Definition. It is the Site Definition that pulls all these pieces together.

CREATE THE CUSTOM SITE DEFINITIONS

Again, there are different ways to create Site Definitions such as via the Visual Studio Extensions or the SharePoint Solution Generator, but here I'll go through the manual process of creating a new Site Definition.

To create a custom site definition, go to C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates.

You need to know what out-of-the-box (OOTB) site definition was used to create the original v2 site definitions.

For instance, if the original site definition was created from a team site definition, copy the "sts" Site Definition and rename it the same as the v2 Site Definition it will upgrade. So if the v2 Site Definition was called STS<MyPortal> name the v3 Site Definition the same thing.

Again, for each custom v2 site definition, copy the v3 site definition folder corresponding to the site definition that the v2 custom site definition was based on and rename it to be the same as the custom v2 site definition.

If you don't know which Site Definition the custom v2 site definition was based on, then I suggest using "SPSTOPIC" if the v2 Site Def was an SPS area definition, or "sts" if it was a WSS team site definition.

REFERENCING A CUSTOM LOGO IMAGE FROM EACH SITE DEFINITION

Open up the onet.xml file for each of your custom Site Definitions, and right at the top, change:

<Project Revision="3" DisableWebDesignFeatures="" SiteLogoUrl="/_layouts/1033/<MyPortal>/images/<MyPortal>_logo.gif">

...where SiteLogoUrl specifies the URL to your custom logo image.

REFERENCING THE CUSTOM MASTER PAGE FROM EACH SITE DEFINITION

Open the default page of each site definition in notepad, and at the top, change:

MasterPageFile="~masterurl/default.master" to MasterPageFile="~masterurl/custom.master"

Make this change just as it appears above even though your custom master page is actually named <MyPortal>custom.master (where <MyPortal> is replaced by the name of your portal).

NOTE: You may have more than one masterpage. I am currently dealing with one for My Sites, one for Team Sites, and then each Portal has it's own. In which case the name of the masterpage is more like <MyPortal><SiteDef>.master

Now open the onet.xml file of each Site Definition in notepad (located in the xml folder) and add:

CustomMasterUrl="_catalogs/masterpage/<MyPortal>custom.master"

...to each configuration element so that they look like:

<Configuration ID="0" Name="Default" CustomMasterUrl="_catalogs/masterpage/<MyPortal>custom.master" />

In the <Modules> section of each Configuration, add the following element:

<Module Name="<MyPortal>MasterPage" />

At the bottom of the page, just above the </Modules> tag (note this is not the same Modules section as the one above, this is outside the Configuration element) add the following:

    <Module Name="<MyPortal>MasterPage" List="116" Url="_catalogs/masterpage" RootWebOnly="FALSE">
      <File Url="<MyPortal>custom.master" Type="GhostableInLibrary" IgnoreIfAlreadyExists="TRUE" />
    </Module>

REFERENCING THE CUSTOM LIST DEFINITION FROM EACH SITE DEFINITION

Within the <Lists> section of each <Configuration> section which requires the custom List, add:

<List FeatureId="<YourListGuid>" Type="10001" Title="<YourListName>" Url="<YourListName>" QuickLaunchUrl="<YourListName>/Forms/AllItems.aspx" />

This assumes that the url for the list is the same as the name of the list.

Change the Type to the actual Type of your custom list.

REFERENCING THE CUSTOM WEB PART FROM EACH SITE DEFINITION

Adding your web part to a page is much the same as it was in v2.

To add your custom web part to the Left web part zone on the default page, find:

And immeadiately below it, add your AllUsersWebPart element similar to the OOTB MembersWebPart below:

        <AllUsersWebPart WebPartZoneID="Right" WebPartOrder="1"><![CDATA[
                   <WebPart xmlns="https://schemas.microsoft.com/WebPart/v2">
                      <Assembly>Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>
                      <TypeName>Microsoft.SharePoint.WebPartPages.MembersWebPart</TypeName>
                      <Title>$Resources:wp_Members;</Title>
                      <Description>$Resources:wp_Members_Desc;</Description>
                      <FrameType>Standard</FrameType>
                      <IsVisible>true</IsVisible>
                      </WebPart>
                   ]]></AllUsersWebPart>

changing the Assembly value to your Assembly name;
PublicKeytoken to your assembly's Public Key Token;
the Version to your version number;
changing the TypeName to your Namespace and Type Name;
and changing the Title and Description (you can simply add text instead of referencing a resource file).

ADD THE CUSTOM WEBTEMP FILES TO THE 12 HIVE

Copy your custom WEBTEMP files from the v2 location in the 60 Hive to this location in the 12 Hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\1033\XML

Your custom WEBTEMP files have names like WEBTEMP<MyPortal> and should have the same name in the v3 folder.

These files assign the IDs to your Site Definitions by tieing the ID to the folder name via the following element:

This is how the upgrade process is going to match up your v2 Site Definitions with your v3 Site Definitions.

ADD AN UPGRADE DEFINITION FILE FOR EACH SITE DEFINITION

You can create Upgrade Definition files from scratch, and there are instructions on doing this in the SDK. But we're simply going to copy existing files and modify them.

Go to: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\CONFIG\UPGRADE

For each WSS site definition, I suggest copying the WssUpgrade.xml file.

Rename these files to <YourSiteDefName>Upgrade.xml. Then open each file in notepad and change the ID to the ID of the v2 Site Definition to be upgraded. The corresponding v3 Site Defs have the same ID as the v2 Site Definitions per the WEBTEMP file installed above. Then do a search and replace to change the paths from "\STS\" to "\STS<MyPortal>\".

For the STS03 Site Definitions, copy the SPSUpgradePremium.xml file (or the SPSUpgrade.xml depending on the version of SPS installed) and rename it SPS<MyPortal>UpgradePremium.xml. This is one file for all of the OOTB SPS03 Area Site Definitions. So for each of the original Area Site Definitions that have customized Site Definitions, you need to change the ID numbers to the IDs of the customized Area Site Definitions.

Delete the WebTemplates that do not have corresponding customized Site Defnitions. Then modify the FromPath and ToPaths so that they reflect the folder name of the corresponding custom Area Site Definitions. You can do a similar Find and Replace as with the WSS Site Definitions, replacing "\SPSTOC\" with "\SPSTOC<MyPortal>\".

Also at the top of this file, delete the line:

Otherwise you'll get an error - Duplicate Id on sequence [Microsoft.SharePoint.Portal.Upgrade.FarmSequence] when you run the upgrade.

Change other items in these files as needed (mostly you don't need to). The Upgrade Definition schema can be found at:

https://msdn2.microsoft.com/en-us/library/ms412955.aspx

ADD THE LAYOUT PAGE REFERENCE FOR ALL SPS SITE DEFINITIONS TO THE SiteUpgraderConfigSPS.xml FILE

The Portal Site Definitions that you are upgrading should use the welcomelayout2.aspx layout page, not the defaultlayout.aspx. Otherwise the width of the pages may be totally wacked because SPS03 used a 2 zone structure and the default layout is a 3 zone structure.

Just copy the last PublishingPageLayoutMapping and paste back into the file one for each of your custom v2 Portal Site Definitions, and then change the WebTemplateIds to be the IDs of your custom v2 Portal Site Definitions.

Note the location of the physical layout pages referenced:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\PortalLayouts

ADD THE IDs OF THE CUSTOM SITE DEFINITIONS TO THE PREUPGRADESCANCONFIG.XML FILE

As noted back in Blog 4 of this series, RUNNING PRESCAN, the PREUPGRADESCANCONFIG.XML file initially contains the IDs for the OOTB SPS site definitions which will be needed if you are doing a SPS03 upgrade (as opposed to a WSSv2 upgrade), and needs all the IDs for all of your custom Site Definitions, both SPS and WSS, before running PRESCAN.

9. Upgrading SharePoint Site Definitions from v2 to v3: CREATING THE SITE DEFINITIONS

Additional resources