Deploy solution packages (SharePoint Foundation 2010)

  • Article

 

Applies to: SharePoint Foundation 2010

This article describes solution packages and the role they play in deploying authored and developed customizations in Microsoft SharePoint Foundation 2010. It includes procedures for importing and deploying solution packages, and an example for building and deploying a solution package by using Microsoft Visual Studio 2010.

In this article:

  • What is a solution package?

  • Deploying site elements by using solution packages

  • Creating and deploying a custom Web Part solution package by using Visual Studio 2010

What is a solution package?

A solution package is a distribution package that delivers your custom SharePoint Foundation 2010 development work to the Web servers or the application servers in your server farm. Use solutions to package and deploy custom Features, site definitions, templates, layout pages, Web Parts, cascading style sheets, and assemblies.

This article does not discuss the deployment of sandboxed solutions. You can deploy a Microsoft SharePoint Foundation 2010 solution directly onto your SharePoint Foundation farm, or you can deploy the solution into a sandbox. A sandbox is a restricted execution environment that enables programs to access only certain resources, and that keeps problems that occur in the sandbox from affecting the rest of the server environment. For more information, see Sandboxed solutions overview (SharePoint Foundation 2010).

A solution package is a CAB file with a .wsp file name extension and a manifest file. It is recommended that you use Visual Studio 2010 Tools for SharePoint 2010 to develop and package SharePoint solutions. You can also create solution packages manually by using tools such as Makecab.exe and SharePoint Packman.

Components that can be packaged in a solution include:

  • .NET Framework assemblies, typically Web part assemblies and event receiver assemblies.

  • Deployment files such as resource files, pages, or other helper files.

  • Features, which allow you to activate and deactivate code in a Web site and provide functionality that include elements such as custom lists, libraries, fields, and content types.

  • New templates and site definitions.

  • Configurations that must be performed at the Web-server level — for example, deploying customizations to the Web.config files for the registration of Web Parts. You can also modify these configurations with a Feature that is distributed with a Feature.

  • Web content such as Web pages and images that are called by Web pages. If you must deploy Web content in a disconnected environment, you should use a content deployment package.

Deploying site elements by using solution packages

In this section:

  • When to use solution packages

  • Deploying farm solutions

  • Importing a solution package

  • Deploying a solution package

  • About creating a solution package

When to use solution packages

A best practice for deploying customizations is to use solution packages as part of a straightforward, safe, and consistent application lifecycle management process. Solution packages make it simpler to change the Features and functionality of the Web sites after the sites are created.

You can use solution packages to deploy new solutions and upgrade existing solutions across the farm. You can package all your SharePoint Foundation entities as one file, add the file to the solution store, and deploy it to the front-end Web servers in the farm. Use solution packages to synchronize a front-end Web server so that its state is consistent with the state of other Web servers in the farm.

You can use solution packages to deploy authored site element customizations from an integration farm to authoring, pilot, or production farm. In SharePoint Foundation, users can save a customized site as a template. This creates a solution package with a .wsp file name extension that can be deployed on another farm.

You can use solution packages to deploy customizations between these environments:

  • From developer workstations, to an integration farm or a software configuration management system

  • From an integration farm and authoring client workstations, to pilot or production farms

Deploying farm solutions

Farm solutions are deployed either locally or by using a timer service. Both local and timer-based deployments can be triggered either by using command-line instructions or programmatically by using the object model.

Local deployment

In a local deployment, solution files are deployed only to the computer from which the deployment operation was initiated. The solution is not marked as "deployed" in the configuration database until the solution files are deployed to all applicable servers in the server farm. Then solution features are installed, and schema and definition files are committed to the configuration store.

Timer Service deployments

In deployments that use the timer service, the deployment creates a timer job. This timer job is picked up by the timer service on each Web server in the server farm. Initially, manifest and feature manifests are parsed to find assembly and _layouts files, which are copied to the appropriate locations. All other files contained within a feature directory are copied to the feature directory. After solution files are copied to the target computers, a configuration reset is scheduled for all front-end Web servers; the reset then deploys the files and restarts Microsoft Internet Information Services (IIS). Solution features are then registered, and schema and definition files are committed to the configuration store.

