Using Features and Solutions to Deploy your SharePoint Customizations

When deploying any Sharepoint application, the way to do it is through 'Features and Solutions'. There are two recommended paths of deploying custom functionality into SharePoint: Sandboxed or Farm Solutions. Which should you choose, and in what circumstances? Dave McMahon talks us through a Sharepoint deployment with Sharepoint 2010 and VS 2010 and finds it pretty easy.

One of the questions you always have to answer when building a web application, or indeed any application, is ‘How do I deploy my application and any subsequent updates?’. In SharePoint the answer to this question is pretty clear cut, and as black and white as can be. SharePoint is a platform with an accepted methodology of deployment, and that methodology is Features and Solutions. If you’re not using features and solutions to deploy your customizations, you’re not doing it right.

‘But Dave, I’ve only one SharePoint farm and I do it all using SharePoint Designer!’

It’s a fair comment, and I’d say in response, ‘What are you doing with only one farm?’. If you have a production farm, don’t you test your changes before you deploy? Don’t you want a rollback? Don’t you want versioning? Don’t you want a repeatable update process?

Get another farm, even if it’s only one box, a virtual box, your workstation, whatever you can lay your hands on. Use SharePoint Designer to make your changes on a development farm, ready for deployment to test and live and use features and solution files to deploy your changes to your production systems.

What are Features?

So what are these features I’ve mentioned?

Well, features are packages of functionality that you can activate or deactivate in a SharePoint farm. They have four possible scopes:

  • Farm
  • Web application
  • Site
  • Web

A farm level feature, as the name suggests, is something that affects the whole farm, for example provisioning a custom timer job or deploying a Business Connectivity Services model.

A web application feature can be activated so that it only affects a single web application, and a typical example is a feature that modifies the web.config file.

A site scoped feature can be activated so that it only affects a site collection, an example being the deployment of a master page to the master pages catalogue.

Finally, a web scoped feature can be activated for a single site, for instance setting the default master page for that site.

What are Solutions?

‘And what are these solution files?’ you may ask.

They are the files you use to deploy your changes to SharePoint. They have the WSP file extension, and are often referred to as just WSP files. In reality, they are cabinet files that contain your customizations, plus a manifest XML file that tells SharePoint how to deploy your changes. In fact, when you first see a WSP file, I encourage you to change the file extension to CAB and use Windows Explorer to browse the contents of the file. Open up the manifest XML file and look at its structure; it will tell you a great deal how SharePoint deploys your customizations.

In SharePoint 2010 there are two types of solutions: farm solutions and sandboxed solutions.

Farm solutions are the same as the solutions we had in SharePoint 2007 and are deployed to the farm. In layman’s terms, your application or update is deployed as is; files on the file system are deployed exactly as that, files on the file system.

