John Ross

Someone once asked me how we upgrade code that has already been deployed.  It might sound like a simple question — I thought it was.  Wrong! It was a fantastic question which surprisingly wasn't documented in many places.  It is possible to manually upgrade the files on each server — but that can get quite tedious. In our case we had multiple web front ends so it was either manually update each file on every server (too complicated, and too many opportunities for mistakes) or use Solutions (automate the process of moving code to each of your WFEs).  The choice was a no brainer.

The answer to how you upgrade solutions lies in the following STSADM command:

stsadm -o upgradesolution -name <solution name> -filename <new solution name>….

Seems simple enough that the command upgradesolution would upgrade your solution.  There are two things to remember about this command:

1) The solution you are upgrading must have the same GUID as the original.
2) It only upgrades features and their related manifest files, as well as redeploys dlls and updates safe controls.

What it doesn't do is the most important part:

It doesn't update anything that is not referenced in a feature.xml, feature manifest, dll, or safe control.

In my case, I originally tried to include almost all functionality into my Site Definition.  It installed web parts, graphics, CSS, master pages, and templates.  The problem came when I tried to update something.  I wasn't able to update the files since everything was wrapped into the Site Definition.  Technically, ONET.XML is updated when you run upgradesolution – but it won't do any good for sites that are already deployed. 

Fixing the problem is simple — keep only the bare minimum in your site definition and add as much functionality as possible through features.  To call a feature from the site definition you reference it by its GUID:

<SiteFeatures>
    <Feature ID="C85E5759-F323-4EFB-B548-443D2216EFB5" />
</SiteFeatures>

NOTE: When you create your feature, it is important to make it hidden if you plan to call it from your site definition.  If it is not hidden, SharePoint will throw an error saying it needs to be activated first. 

When you need to upgrade a solution you'd run the STSADM command listed above with the appropriate options.  As a best practice it is normally a good idea to activate any features in the solution using the force option:

stsadm -o activatefeature -name myFeature -force…

One final post script – when deploying or upgrading to multiple WFEs it is important to use the -immediate option or specify a time.  Using the -local will only deploy to machine you are running the command from.  However, I ran into issues when upgrading some solutions where an error would be thrown.  Basically, the solutions would get deployed to some WFEs but not all.  Still have no idea why.  I did find a workaround that seemed to work most of the time.  I would first try to run the upgrade, it would throw the error and SharePoint would consider that the solution was no longer deployed.  Then, I'd run the same upgrade command without the -immediate tag which upgrades the solution offline.  Next I'd run the following command:

stsadm -o deploysolution -name <solution name> -local

This would deploy the solution to the server I was on without erroring.  Next I'd go into Central Admin > Operations > Solution Management and select the solution I was attempting to deploy and deploy it to the remaining WFEs. 

 Again, I'm not sure why this happened but I saw the same behavior in multiple environments.  I'd be interested to hear if anyone else has run into this.
 

Filed under: Uncategorized