Magick Upgrading in SharePoint

Key to the Magick framework for SharePoint solutions is the concept of upgrades.

In previous articles, I’ve outlined how Magick supports and encourages certain principles that are important to building maintainable and upgradable SharePoint solutions. Now it is time to get a bit technical and look at how this actually happens.

There’s a bit of theory still, though.

Magick Solution Structure

Everything in Magick is by convention only, except for one single requirement.

By “convention only”, I mean that you are free to design your solutions in any way you like. You can use any development tool you like (WSPBuilder, VSTools for SP, STSDev, or Notepad), you can follow any patterns you like, and you can combine all of these in any way you like.

There’s one single requirement, though, and that is that you tag your features with a certain custom property.

Features in SharePoint support custom properties just fine, and they’re simply ignored if not used, so this requirement is a very basic and non-intrusive requirement.

The reason for this requirement is that these custom properties are how Magick determines what to do with those solutions.

There are two custom properties you need to add to your features. The first property, called UpgradeSolutionID tells Magick which upgrade path you want to take. The second property, called UpgradePriority, is a number that tells Magick in which order to run the upgrades.

An example feature may look like this:

<Feature xmlns=”http://schemas.microsoft.com/sharepoint/”
Title=”My Magick feature”
Description=”Some description”
Id=”b5c82b69-ac82-4a34-8b80-49f39628e51a”
Scope=”Web”>
  <Properties>
<Property Key=”UpgradePriority” Value=”15″ />
<Property Key=”UpgradeSolutionId” Value=”Magick” />
</Properties>
</Feature>

I’ve highlighted the custom properties section, which you need to add to any features that you wish to add to Magick.

That’s it! If you learn how to add those custom properties (or simply copy them from here) you’re done. There’s no need to learn anything else, really, and there’s no need to make any other changes to any features.

How Magick Really Works

You may be surprised by the simplicity of the changes required to create Magick features, but don’t be deceived by this simplicity. Behind these properties lies an awesome power with virtually no side effects, and you can build some pretty complex multi-path upgrade scenarios.

I’ll go into detail on Magick and the 42 lines of the framework later, but for now, let me explain how Magick uses these properties to handle your upgrades.

In Magick, there is a single feature, called and Upgrade feature, which handles all the hard work for you. This is where those 42 lines reside.

When activated, the Magick Upgrade feature will go through all features in your farm and look for features that have those two custom properties added. Then, it will sort them in the order of the UpgradePriority property, and finally, it will activate all the features that haven’t been activated already.

This too may sound extremely simple, and it is, but again, this simplicity hides awesome power and incredible flexibility.

Let’s say that you want to add a certain list with an attached content type. Using Magick, you would then add a feature to create the list, a feature to create the content type, and finally a feature to connect the content type to the list.

Your features would then, for example, have the following UpgradePriority numbers:

  • 15 List creation (web scoped)
  • 25 Content type creation (site scoped)
  • 35 Connect content type to list (web scoped)

Upon activating the Magick Upgrade feature, Magick will activate these features in order, even if they have different scopes. You don’t need to activate the individual features yourself or ask your users to do so.

After activation, the Magick Upgrade feature automatically deactivates itself so that it is ready to be activated again. Of course, because Magick only activates features that aren’t activated, clicking it again won’t reactivate the existing features, so there’s no danger of getting two lists.

Next time you want to make changes to your sites, you create a new solution with new features and ensure that you have unique UpgradePriority numbers, and upon activating the Magick Upgrade feature, those features will be activated for existing sites. For new sites, all features will be activated, and you’ve ensure that all your sites have the same features activated.

Neat, eh?

Can I use this for existing features?

A possible, although not supported, scenario is to tag existing features with the Magick custom properties. For example, if you want the Publishing framework to be available, you can technically modify the feature.xml file of that feature and add the custom properties to have Magick add it for you.

Keep in mind, though, that modifying existing features, especially the out-of-the-box features that ship with SharePoint, is not supported.

You can, of course, tag any of your own features as much as you like, to ensure you at least get your features activated in the correct order.

Paths and Priorities

The two custom properties that Magick needs give you great flexibility in targeting different exactly what to upgrade. I’ll go into more detail on how you can customize these properties to create different upgrade paths.

In this context, and upgrade path means a group of upgrades that Magick will handle as a separate set of upgrades. With a few modifications, you can even get Magick to automatically pick the right path for you.

If you’re allergic to .NET development, this means you actually need to have multiple features to activate multiple paths.

For example, you may want to have one path that upgrades Team Sites and another path that upgrades your custom Project Sites.

To accomplish this, you need to tell Magick which path to upgrade. There are multiple ways to accomplish this, and I’ll dig into the details of how to do so once I show you the actual code.

It is also vital that you keep track of the UpgradePriority numbers you have used. This is really a matter of strategy, and I’ll share some of my experience in picking such priorities with you. In short, however, a good strategy allows you to inject upgrades into previous solutions. For example, you may find out that as part of your content type deployment, you really wanted to add a new form to the list first. With Magick, that’s as simple as deploying a new feature with an UpgradePriority that precedes a previous feature.

Like I said, I’ll go into more detail on strategies later, and next, I’ll also show you the framework code that makes Magick… well, Magick.

.b

Found this article valuable? Want to show your appreciation? Here are some options:

a) Click on the banners anywhere on the site to visit my blog's sponsors. They are all hand-picked and are selected based on providing great products and services to the SharePoint community.

b) Donate Bitcoins! I love Bitcoins, and you can donate if you'd like by clicking the button below.

c) Spread the word! Below, you should find links to sharing this article on your favorite social media sites. I'm an attention junkie, so sharing is caring in my book!

Pin It

Published by

Bjørn Furuknap

I previously did SharePoint. These days, I try new things to see where I can find the passion. If you have great ideas, cool projects, or is in general an awesome person, get in touch and we might find out together.

3 thoughts on “Magick Upgrading in SharePoint”

  1. Hey, I purchased and read your professional SP dev journal a while back and I like the upgrade framework. BUT, with the new ReplaceContent attribute in SP2013 it’s very easy to swap the content of files, declaratively. Especially in apps, where they tell you to modify the original files (CSS, JS, display templates, page layouts, etc) and then use ReplaceContent to swap the content of the files during a solution upgrade.

    It’s nice to be able to drop in a new elements file, specify the changed files, and use applyelementmanifests to upgrade the files. I also name the element files with the version e.g. 1.0.1.0-Elements.xml, 1.0.2.0-Elements.xml, etc. which makes it really nice to see what files have changed during each upgrade. As for content type changes, I either declaratively add fields in the feature upgrade xml, or use a custom upgrade action to do anything else.

    I think your upgrade framework is great for previous versions of SP but with the latest improvements in SP 2013, I’d love to hear your opinion on the advantages of using your framework (in SP 2013).

      1. There’s obviously more flexibility in C# code but you can run that from a custom upgrade action too. I’m trying to make a case for using your framework with new projects but I’m struggling to see the benefit over the new-ish upgrade features. I’m guessing you’ll touch on the ability to selectively upgrade features from the UI, by activating the upgrade feature.

        But there’s also the disadvantage of feature sprawl with all of the upgrade features (even though you can hide them it still feels like feature sprawl.

        I’ll wait for your post.

Leave a Reply

Your email address will not be published.