SharePoint 2010: Solution Packaging

After you’ve developed your SharePoint solutions, how you package and deploy them is the final part of the process.

Steve Wright and Corey Erkes

Adapted from “Pro SharePoint 2010 Governance” (Apress, 2012)

When you’re developing solutions to use within SharePoint, you still have options as to how to package and deploy those solutions. SharePoint uses the solution framework to install custom enhancements within SharePoint environments.

The solution framework lets you deploy, activate and update custom components in a controlled manner. This structure is designed to keep the SharePoint server farm stable. Your solution packages can contain resource files for a consistent approach to localizing your custom components. The solution framework replaces other installer technologies used in Windows environments such as Microsoft Installer (MSI) files and ClickOnce.

Solution packages also provide a means to bundle all of the components associated with a custom enhancement into a file with a WSP extension. You can then deploy these files to the farm so all the components install simultaneously on all servers within the farm. This removes the need to maintain Web page files, templates and executable files separately on each server.

The SharePoint 2010 solution framework also includes new features that help you update solution packages in place without interfering with farm operation. You can do this by versioning each deployed feature and providing custom actions for upgrading from one version of a feature to another.

Solution packages

A solution package file is a single file with a WSP filename extension. However, what appears to be one file may in fact be several files archived into one. The WSP file format is actually nothing more than a standard Windows cabinet (CAB) file. To prove this, take any solution file and change the extension from WSP to CAB. Now open the file and you’ll see the file structure.

There’s a package manifest file in the root directory and one or more subdirectories containing the other components. Many of these components are XML files with configuration information for lists, sites, content types and so on.

The most-common files you’ll find in a solution package are:

  • Manifest.xml: There’s one manifest file in a package. It contains a description of everything in the package, either directly or through references to other files.
  • Feature.xml: These files describe the configuration and components associated with a feature. You can turn these on or off in the SharePoint environment.
  • Elements.xml: These files contain lists of individual components and their configuration information. Components are items such as list instances, content files, site columns, content types and event receivers.
  • Schema.xml: These files contain the metadata specifications for an object such as a list template.

There are many other types of files that appear in a solution package, but these are the most important. They control the feature and component configuration. Before you use them, you need to understand a little about the environment to which they’ll be deployed.

Understand deployment environments

When you deploy a solution package to a SharePoint server farm, it deploys in one of two runtime environments. The first environment is the server farm itself. This gives the solution components the ability to access resources throughout the farm and beyond, within the limits of the access permissions on those items.

The second environment—the sandbox—is far more limited. When a solution package is running in the sandbox, its ability to affect the farm as a whole is restricted. Understanding the difference between farm solutions and sandboxed solutions is critical to deployment planning for custom enhancements.

The first thing to consider is where the solution will be deployed. Farm solutions are global to the server farm. Sandboxed solutions are local to a specific site collection. If multiple site collections need to use your sandboxed solution, you’ll have to deploy to each one separately.

The most important difference between farm and sandboxed solutions is security. Farm solutions generally run with full trust. Using .NET Code Access Security (CAS), you can create farm solution components that run with less than full trust. This is a good idea from a security standpoint because it lets the code run with the minimal set of privileges needed. You should reserve farm deployment for well-tested and highly trusted code.

Sandboxed solutions run in a very different security environment. Their access to resources is limited to the site collection in which they’re deployed. There are also resource restrictions and quotas you can apply to prevent rogue solution components from compromising system performance. You can easily disable misbehaving sandboxed solutions and prevent them from running entirely, if needed.

Manage your farm solutions

Deploying a solution package to a SharePoint server farm consists of two basic operations: Add and Deploy. The Add operation uploads the solution file into the SharePoint configuration database, where it can be accessed by each server in the farm. Deploy installs the files into various file system directories on each server in the farm.

Only farm administrators can add solutions to the farm solution store. There’s no page in Central Administration that lets you upload a package. You have to do this with a command-line tool. You can also add solutions using the SharePoint API.

