What Magick Solves in SharePoint

A little while back, I talked briefly about a SharePoint solution framework I built some years back, that I’ve now decided to dub Magick the Framework.

In this article, I want to talk about the problems that Magick solves and why it makes your SharePoint development life much easier. I’ll stay away as much as possible from technical lingo, but to understand what really goes on, you need to understand the basics of SharePoint solutions, features, and some Microsoft policies.

Let me elaborate…

What You Need to Know

First, you need to know that a SharePoint solution in this context is a WSP file, whether a farm solution or a sandbox solution.

A solution is basically a compressed file that contains files and instructions on how to deploy those files to a SharePoint farm. Think of them as software installation packages for SharePoint; like a setup.exe file is for Windows.

When third tier developers build things for SharePoint, they usually end up with a WSP file that they then hand over to a farm administrator for installation. The farm administrator will then install and deploy the solution and the components of the solution then becomes available to users of the farm.

These components are often of a specific type called features. A SharePoint feature can simplest be explained as being a plug-in to SharePoint that extends the default functionality of SharePoint somehow. Features are extremely powerful and flexible,  and can both deploy things like web parts, list and list templates, new sites, or they can perform specific actions when you activate them.

The last thing you need to know is something about Microsoft’s policies on modifying components after they have been deployed.

There are specific guidelines on what can be changed and what cannot be modified in certain situations. To make it very easy to understand and to avoid a lot of confusion, you can remember that for almost all things, you cannot make changes to any deployed solution, feature, template, or page after it has been deployed once.

Note: There are certainly exceptions to the rule, but if you remember to not change anything after deployment, you’re safe.

These policies exist for very good reasons. In SharePoint, features, templates, and solutions are recipes for what needs to be done. Just like when you are making a dish from a recipe, the result is not dependent on the recipe after it has been created. In other words, if you bake a loaf of bread and then change the recipe, the bread you already made doesn’t change; only future loaves fill be different.

However, there are exceptions to this as well. For example, list definitions or pages actually exist in the features and go away if you remove the features. This is by design, and if you utilize it the way it is meant to be utilized, you create a very powerful system for managing content.

The catch, though, is that when you modify an existing component, because it can partially be a recipe and partially a template, your recipe and template no longer matches what is on the site. In fact, the site itself can completely break down because the site expects certain components of certain functionality to be there.

In short, then, when you have deployed your solution once, you should never expect to be able to change that solution again, which places a huge burden on the design and architecture; if you make mistakes, you’re never going to be able to fix it.

Magick seeks to solve this challenge without breaking any of the Microsoft policies on changes. In fact, Magick allows you to be even more strict with your own policies than Microsoft demands, but without sacrificing any of the flexibility.

Key Principles of Magick

To accomplish this goal, Magick encourages certain patterns and principles in the way you develop your SharePoint solutions.

1. Use as little static code as possible

The first and by far the most important principle is that we want to limit the amount of code that cannot be changed or is static. We can’t break Microsoft’s policies about changing deployed content, so we want to minimize the chances of us wanting to do so.

The most visible aspect of this is how you design site templates or site definitions. In Magick, you want your site templates and site definitions to be as empty as possible. In fact, a site definition that contains absolutely nothing is perfect.

Of course, a completely empty site isn’t very useful, which brings us to the next principle of Magick.

2. Make all components atomic

This principle means that you break down your functionality into as small pieces as possible, and have each component do one thing and one thing only.

For example, although it is possible to have a single feature that both deploy a list definition or template and that creates a list instance from that definition, doing so means that you break the principle of atomic components. Instead, you should have one feature that deploys the definition or template and another feature that creates the list.

Of course, this means that you get a lot of work managing all those components or features. There are ways around this, however, and I’ll get to those later, but let me first bring up the third principle of Magick.

3. Deploy once and never touch again

This is the part where Magick encourages more restrictive policies than Microsoft. Rather than focusing on what you can change, deploy code in such a way that you never need to change it again.

This policy guarantees that we remain compliant with Microsoft’s requirements. If we deploy supported functionality and don’t touch it again, there’s no chance that we’ll touch anything that Microsoft prohibits us from modifying.

There is one exception to this principle. Regardless of what we define in our solutions, we can always modify and redeploy .NET components. Only declarative components like definitions, templates, and ASP.NET markup pages must remain static after deployment.

In fact, this principle makes it somewhat difficult to deploy upgrades to a site without using .NET feature receivers. Because we can never change a component, feature, or solution after we have deployed it once, we are limited to what we can do with new solutions to what we can accomplish by deploying new components.

.NET gives us far more options because we can run code to analyze the current setup and make decisions or even change or modify content based on what we see. Declarative (i.e. non-managed code) components have a lot fewer options for modifying content.

This also brings me to a fourth and optional principle and the solution to the management of all those features I mentioned.

4. (Optional) Use .NET feature receivers to install and activate functionality

In the first article, I mentioned that building .NET code is completely optional. That is absolutely true, and with the exception of installing the framework itself, there’s no hard requirement for you to ever deploy a single .NET component again.

However, if you don’t use .NET feature receivers, you miss out on a great way to ensure your solutions are deployed smoothly.

The most common example of this principle is in creating a Setup feature. A Setup feature in your solution is ultimately responsible for setting up (doh!) all the other components.

Let’s imagine, for example, that you want to create a project site based on the Team Site template. To do so, you may need to activate a range of list instance features, possibly some list template feature, certainly some content type features, and maybe some web part features.

Of course, because of the way SharePoint works, you need to activate these features in a particular order. You cannot activate a list instance before the template for creating that instance is activated, and you may not be able to activate that template until the content types are in place.

Doing so manually means that you need to go through a lot of hoops and users have a lot of chances to make mistakes. We don’t want to expose our users to that risk, so instead, we create a Setup feature.

Note: If you’re really allergic to .NET code, you can accomplish some of the basic functionality of a Setup feature using feature activation dependencies. However, Magick can still provide a better approach than using feature activation dependencies even without any .NET code at all.

How? Well, I just told you: it’s Magick!

The Setup feature will ensure that all the features are activated at the right time, in the right order, and at the right scope. Because we’re writing .NET code, we also have the opportunity to dynamically change the way we set up our components as well, and we can even catch errors and fix them automatically or at least present them to the users in a more user friendly manner than “Something went wrong” and a cryptic correlation token.

For the user, a Setup feature presents itself as a single and quite normal feature to activate to get everything set up the way the developers intended. This is in contrast to following a series of steps that must be done in the correct order or else chaos will ensue (and we don’t want Chaos Magick, do we?).

Magick takes away that complexity, even without .NET code, so as long as you follow the principles outlined here, and the very simple pattern that Magick requires, your users shouldn’t feel a thing when you want to set up a new solution or upgrade an existing solution for them.

With these principles in place, we can start looking at how Magick accomplishes its goal of solving the problems of installing, maintaining, and upgrading SharePoint solutions over time. I’ll get back to that in a later article, however, again as time permits.

For now, feel free to ask questions if you have them, and I can try to include the answers in future articles.


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.

One thought on “What Magick Solves in SharePoint”

Leave a Reply

Your email address will not be published.