Sandboxed solutions are new to SharePoint 2010 and deploy your files to the SharePoint Content Database (see my previous article Visual Studio 2010 and SharePoint 2010: Support at Last.

You have a decision to make right here about how you are going to package your features: farm or sandboxed solution? Often the decision is made for you: sandboxed solutions permit only limited functionality (again, see Visual Studio 2010 and SharePoint 2010: Support at Last) but are available on a wider variety of SharePoint platforms including Office 365, previously known as BPOS. On the other hand, farm solutions allow the full functionality of SharePoint but are usually only deployed to dedicated farms. Whether a solution can be farm or sandbox is primarily determined by its contents, including the scope of the features it contains.

If your solution contains either a farm or a web application scoped feature, it can only be deployed as a farm solution.

Solutions that only contain site and web scoped features can usually be deployed using either a sandbox or farm solution. However, be aware that unless you take care, you could successfully deploy code using a sandboxed solution that is not permitted to run. The Community SharePoint Kit for Developers contains a great tool which limits Intellisense Visual Studio 2010 to show only supported methods and properties when building for sandbox solutions.

Sandboxed or Farm Solutions?

As I previously mentioned, whether you design for sandboxed or farm solutions is often driven by project requirements. Let’s say I want to deploy a new master page for a site; this is perfectly achievable through a sandboxed solution. But then let’s also say I need to deploy a new custom control that I’ve included in the master page, and that control needs to be deployed to the %SharePoint Root%\Template\CONTROLTEMPLATES folder as an ASCX file and its associated DLL needs to be placed into the GAC; now the story is different and I have to deploy using a farm solution.

As a guideline, the accepted best practice is to aim for a sandboxed solution initially, but move to a farm solution if your project functionality dictates this. However, it is important to remember that hosted SharePoint environments will often only permit sandboxed solutions, so in this case the platform is a major influencer in your decision.

Looking at an Example Deployment

Let’s take a look at this framework for deployment in more detail. As usual, the best way to do this is by the way of an example. We’ll use the example of deploying a custom master page for our SharePoint site. We’ll look at designing it and testing our deployment on our development farm, and we’ll define a rollback too, so that when we want to, we can restore our old master page. We’ll deploy this as a sandboxed solution.

Then we’ll add in a custom ASCX control and see that we must convert the solution to a farm solution and redeploy. At the end of the article you should have a good understanding of how to write features, and how to deploy them using either farm or sandboxed solutions.

Setting up the development environment

To recreate this demonstration you will need to install on your PC:

You should also install the Community Kit for SharePoint (CKS) – Development Tools Edition, as we will be using the Starter Master page Template Item from this to speed things up.

The Visual Studio project files for the example are available to download.

Creating the visual changes

First off, we need to make the design changes to our custom master page. I’ll use SharePoint Designer 2010 (SPD2010) to implement these changes (we will take a look at SPD2010 in a future article and examine some of its great new features).

So, open SPD2010, click Open Site, enter the URL of your site into the Site Name text box, and then click Open.

Next, in the left-hand Navigation Pane, select Master Pages and highlight the line that says v4.master. Don’t click the hyperlink – this will take you into the properties window of the page, which we don’t want at this time.

Now, right-click and select Copy, then right-click again and Paste. Then, right-click a third time and click Rename. Rename the master page to simple-talk.master.

Finally, do yet another right-click and select Set as Default Master Page. You can now edit simple-talk.master in SPD2010 if you wish, and immediately see the changes in your SharePoint site.

The extent of our styling of the master page will not be too much of a stretch. Add in mark-up as shown in Code Sample 1 just after the <div>; tag with an id attribute of s4-mainarea, and then save, clicking Yes when asked if you wish to continue customizing your page.

Code Sample 1: Custom mark-up in master page

Your home page will now have a brownish bar across the page, under the top navigation menu bar.

1271-01-CustomMasterPage.png

Code Sample 1: Custom mark-up in master page

If this was the only site collection or farm we had, that would be it. But I’m assuming you now wish to deploy this change to other site collections or farms. In order to do this we now need to create a deployable feature.

Creating the feature

Open up Visual Studio 2010 and select File -> New -> Project. In the Add New Project dialog box (shown in Figure 2), under Installed Templates, select SharePoint -> 2010, highlight Empty SharePoint Project, and then name your project accordingly.

1271-02-NewProject.png

Figure 2: Add New Project dialog box

Next, on the SharePoint Customization Wizard dialog box, we want to select Deploy as a sandbox solution. Add in the URL to your site collection, which should be different from the one you edited your master page in, and click Finish. This will create a project called SimpleTalk.

Now select the SimpleTalk project node in the Solution Explorer, right-click and select Add -> New Item, then select Start Master Page (CKSDev), give it a name of simpletalk and click Add.

At this point we have all the files we need to deploy our master page and we just need to do a little cut-and-paste. But let’s examine in a little more detail what we actually have in the solution, which should now look as in Figure 3.

1271-03-SolutionExplorer.png

Figure 3: SimpleTalk Solution Explorer

The feature folder contains two files used by Visual Studio 2010 (VS2010) for constructing the final feature that SharePoint will need in order to deploy your master page. These files are:

  • The feature control file with the extension .feature; this is used by VS2010 only and is never deployed.
  • The feature template XML file. This contains the outline XML that VS2010 will use to construct the final feature.xml file, which must be present in a SharePoint feature. This too is used only by VS2010 and is never itself deployed. 

It is the feature.xml file which actually gets deployed and which tells SharePoint 2010 what is in the feature, and thereby what SharePoint needs to do with the files associated with the feature. The feature.xml file will only be created when you instruct VS2010 to package your solution.

Next, we see the package control file and the package template. This works in a similar manner to the feature. Neither of these two files ever gets deployed, but they are used by VS2010 to construct a file called manifest.xml, which exists in the WSP solution file.

Finally, the folder simpletalk has been added with two files: Elements.xml and simpletalk.master. The second is plainly an ASP.NET Master Page; the former is another SharePoint specific file, and whilst it does not strictly need to be called Elements.xml, by convention it nearly always is. The Elements.xml file in this case looks as shown in Figure 4:

1271-04-ElementsXML.png

Figure 4: Elements.xml file

All this mark-up has been added by the CKS Item and will tell SharePoint that a file called simpletalk.master should be made available at a relative URL _catalogs/masterpage. Most of the other properties are metadata and should be replaced with meaningful data, and one I will mention specifically is Type='GhostableInLibrary', for two reasons:

  • Reason one is that this is the attribute that tells SharePoint that this document should be made available and versioned through a document library, which means that any change to the document through SPD2010 will result in the file being uploaded into the SharePoint content database and thereafter that is where the source code for the file will be held.
  • Reason two is that without this attribute, you will not see the document in the library listing and for some inexplicable reason it is omitted from the standard SharePoint Module Template in VS2010, which is why I used the CKS Template.

I want the feature to be scoped at the SiteCollection level, which means that it is available to all sites within the SiteCollection. I can do this quite easily in the Feature Designer shown in Figure 5. So, double-click on the Feature1 folder and in the Scope drop-down list change the scope to Site. We can see the simpletalk item is included in the feature as it is shown on the right-hand side of the designer.

1271-05-FeatureDesigner.png

Figure 5: Feature Designer

All we need to do now is copy the mark-up from our master page in SPD2010 and paste it into the simpletalk.master file in our VS2010 project, then save the master page. Once that is done we’re good to go.

Deploying our feature

To deploy our feature, we need to do the following:

  1. Add it to a solution.
  2. Upload it to the Site Collection Solution Store.
  3. Activate the solution.
  4. Activate the feature.

Sounds a lot of work to you? It does to me too. And in Microsoft Office SharePoint Server (MOSS) 2007 it was, but now with VS2010, it’s a breeze. Just right-click the SimpleTalk project and click Deploy. Wait a few seconds, and then open your SharePoint site and select Site Actions -> Site Settings -> Galleries ->Solutions, and you will see your solution appearing in the solutions gallery as in Figure 6. Note that the status is Activated, so the relevant features have all been deployed.

1271-06-SolutionGallery.png

Figure 6: Solution Gallery

Select Site Actions -> Site Settings ->Site Collection Administration -> Site Collection Features, scroll down, and you should see the feature has been activated as shown in Figure 7:

1271-07-SiteFeature.png

Figure 7: Site Collection Feature

Finally, select Site Actions -> Site Settings -> Galleries -> Master Pages and page layouts. You will then see your deployed master page in the master page gallery.

1271-08-masterPageGallery.png

Figure 8: Master page gallery

Where is our brown bar? We haven’t set it as the default, so the master page is still the original v4.master. Let’s enhance our feature so that it sets our new master page as the default master page.

Enhancing the feature with code

In our Visual Studio project, select the Feature1 folder, then right-click and select Add Event Receiver, which will create a class called Feature1.EventReceiver.cs.

We will add code to two protected overridden methods. Insert the following code into the FeatureActivated and FeatureDeactivating methods:

Code sample 2: Feature code

In a production environment you will need code that is a bit more defensive than this, but it will suffice for our example. So what does this code do?

This line retrieves a reference to the site collection in which we are deploying the master page.

This creates a reference to the root web site of the site collection.

This stores the existing master page URL into the ‘bucket’ collection for the root web site.

The next line is the line that actually sets the new master page.

The Uri object AbsolutePath property is used to ensure the correct path to the master page is used. The URL relative to the SiteCollection is read from the Feature Properties, a collection of user properties that you can add into the Feature.Template.xml shown in Figure 9:

1271-10-FeatureXML.png

Figure 9: Feature Properties

This configuration property is then available at runtime and makes your code more generic.  To ensure your changes are saved we must include the following line:

In the FeatureDeactivating code, we simply restore the original master page. The ability to rollback is one of the key benefits of using features and solutions, and I recommend that you always properly test rollback code in the FeatureDeactivating method.

With this code in place, just hit Deploy again. This will build and package your solution, deactivate the existing feature, retract the existing solution, deploy your revised solution, activate the solution, and activate your feature. So wait a few seconds and you will see your site with the SimpleTalk brown band across the page beneath the top navigation menu, as shown in Figure 1 above.

Adding in a user control

Let us now enhance our interface by adding in a user control that simply outputs the current date. There is a multitude of ways of doing this, I know, but I’m illustrating a point here. In VS2010, highlight the SimpleTalk project, right-click and select Add -> SharePoint Mapped Folder. In the dialog box, select TEMPLATE/CONTROLTEMPLATES. You will now have a mapped folder and all files in this folder will be deployed into the CONTROLTEMPLATES folder under the SharePoint root folder known colloquially as the 14-Hive, which is normally located at:

Right-click the CONTROLTEMPLATES folder and select Add-> New Item, and then select UserControl. VS2010 will now add in a user control and all the necessary Assembly and Register Directives. In Figure 10 you can see this code as well as the additional line I’ve typed in:

which is the ASP.NET Label control that will hold the current date.

1271-11-UserControlMarkup.png

Figure 10: UserControl mark-up

Notice the placeholder $SharePoint.Project.AssemblyFullName$. This will get replaced at packaging time with the full name of the assembly that the project gets built into.

The code-behind file is simple, and gets created in the project when you create the UserControl. Open up the code-behind file and you will see there is already a Page_Load event handler provided for you. Add the following line into the Page_Load event:

Your code file should now look as shown in Figure 11.

1271-12-UserControlCodebehind.png

Figure 11: User control code-behind

This code simply sets the text of the label to today’s date.

Finally, we need to amend our master page to include the new control, which we do by adding in an ASP.NET Control Register Directive at the top of the master page as follows:

And further down the page where we added in our brown bar mark-up, we alter the mark-up to add in the control itself as follows:

However, if we now go ahead and click the Deploy button, we will get an error and for once the error message is pretty self-explanatory and highlights one of the limitations of sandboxed solutions:

1271-13-SandboxSolutionError.png

Figure 12: Sandbox solution error

Why is this?

As I mentioned in Visual Studio 2010 and SharePoint 2010: Support at Last ), if a solution needs to deploy items to the file system as a sandboxed solution we cannot deploy it as a sandboxed solution. In this case, we choose to revert to a farm based solution. We do this very simply; by selecting our project, and then, in the Project Properties window in VS2010, we change the Sandboxed Solution property to False.