To use the STSADM tool to add the package, use a command such as the following:

stsadm -o addsolution -filename MySolution.wsp

To perform the same operation using Windows PowerShell, use a command such as the following:

Add-SPSolution -LiteralPath MySolution.wsp

Once the Add operation is complete, the package will appear on the Solution Management page of the Central Administration site. Although you’ve uploaded the package file, its features aren’t yet ready to use. At this point, the solution files haven’t been installed on each SharePoint server.

Now that you’ve added your package to the farm solution store, you’re ready to deploy it to the farm. There are two ways you can deploy a package from the farm store: local deployment and via a timer job.

A local deployment installs the solution files on one server in the farm. You can only do this type of deployment using the command line. It will only affect the server upon which it will run. You won’t be able to use your solution until it’s deployed on all of the farm’s servers. Therefore, you’ll have to repeat the deployment process on each server.

The more common type of deployment uses the SharePoint Timer Service. You can deploy this way using either the command line or the Central Administration Web site. When you start the deployment, SharePoint creates a timer job that will run on each server in the farm. This has the same effect as performing local deployments on each server.

Besides letting you deploy in a single step, timer job deployments also automate the process of restarting the IIS worker processes. You have to do this to let SharePoint properly recognize the new solution’s files. There might be a brief outage when the IIS worker process is restarted, but it shouldn’t last more than a few seconds in most cases.

To perform a farm deployment from the command line, you can use either the -deploysolution option on the STSADM tool or the Install-SPSolution cmdlet in Windows PowerShell. (Note that the Windows PowerShell cmdlet is called Install-SPSolution, not Deploy-SPSolution.)

Both of these commands have a -local flag to perform a local deployment. To use a timer job that will run at a given time, use the -time option on either command. To use a timer job that executes immediately after entering the command, use the -immediate option on STSADM or just leave the -local and -time options off of the Windows PowerShell command.

You can specify several other options when deploying a farm solution. Here are a few of the most important:

  • Web Application: Some solutions have resources you’ll need to deploy within the IIS Web application directory structure. When deploying a solution, you can select a set of Web applications to target for these resources.
  • Global Assemblies: If the solution package contains assemblies you need to deploy to the Global Assembly Cache (GAC), there’s an option that prevents you from unknowingly deploying fully trusted code.
  • CAS: CAS policies control the permissions granted to partially trusted code running in the farm. If a solution package contains new CAS policies, you’ll have to flag this.

You can also deploy a solution from the Central Administration Web site. Select System Settings from the left menu. Then select Manage Farm Solutions. A freshly added package will be displayed with a status of Not Deployed.

Click the package name and you’ll see a screen with useful information about the package, including whether it contains items that require special handling during deployment such as fully trusted assemblies or CAS policies. Click the Deploy Solution link to display a form you can use to start a timer job for deployment. You can’t perform local deployments through the Web interface.

Deploying a sandboxed solution to SharePoint is very different from deploying a farm solution. Instead of an Add followed by a Deploy, a sandboxed deployment consists of Deploy and Activate steps. However, using a sandbox is an effective way to test solutions before deploying them live.

Steve Wright

Steve Wright is a senior manager in business intelligence management for Sogeti USA LLC in Omaha, Neb. Over the last 20-plus years, Wright has worked on air traffic control, financial, insurance and a multitude of other types of systems. He has authored and performed technical reviews for many previous titles covering Microsoft products including Windows, SharePoint, SQL Server and BizTalk.

Corey Erkes

Corey Erkes is a manager consultant for Sogeti USA LLC in Omaha, Neb. Erkes has worked with a wide range of companies at different points in the lifecycles of their SharePoint implementations. He’s also one of the founding members of the Omaha SharePoint Users Group.

©2012 Apress Inc. All rights reserved. Printed with permission from Apress. Copyright 2012. “Pro SharePoint 2012 Governance” by Steve Wright and Corey Erkes. For more information on this title and other similar books, please visit