7. Upgrading SharePoint Site Definitions from v2 to v3: CREATING A LIST DEFINITION

  • Article

As with the Master Page, there are many different ways to put together and deploy a new List such as via the Visual Studio extensions for SharePoint. But in this case, where we are putting together v3 Site Definitions which correspond to v2 Site Definitions which we are upgrading, we're going to create the v3 list in much the same way that the v2 list was created, manually by copying an existing list, modifying it as needed, and then attaching it to the Site Definition.

Note that if you want to take the existing v2 definition and modify it into a v3 list Feature, there is an article in the SDK to guide you through this process:

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

There is a big difference between the way lists are provisioned in SharePoint v3 vs. SharePoint v2. In v2 the List Definitions were part of each Site Definition and were defined in the onet.xml file found in the Site Definition's xml folder. In v3, lists are a Feature and are defined in the Feature's schema.xml file. 

With v3 you only have to create a List Definition once, and then it can be added to any number of different Site Definitions, whereas in v2 all Lists had to be defined within each Site Definition.

Feature definitions reside in the FEATURES folder located at:

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

In my particular case, I need a document library with two additional fields. To accomplish this you first copy the existing document library Feature - the folder named DocumentLibrary, and paste it back into the FEATURES folder and rename it to DocumentLibrary<YourListName>.

Open up your new DocumentLibrary<YourListName> folder, and rename the DocLib folder to <YourListName>Lib.

Open up the ListTemplates folder and rename the DocumentLibrary.xml file to DocumentLibrary<YourListName>.xml

Now we need to correct the references to these files in the Feature.xml file. Open Feature.xml in notepad. Change:

  • Id="<generate a new GUID>" 
  • Title="<YourListTitle>"
  • Description="YourListDesription"
  • <ElementManifest Location="ListTemplates\DocumentLibrary<YourListName>.xml" />

For the Id value, in Visual Studio on the Tools menu select "Create GUID". Select "Registry Format" then click "New GUID" and then "Copy" and paste the result in notepad and copy just the GUID itself (look at the one you're replacing to understand the format). Also, there are many GUID generators online if Visual Studio isn't available.

Now open the DocumentLibrary<YourListName>.xml file in notepad. Change:

  • Name="<YourListName>"
  • Type="10001" (suggesting that you ID your custom lists 10,000 and up)
  • DisplayName="<YourListName>"
  • Description="<YourListDescription>"

To modify the new List Definition from the original Document Library site definition, open the schema.xml file located in your <YourListName>Lib folder in notepad.

In my case I am adding two fields from the v2 List Definition, Report Type and Report Sub Type. I copy the following field elements from the v2 Onet.xml file to the <Fields> section of the FEATURES schema.xml file ("_x0020_" is an encoded space):

 <Field Type="Text" Name="Report_x0020_Type" DisplayName="Report Type" Required="TRUE" ></Field>
 <Field Type="Text" Name="Report_x0020_Sub_x0020_Type" DisplayName="Report Sub Type" Required="TRUE" ></Field>

And then these same fields are added into the <ViewFields> section so that they show up in the forms for creating views etc:

  <FieldRef Name="Report_x0020_Type"></FieldRef>
  <FieldRef Name="Report_x0020_Sub_x0020_Type"></FieldRef>

I am just demonstrating the addition of these two fields. They will not be editable. To make them editable you need to create them as Content Types and add an entry in the <ContentTypes> element. See Ari Bakker's blog entry for detailed help with that:

https://ari.provoke.co.nz/archive/2007/04/18/creating-a-custom-sharepoint-2007-list-definition.aspx

Of course you can make much more complicated modifications such as adding calculating fields, adding new views etc.

For more information on the Schema.xml file go to:

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

Now you need to deploy this new feature to your farm. For this you'll need to run STSADM.

  • stsadm -o installfeature -filename DocumentLibrary<YourListName>\Feature.xml
  • stsadm -o activatefeature -name SimpleListFeature -url https://<YourPortal>

For info on how to add this new list into your custom Site Definition(s), see blog entry 9 "Creating The Site Definition".