1271-14-ChangeToFarmsolution.png

Figure 13: Changing to a farm solution

As an aside, the move to a farm solution may not be possible, such as in some hosted SharePoint scenarios. In these cases, we have to use alternative methods to achieve the functionality we require. In this situation, a simple piece of JavaScript would suffice, but plainly this will not always be the case. We will examine this issue in another article.

Now if we click Deploy everything works fine. You will notice that the Application Pool has been recycled and so the page takes longer to come up the first time. This is a fact of life with farm solutions; the Application Pool always gets recycled. With sandboxed solutions this is not the case.

Once the site comes back up you should see the brown bar and the date as shown in Figure 14.

1271-15-FinalMasterPage.png

Figure 14: The final master page

Deploying into production

To complete the deployment to a production system, we take our WSP file, which you can find in bin/Debug, and upload this to the relevant solution gallery on our production server. We then activate the solution in that environment. We can do this using PowerShell, which we’ll take a look at in another article soon.

Summary

So what have we learnt? Well, we’ve learnt there are two recommended paths of deploying custom functionality into SharePoint: sandboxed solutions and farm solutions. Sandboxed solutions have least impact on the farm but have limited functionality as a result. Farm solutions allow you to do anything, but as we have seen they can affect the whole farm on deployment. We’ve seen how easy it is to create features, both declarative and code-based, and deploy and test them using VS2010 in a development environment.

Hopefully you now have a good appreciation of how simple it is to build and deploy your own custom functionality for SharePoint 2010 using VS2010, compared with MOSS 2007.

In future articles we’ll look at how to overcome some of the limitations of sandboxed solutions, and also how to use PowerShell to deploy your solutions in a production environment.

1555-ANTS_60x60_Logo_CP.gif How does your SharePoint application perform? The Beta release of ANTS Performance Profiler 8 adds support for SharePoint 2013, helping rapidly identify and understand SharePoint performance issues. Try the Beta.