Deployment lifecycle when using Site Definitions and Features (including post production day)

  • Article

Summary

As you have noticed, I've changed my latest SharePoint focus to look at Site Definitions (and obviously Features but I played with them a lot prior to this).  The reason for this is that I was looking at the "best" way to deploy artifacts for SharePoint WCM portals.  While I had a very good working solution prior to me playing more with Site Definitions, I now think that I am ready to handle the task much better.  This is also a follow-up to a previous article : https://blogs.msdn.com/maximeb/archive/2008/01/13/real-life-team-based-development-for-web-content-management-with-sharepoint-2007.aspx

 

The reason for this is that there is no single way to deploy SharePoint artifacts.  Worst, once you deployed the first time, your original mechanism may not work anymore or if it does, it's probably not what you should use!  What I'll attempt to do here is to define a few SharePoint artifacts that we deploy in a Web Content Management scenario for both production day and post production day, as well as the deployment lifecycle for the developers pre-production-day and post-production-day.

 

SharePoint artifacts we'll cover:

  • Master pages
  • Page Layouts
  • CSS / JavaScripts / Images (for the masterpages and layouts)
  • Site Columns & Site Content Types
  • Library content types association
  • Custom Lists
  • Event Handlers on libraries
  • Feature Receivers
  • Timer jobs

 

SharePoint topics discussed:

  • Site Definitions
  • Features
  • Variations
  • Feature Stapling
  • Timer Jobs
  • Content Deployment

 

Why Site Definitions?

The timing of me digging Site Definitions more and this post, https://www.andrewconnell.com/blog/archive/2008/02/15/You-dont-need-to-create-site-definitions.aspx,  from Andrew Connell was interesting.  First of all, he's right, you do not need to create a Site Definition all the time.  However, there are also general guidelines.  When you look at the Publishing portal that is available out of the box, it really looks like a good sample for reverse-engineering (and believe me, I opened it often to learn stuff!).  How often have you kept the original "Press Releases" sub-site or used "Blueband" or any other master for your site?  What Andrew mentions is that you should create your own minimal publishing site or you can take a look at this one here on CodePlex but I suggest you still take it apart with your requirements.

 

Also, I'm almost always in a multilingual scenario (i.e.: SharePoint Variations) and then Site Definitions takes its full meaning.  Why? well the Variation mechanism is really just a system that provision sites.  It is not a copy of the source site.  When the variation timer job kicks in, it will detect a new site in the source variation.  When it reads it, it takes the title, the description, the URL and the Site Template (i.e.: site definition).  Then it simply does a standard Create Site... with those parameters.  Once that is done, it will replicate only the publishing fields of the welcome page.  Last, it will provision the other publishing pages the same way and replicate only the publishing fields on those pages.  Note that any customization done manually at the source, beside publishing pages and fields, will NOT be brought to the other variations. That includes libraries undefined in the site definitions, documents or images, versioning settings, workflows, and everything else you see in the user interface that isn't a publishing field!

 

I think my last sentence was obvious enough that if you customize something at the source, you will customize it again at the destination.  While there may be scenarios when you might want this, it'll be unusual and the solution is to use Site Definitions so that the provisioning brings as much as possible.

I'll finish this section with an example: today, if you have a Publishing site with the OOB site definition and that your welcome pages aren't "WelcomeLinks", what do you do?  First of all, at the source, you created a new page with your layout.  Then you updated the welcome page of your site to your new page and deleted the old "default.aspx".  Now all your welcome pages are not "default.aspx" but it's no big deal.  When you created a 2nd variation label, all the default.aspx/WelcomeLinks are back and they are the welcome pages of your sites in that variation!!  So you again updated the welcome page and deleted the default.aspx.  That's not very user friendly.  Also, if you wanted to ended up renaming your custom page to "default.aspx", the variation mechanism would break when trying to provision the site since it's the name for the WelcomeLinks.

 

As you can see, Site Definitions becomes a must when using variations.

 

What defines a Site Definitions?

