Wednesday, April 23, 2008

Using STSDEV to create a solution with a Site Definition

In this post I'll give a basic overview of how to create a simple site definition using STSDEV. The purpose of using STSDEV is to give the project a standardized structure and to make use of the solution autogeneration.

Here are the steps (Make sure you've downloaded STSDEV and run through the tutorials, or understanding this might be tough)

Part 1: Generate the STSDEV solution

  1. Open Visual Studio and run STSDEV (should be an option on your tools menu if you ran through the tutorials, see above link)
  2. Choose to create an empty solution with C# assembly
  3. Click 'Create the Solution'
  4. After you create the solution, you'll need to open it from the file system. STSDEV does not automatically open it for you in Visual Studio.

Part 2: Set up the project structure

Even the most basic site definition needs at least 3 files: a webtemp.xml file, an onet.xml file, and a default.aspx file. So let's create these files in the appropriate places.
  1. right click on the 'RootFiles' folder and add a new folder called 'TEMPLATE'
  2. Under the 'TEMPLATE' folder you created add a new folder called '1033'
  3. Under the '1033' folder you created create a new folder called 'XML'
  4. In the 'TEMPLATE/1033/XML' folder add a new XML file called 'webtemp.YourSiteName.xml', where your site name is what you want to call your site.
  5. Under the 'TEMPLATE' folder you created add a new folder called 'SiteTemplates'
  6. Under the 'SiteTemplates' folder create a folder called 'Your Site Name', with the name of the site you'd like to use.
  7. In the 'Your Site Name' folder, create a folder called 'xml'
Following those steps should set up your directory structure.

Part 3: The webtemp*.xml file

According to the MSDN documentation: 'The WebTemp*.xml files contain the site definition configurations that are available on the Template Selection section of the New SharePoint Site page'. So the details of this file determine how your site definition information will show up on the 'Create New Site' page.

  1. Go to the WebTemp.xml documentation page and copy the xml code into your webtemp*.xml file.
  2. Delete all the <template> nodes except for the first one
  3. In the only remaining <template> node, delete all the <configuration> nodes except the first one
  4. Enter a name for the <template> node 'Name' attribute (ensure this is the same name as your directory name in the SiteTemplates folder)
  5. Enter an id for the <template> node 'ID' attribute (if you've never done this before, start with 11001, this is because certain ID ranges are reserved. You'll notice that most of the out of the box templates are in the 10000 range, so hopefully anything in the 11000 range will be ok).
  6. Give the <configuration> node ID attribute a value of '0' (zero)
  7. Give the <configuration> node Title attribute a title of your choosing.
  8. Give the <configuration> node Description attribute a description of your choosing.
  9. Give the <configuration> node DisplayCategory attribute a category of your choosing (choosing 'Development' is a good idea, this will be the name of the tab on the 'Create Site' page that your site definition appears under)
Part 4a: Copying the onet.xml and default.aspx pages.

Since I will only be talking about the minimum needed to get your simple site definition working, after you complete this (or before) you might want to read up on the documentation for onet.xml

Because the onet.xml and default.aspx files are fairly long I won't post it here. What I do is use the version that is generated from VSeWSS. If you don't have this, download it because it is pretty useful, and generates solutions for you as well. I actually used this all the time before STSDEV came out and I decided that STSDEV generated what I considered to be cleaner and more well structured solutions. I have a template directory that contains most of the files that I use that I just copy into my solutions as I create them. I'll give the instructions on how to get the onet.xml and default.aspx file into your solution if you have VSeWSS v1.1 installed.
  1. Right click on your solution node for your STSDev Project and choose Add > New Project
  2. Choose 'Blank Site Definition' and create it
  3. In the project expand the 'Site Definition' folder and you'll see an onet.xml file, copy this to the 'TEMPLATE/SiteTemplates/Your Site Name/xml' folder in your STSDEV project
  4. In the same 'Site Definition' folder you found the onet.xml file in, you'll see a default.aspx file, copy this to the 'TEMPLATE/SiteTemplates/Your Site Name'.
Part 4b: Modifying the onet.xml file

There are only a few changes you need to make to the onet.xml file.
  1. Set the <project> node's 'Title' attribute to whatever you like.
  2. Set the <project> node's 'Revision' attribute to '1'.
  3. Set the <configuration> node's (under <project>) 'ID' attribute to '0' (zero).
Part 5: Deploy your solution

This is where STSDEV really shines, you basically don't need to do anything to get your site deployed other than select the 'DebugDeploy' configuration and do a build. If you did everything correctly you should be able to test your deployment by going to your site collection's home page and choosing Site Settings > Create and create a new site using your template.


Martin B said...

Thank you very much! This was just what I needed for my current project :)

Anonymous said...

Thanks for your guide.. made my day. Now i just have to staple some features to it and make some resource files and i have my site definition ready to go(in a wsp)

Restoring a lot of files from the Recycle Bin

I had a customer who accidentally synched a (very large) SP Online library and then decided they didn't want the files on their PC anymo...