Thursday, March 17, 2011

About SharePoint 2010 Site Templates

I've been struggling with SharePoint site templates lately and have learned some valuable things. There's too much for one post. I'm hoping to have time to write a series that, taken together might be helpful.

This post is about the big picture and the main lessons.

Here's the scenario:
  1. You've built yourself a nice SharePoint site on your development server. Let's say it contains custom web parts, workflows, site columns, pages and content types.
  2. Now, it's time to package this up into a template and move to another server (say a test or production server). You want to use the template to create multiple copies of your site.
  3. SharePoint 2010 has improved capabilities over SharePoint 2007 but the new features come with their own limitations and complexity. That's what I want to write about.

The naive SharePoint developer will read the documentation and assume that this is all you need to do:

  1. Save the site as a template in the Solution Gallery.
  2. Download the WSP
  3. Either upload the WSP to the new server's gallery or deploy it using Central Administration.

Here's an example of the naive approach. Unfortunately, it creates lots of problems and only works on the simplest of sites.

Here's a short list of the problems:

  • The template includes lots of stuff you don't need and probably don't want on the destination server including content types and site columns from the root site. The site definition includes dependencies on all site-collection features on the source server even if they're not needed.
  • Because of all the extra stuff, the destination server needs to be almost identical to the source server. If it isn't, it won't work. Unless your template is extremely simple, this will prevent you from creating sites using your template until you've essentially re-installed all the dependent features (even the ones you don't use).
  • Features are given unfortunate names like "Web template of exported site MySite"
  • The template will clone the theme of the source site. New sites based on the template will appear to be using a standard Theme, but they are not. Site administrators who want to control look and feel will not be happy with this.

Visual Studio 2010 includes a wizard that can import WSPs. This is a huge time saver over what we had to do before. Unfortunately, this too has more than a few pitfalls. The upshot of these pitfalls is that, while it works, you should expect to spend quite a bit of time adjusting things before a truly useful and portable template can be generated.

Click here for a video that shows the basic Visual Studio WSP import process.

A quick summary of the pitfalls of importing WSPs into Visual Studio 2010:

  1. As mentioned above, the WSP that SharePoint creates contains a lot of stuff you don't need and don't want. The wizard allows you to avoid loading those items into the project, but the process is very tedious and it's easy to make mistakes. (A typical import will include more than 150 elements and each has to be selected individually).
  2. The resulting solution has a very odd and complex structure. Elements that could have easily been combined are separate. For example, a list instance is in one element while Edit, Upload, View pages are in another. Neither element is useful without the other and they can readily be combined. Why they're separate is a mystery.
  3. The arrangement of elements into features is very odd. In general, the import wizard seems to create lots of features when a few would do just fine. Again, the default names are most unfortunate.
  4. If you want to create your template in iterations, the only process that works is very tedious and error prone. Basically, you have to re-export the site, import it into a working project then manually transcribe the changes into your production project.

So, here's a more realistic process for creating "real" templates:

  1. Create the template on your development server.
  2. Save it into the Solution Gallery
  3. Import it into Visual Studio, omitting SharePoint-standard content types and site columns.
  4. Save the solution in your source code control system.
  5. Rename the features to something meaningful.
  6. Open the onet.xml file and remove dependencies on features you aren't using and don't need.
  7. Build the WSP.
  8. Test the WSP on another server.
  9. Fix whatever isn't working right.

When it comes time to produce a newer version of the template:

  1. Save the improved template to the Solution Gallery
  2. Import it into Visual Studio as a working copy.
  3. Open another copy of Visual Studio with your production template.
  4. Locate the changes and transcribe them to the new project.
  5. Build and test the new WSP.