First of all, there is no golden rule for this but here's what I personally follow to determine if I use the same definition or a new one:

  • A different welcome page layout
  • I want to pre-provision a default set of web parts in a welcome page layout
  • (f) I want to associate specific content types to libraries
  • (f) I want to allow specific page layouts creation (i.e.: a "news" only section, a "product" only section, etc.)
  • (f) I want to add special Site Actions for some sites
  • (f) I want to have a special workflow for some sites
  • (f) I want to update library settings for some sites

 

Note that the items prefixed by "(f)" are items where the delivery mechanism is Features but they are associated in some site definitions.

 

Also, one note that will affect your site definition architecture are Feature Stapling.  That functionality is one of the very practical mechanism to apply a feature to a site definition.  Unfortunately, it's also "only that".  What I mean is that if you have multiple sites with the same definition, it will apply the feature on all those sites.  This is great inside a single Site Collection but when your SharePoint farm contains multiple site collections (possibly for different customers), you may not want to apply a feature to all of them.  Unfortunately, I do not personally know of a better solution than to create your Site Definitions "per site collection" only (i.e.: in the naming).  They will still likely use the same features though.

 

And really, when I design Site Definitions, I created a Feature that contains all the Features that I use for ALL sites.  That way, my Site Definitions are very small and only contains the customization for that site.  Also, I suggest taking a look at this tool to read your sites definitions : https://blogs.msdn.com/maximeb/archive/2008/02/16/site-definition-viewer-a-windows-net-2-0-tool-to-read-site-definition-and-features-configurations-version-0-1.aspx.  I also created some CMD files to automate development of site definitions and they come in handy to maximize your time.  I will post them soon.

 

 

Before taking a look at the SharePoint artifacts, I need to give you a bit of background on how we get the artifacts: We set up a MOSS server only for "web integrators". The Site Collections in there contains the files directly in the database edited through SharePoint Designer. We hooked up an event on the libraries that, when a check-in is done, it brings the file in a Team Foundation Server. Then, we have someone maintaining the build process and when he get the "go" from the web integrators, he builds the feature containing the files and that is sent to the developers for updates and eventually to production.

 

 

SharePoint artifact deployment - Master Pages - Page Layouts - CSS/JS/Images

1) Pre-production "day 1"

You should create a site-scoped Feature containing your master pages and other files (pages layouts and css/js/images).  Take a look at the PublishingLayouts for ideas.  When this feature is activated on a site collection, it will add the file in the libraries in a ghosted format which means that there are no customization on them.  Note that if you ever unghost it at the destination, your feature will never update the file after.

 

2) Post-production "day 2+"

We'll have to define some sub-scenarios but first, let's start that, yes, you may be able to uninstall the feature and reinstall it while using the -force command but I do not recommend it.  First, as I just mentioned, if you unghosted a file, it will not be updated.  So if you plan on using this technique, make sure you test first.  Also, I had some issues with BlobCache with CSS/JS/GIF/JPG but only when they were ghosted, never when unghosted.

 

Scenario #1 Updates to some/all the files

I would suggest creating an STSADM extension that update files defined in your Feature.  This extension will unghost the file and it will act as your mechanism to deploy updates.  What I use is a simple extension with an Xml input file that defines the files to update.  This file simply grows over time since I only append to it.  It gives me an added benefit with "change management" since it's not simply a build that picked up all files and sent it in the feature which may contain an update.

 

Scenario #2 New files

If you have new files, you probably have a "business reason" behind.  For a new master pages or page layout, is it only for a new type of site (i.e.: defined in a site definition) or would you like to apply it automatically on some/all sites?  That you have a new site definition or not, you are likely to have a new feature that brings the file.  This feature may contain a Feature Receiver that will do some actions with those files such as :

  • Assigning the master page to some sites
  • Allowing the page layout to be created in some/all sites
  • If you have a new site definition, you may want to add it in the list of available web templates

 

Once you have your feature, you may want to create another one to staple the first feature with your site definition (some or all of them).

 

For new CSS/JS/images, they are probably used by a new page layout or master to being with so they will go in the same new feature.

 

3) Developers Pre/Post production day