For more information about the solution store, deployment, and synchronization, see Deploying a Solution (https://go.microsoft.com/fwlink/p/?LinkId=186995) in the Microsoft SharePoint 2010 Software Development Kit (SDK)

Adding a solution package

Before you can deploy a solution package, you must add it to the solution database of a SharePoint Foundation farm.

Important

You must be a member of the Administrators group on any computer on which you run Windows PowerShell.

To import a solution package by using Windows PowerShell

  1. Verify that you meet the following minimum requirements: See Add-SPShellAdmin..

  2. On the Start menu, click All Programs.

  3. Click Microsoft SharePoint 2010 Products.

  4. Click SharePoint 2010 Management Shell.

  5. At the Windows PowerShell command prompt, type the following command:

    Add-SPSolution -LiteralPath <SolutionPath>

The solution is added to the farm's solution store. To use the solution, follow the procedure in the next section in this article. For more information, see Add-SPSolution.

Deploying a solution package

You can deploy imported solutions by using the Central Administration Web site or by using Windows PowerShell. After a solution has been added to the solution store by using the Windows PowerShell Add-SPSolution cmdlet, it must be deployed to a site before it can be accessed.

Note

You cannot add a solution to the solution store by using the Solution Management page in Central Administration.

The following procedures show how to deploy an imported solution to a site in the farm by using either the Central Administration Web site or Windows PowerShell.

To deploy a solution by using Central Administration

  1. On the Central Administration Home page, click System Settings.

  2. In the Farm Management section, click Manage farm solutions.

  3. On the Solution Management page, click the solution that you want to deploy.

  4. On the Solution Properties page, click Deploy Solution.

  5. On the Deploy Solution page, in the Deploy When section, select one of the following:

    • Now

    • At a specified time. If you select this option, specify a time by using the date and time boxes. We recommend that you select a time when the load on the destination servers is low.

  6. In the Deploy To? section, in the A specific web application list, click either All web applications or select a specific Web application.

  7. Click OK.

To deploy a solution package to a single Web application by using Windows PowerShell

  1. Verify that you meet the following minimum requirements: See Add-SPShellAdmin.

  2. On the Start menu, click All Programs.

  3. Click Microsoft SharePoint 2010 Products.

  4. Click SharePoint 2010 Management Shell.

  5. At the Windows PowerShell command prompt, type the following command:

    Install-SPSolution -Identity <SolutionName> -WebApplication <URLname>

    Where:

    • <SolutionName> is the name of the solution.

    • <URLname> is the URL of the Web application to which you want to deploy the imported solution.

    By default, the solution is immediately deployed. You can also schedule the deployment by using the time parameter. For more information, see Install-SPSolution.

To deploy a solution package to all Web applications by using Windows PowerShell

  1. Verify that you meet the following minimum requirements: See Add-SPShellAdmin.

  2. On the Start menu, click All Programs.

  3. Click Microsoft SharePoint 2010 Products.

  4. Click SharePoint 2010 Management Shell.

  5. At the Windows PowerShell command prompt, type the following command:

    Install-SPSolution -Identity <SolutionName> -AllWebApplications -time <TimeToDeploy> -GACDeployment -CASPolicies

    Where:

    • GACDeployment is the parameter that enables SharePoint Foundation 2010 to deploy the assemblies in the global assembly cache.

    • CASPolicies enables the creation of a custom code access security (CAS) policy file and the activation of it in the Web.config file of the targeted site collection.

    The solution is immediately deployed by default. You can also schedule the deployment by using the time parameter.

About creating a solution package

SharePoint Foundation 2010 does not include a tool for creating solution packages. This section describes ways to create solution packages that contain developed site elements and artifacts.

Visual Studio 2010

You can use Visual Studio 2010 to group related SharePoint elements into a Feature, and then bundle multiple Features, site definitions, assemblies, and other files into a single package (.wsp file) to deploy to servers running SharePoint Foundation 2010. You can use Visual Studio 2010 to debug and test the .wsp file on the server running SharePoint Foundation 2010. You can also customize the deployment steps on the development computer.

Developers can build their SharePoint solutions in Visual Studio 2010 and produce .wsp files by using the automated build process. Source code of the Visual Studio SharePoint project that is used to generate the .wsp file can also be added to the source code control system by using Visual Studio 2010 integration. Visual Studio 2010 can import .wsp files and create projects to further extend them and to create new .wsp files. The primary source of .wsp files that are imported into Visual Studio 2010 is templates saved from sites by using the Save As Template command on SharePoint Foundation 2010 sites. These templates can be used to save all of site customizations to a SharePoint solution.

For more information, see SharePoint Development in Visual Studio (https://go.microsoft.com/fwlink/p/?LinkId=187000).

Makecab

Solution packages can be created manually by using tools such as Makecab.exe. The Makecab.exe tool takes a pointer to a .ddf file, which describes the structure of the CAB file. The format of a .ddf file is similar to that of an .inf file — that is, you declare a standard header and then enumerate, one file per line, the set of files by where they are located on disk and where they should be located in the CAB file.

The Makecab.exe tool is available for download in the Microsoft Cabinet Software Development Kit (https://go.microsoft.com/fwlink/p/?LinkId=107292).

About customizing solution packages

If you need to make any of the following customizations in SharePoint Foundation 2010 solutions, it is recommended that you use Visual Studio 2010 to customize solution packages. You can also make these customizations by manually creating SharePoint solution packages.

  • Deploy .NET Framework assemblies in the private application folder instead of the global assembly cache.

  • Add code access security permissions to the solution that must be applied during the deployment.

  • Deviate from the names used by default for the Feature folders.

  • Localize the solution.

  • Associate Feature event handlers to certain types of SharePoint Foundation 2010 solutions, such as Web Part solutions.

  • Add resources (XML files, pictures, .dll files, and assemblies) to the solution package.

Manually create a solution file

In most SharePoint Foundation 2010 development scenarios, we recommend that you use Visual Studio 2010 Tools for SharePoint 2010 to develop and package SharePoint solutions. In Visual Studio 2010, the deployment process copies the .wsp file to the server running SharePoint Foundation 2010, installs the solution, and then activates the Features.

You can also manually create a solution file. The following are the basic steps of creating a solution file:

  1. Collect all individual solution files in a folder. There are no concrete guidelines about how you should do this, but a best practice is to separate the different types of solution files into their own subfolders.

  2. Create a manifest.xml file that lists the components of the solution.

  3. Create a .ddf file that defines the structure of the solution file. This file contains the list of individual solution files that determine the output .wsp file.

  4. Execute Makecab.exe with the .ddf file as input and the .wsp file as output.

About the solution manifest file

The solution manifest (always called manifest.xml) is stored at the root of a solution file. This file defines the list of Features, site definitions, resource files, Web Part files, and assemblies to process. It does not define the file structure — if files are included in a solution but not listed in the manifest.xml file, they are not processed in any way.

Following is an example of the structure of a manifest.xml file, shown in XML.

<?xml version="1.0" encoding="utf-8" ?>

<Solution xmlns="https://schemas.microsoft.com/sharepoint/"

SolutionId="{79d1a62e-3627-11db-963e-00e08161165f}"

ResetWebServer="TRUE">

    <Assemblies>

        <Assembly DeploymentTarget="GlobalAssemblyCache"

Location="Example.Sharepoint.Webparts\

Example.SharePoint.WebParts.dll">

            <SafeControls>

                <SafeControl Assembly="Example.Sharepoint.Webparts,

Version=1.0.0.0, Culture=Neutral, PublicKeyToken=63cce650e8605f5d"

Namespace="Example.Sharepoint.Webparts" TypeName="*"/>

            </SafeControls>

        </Assembly>

        <Assembly DeploymentTarget="GlobalAssemblyCache"

Location="Example.Sharepoint.Timer/Example.Sharepoint.Timer.dll"/>

    </Assemblies>

    <FeatureManifests>

        <FeatureManifest Location="Example.Sharepoint.Timer\Feature.xml"/>

        <FeatureManifest Location="Example.CustomType\Feature.xml"/>

        <FeatureManifest Location="Example.ExampleLibrary\Feature.xml"/>

        <FeatureManifest Location="Example.Columns\Feature.xml"/>

        <FeatureManifest Location="Example.Workflow.ProcessExample\Feature.xml"/>

        <FeatureManifest Location="Example.Workflow.ProvisionExample\Feature.xml"/>

    </FeatureManifests>

    <SiteDefinitionManifests>

        <SiteDefinitionManifest Location="EXAMPLE">

            <WebTempFile Location="1033\XML\WEBTEMPExample.XML"/>

        </SiteDefinitionManifest>

    </SiteDefinitionManifests>

</Solution>

In addition, you can add a DwpFiles element to specify .webpart or .dwp files, or a ResourceFiles element to specify resource files, site definitions, application resources, and code access security policies.

Optionally, annotate your Feature.xml files by using <ElementFile> tags.

If your solution contains Features, in the <ElementManifests> tag in your Feature.xml file, add <ElementFile Location="..."/> for all the extra files in your feature, such as ASP.NET pages (for example, allitems.aspx) or master pages, and so on.

For more information about solution manifest files that define the constituent parts of a solution, see Solution Schema (https://go.microsoft.com/fwlink/p/?LinkID=183466).

Creating and deploying a custom Web Part solution package by using Visual Studio 2010

For an example walkthrough that shows you how to use Visual Studio 2010 to create, customize, debug, and deploy a SharePoint list definition to track project tasks, see Walkthrough: Deploying a Project Task List Definition (https://go.microsoft.com/fwlink/p/?LinkId=189612) in the MSDN Library.

This walkthrough illustrates the following tasks:

  • Creating a SharePoint list definition project that contains tasks.

  • Adding the list definition to a SharePoint Feature.

  • Adding an event receiver to the list.

  • Creating and customizing a SharePoint package to deploy your Feature.

  • Building and deploying your SharePoint solution.

When you build the sample project in this walkthrough, Visual Studio 2010 automatically deploys the solution to the server running SharePoint Foundation 2010 on your development computer for testing and debugging. You can also create a solution package file that you can add and deploy on another computer. For more information, see How to: Deploy a SharePoint Solution (https://go.microsoft.com/fwlink/p/?LinkID=187004). You can use the Add-SPSolution Windows PowerShell cmdlet to import the solution to another computer.

You can use the Solution Management page in Central Administration to deploy the solution package. Alternatively, you can use the Install-SPSolution Windows PowerShell cmdlet to deploy the solution package.

In the walkthrough, the scope of the project list feature is Web. To activate the Feature, on the Web site, expand the Site Actions menu, and then click Site Settings. Under Site Actions, click Manage site features. On the Features page, next to the Feature name, click Activate.