During the initial development phase "pre-production day", developers should update their environment when they need it.  Since I have everything in Team Foundation, I created special CMD/Bath files for developers that helps them clean/create a site definition with some sub-sites already pre-populated.  This is enough for most cases.  It's clean and fast and they are up and running quickly.

 

"Post-production day", the site definitions will not be updated (although they can be appended), nor the features, so they should run the same script that add files in the database and install the new features.

 

SharePoint artifact deployment - Site Columns and Site Content types + library association

1) Pre-production "day 1"

Feature is the best mechanism to bring columns and content types.  Note that the feature has to be Site scoped so it will not bring the content types to a library unless you manually create a page through the GUI or that you use a content type association feature in your site definition.  You can take a look at Andrew Connell's STSADM extension for a good sample of exporting your columns/content types.

 

2) Post-production "day 2+"

Well we learned the hard way, since the MSDN documentation wasn't available back then, that if you add a column to a content type (in a feature), a "reinstall" of the feature will only bring the new column at the Site Collection level and it will not be replicated down to each libraries using that content type.  Fortunately, the user interface works great so if you do not have many columns to add, you may simply want to document the manual update.

 

But you know I like automation ... so yes, we are also fortunate with the API and it replicates down the change as well.  An STSADM extension that adds column + associate it to a content type can be done easily so that it reads an Xml input file with all the updates since Day 1.  When it runs, if the column's already there, it simply skips it and go check if the content type contains the association to it.

 

3) Developers Pre/Post production day

The same process will apply for developers.  However, since the "STSADM extension" isn't created until Day 1, they may either recreate their site collection or manually add the column/content types when a change occurs.  In my case, since creating a site definition is scripted, it goes very fast.

 

 

SharePoint artifact deployment - Custom lists

1) Pre-production "day 1"

A custom list is defined in a feature.  The definition contains the columns and types.  An instance of a list is defined in a Site Definition or through the user interface.  You can also populate rows of data for an instance of a list defined in the Site Definition.

 

2) Post-production "day 2+"

That one is tricker, you can update and reinstall the feature.  However, that will only affect new list creation.  I personally haven't gotten the need to add columns and data to a list post-production but I would likely need another little STSADM extension to update it.

 

3) Developers Pre/Post production day

Same process as the content types, if it's only a feature, then reinstall it.  If it's in the site definition, run the creation script.

 

 

 

SharePoint artifact deployment - Event Handlers, Feature Receivers, and Timer Jobs

1) Pre-production "day 1"

All of these are class items.  You may want to run code for a specific event on a library, run code when a feature's activated, or run code through a timer job at a specific time.  All of them are also originally brought through a feature.

 

2) Post-production "day 2+"

Now, this can be either very easy or much harder depending on how "politically correct" you want to be.  Technically (or less politically correct), the classes are either in the BIN or the GAC, if you need to update the code, you can simply deploy them without touching anything in SharePoint (beside an application recycling or an IISRESET).  That is, only if you kept the same assembly version.  

 

Unfortunately, if you want to be more politically correct, you'd have to change the feature, since it contains the assembly version, and reinstall it but there are cases when it seems that some references are "ghosted" somewhere in a database so it may not work.  If you want to be politically correct (and normally, we should) with assembly versions, I would strongly suggest doing tests.

 

3) Developers Pre/Post production day

For pre-production day, it's easy, the version isn't likely to change much so you are good to deploy the DLL and reset IIS/app pool.  Post production day will depend on what you chose in scenario 2.

 

 

Content Deployment with all this

As long as your site definitions, features, and assemblies are all deployed at the destination, Content Deployment will work great with your artifacts.  Sounds simple but even with all my run-ins with Content Deployment, it works good in that scenario.

 

 

Hope it helps a bit.  I know it's a bit sad that there isn't a "single scenario" and I'm still using STSADM extensions to do some updates, but remember, most of the updates are doable from either SharePoint Designer or the web user interface.  These 2 tools works good for the updates.  Unfortunately, this version of the product doesn't seem to include the fact that field WCM deployments often have a more rigid and secure environment and SPD users aren't likely to play in production or even staging.  That's when we, developers, want to automate the process and that's when we create STSADM extensions to fill the gap.

 

Maxime