Deploying Extensions for the SharePoint Tools in Visual Studio

To deploy a SharePoint tools extension, create a Visual Studio extension (VSIX) package that contains the extension assembly and any other files that you want to distribute with the extension. A VSIX package is a compressed file that follows the Open Packaging Conventions (OPC) standard. VSIX packages have the .vsix extension.

After you create a VSIX package, other users can run the .vsix file to install your extension. When a user installs your extension, all of the files are installed to the %UserProfile%\AppData\Local\Microsoft\VisualStudio\10.0\Extensions folder. To deploy the extension, you can upload the VSIX package to the Visual Studio Gallery Web site, or you can distribute the package to your customers by some other means, such as hosting the package on a network share or some other Web site.

For more information about creating VSIX packages and deploying them to the Visual Studio Gallery, see VSIX Deployment.

You can create a VSIX package by using the VSIX Project template in Visual Studio, or you can create a VSIX package manually.

Using VSIX Projects to Create VSIX Packages

You can use the VSIX Project template provided by the Visual Studio 2010 SDK to create VSIX packages for SharePoint tools extensions. Using a VSIX project provides several benefits over creating a VSIX package manually:

• Visual Studio automatically generates the VSIX package when you build the project. Tasks such as adding the deployment files to the package and creating the [Content_Types].xml file for the package are done for you.

• You can configure the VSIX project to include the build output of your extension project and other files, such as project templates and item templates, in the VSIX package.

For more information about using a VSIX project, see VSIX Project Template.

Organizing Your Projects

By default, VSIX projects only generate VSIX packages, not assemblies. Therefore, you typically do not implement a SharePoint tools extension in a VSIX project. You generally work with at least two projects:

• A VSIX project.

• A class library project that implements your extension.

You might also work with additional projects for certain types of extensions:

• A class library project that implements any SharePoint commands that are used by your extension. For a walkthrough that demonstrates this scenario, see Walkthrough: Extending Server Explorer to Display Web Parts.

• An Item Template or Project Template project that creates an item template or project template, if your extension defines a new type of SharePoint project item. For a walkthrough that demonstrates this scenario, see Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 1.

• A class library project that implements a custom wizard for an item template or project template, if your extension includes a template. For a walkthrough that demonstrates this scenario, see Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 2.

If you include all of the projects in the same Visual Studio solution, you can modify the source.extension.vsixmanifest file in the VSIX project to include the build output of the class library projects.

Editing the VSIX Manifest

You must edit the source.extension.vsixmanifest file in the VSIX project to include entries for all the items that you want to include in your extension. When you edit the source.extension.vsixmanifest file, Visual Studio opens the file in a designer that provides a UI for editing the XML in the file. For more information, see VSIX Manifest Designer.

You must add entries to the source.extension.vsixmanifest file for the following items:

• The extension assembly.

• The assembly that implements any SharePoint commands that are used by your extension.

• Any project templates or item templates that are associated with your extension.

• A custom wizard for a template that is associated with your extension.

The following procedures describe how to add entries to the .vsixmanifest file for each of these items.

To include the extension assembly

1. In the VSIX project, double-click the source.extension.vsixmanifest file to open the file in the designer.

2. In the Content section of the editor, click the Add Content button.

3. In the Add Content dialog box, in the Select a content type list box, select MEF Component.

4. Under Select a source, do one of the following steps:

   • If the extension assembly is built from a project that is in the same solution as the VSIX project, click the Project radio button and select the name of the project in the list box next to it.

   • If the extension assembly is included as a file in your project, click the File in Project radio button and select the assembly in the list box next to it.

   • If the extension assembly is located in some other location, click the File radio button, and then use the Choose File dialog box to locate and select the assembly.

5. Click OK.

To include a SharePoint command assembly

1. In the VSIX project, double-click the source.extension.vsixmanifest file to open the file in the designer.

2. In the Content section of the editor, click the Add Content button.

3. In the Add Content dialog box, in the Select a content type list box, select Custom Extension Type.

4. In the Type text box, type SharePoint.Commands.v4. This value is required for all assemblies that contain SharePoint commands.

5. Under Select a source, do one of the following steps:

   • If the command assembly is built from a project that is in the same solution as the VSIX project, click the Project radio button and select the name of the command project in the list box next to it.

   • If the command assembly is included as a file in your project, click the File in Project radio button and select the assembly in the list box next to it.

   • If the command assembly is located in some other location, click the File radio button, and then use the Choose File dialog box to locate and select the assembly.

6. Click OK.

To include a template that you create by using a Project Template or Item Template project from the Visual Studio SDK

1. In the VSIX project, double-click the source.extension.vsixmanifest file to open the file in the designer.

2. In the Content section of the editor, click the Add Content button.

3. In the Add Content dialog box, in the Select a content type list box, select Project Template or Item Template.

4. Under Select a source, click the Project radio button and select the name of the project in the list box next to it.

5. Click OK.

6. In Solution Explorer, right-click the node for your Project Template or Item Template project and click Unload Project.

7. Right-click the project node again and click Edit YourTemplateProjectName**.csproj** or Edit YourTemplateProjectName**.vbproj**.

8. Locate the following VSTemplate element in the project file.

   <VSTemplate Include="YourTemplateName.vstemplate">
   

9. Replace this VSTemplate element with the following XML.

   <VSTemplate Include="YourTemplateName.vstemplate">
     <OutputSubPath>SharePoint\SharePoint14</OutputSubPath>
   </VSTemplate>
   

   The OutputSubPath element specifies additional folders in the path under which the project template is created when you build the project. The folders specified here ensure that the item template will be available only when customers click the 2010 node under the SharePoint node in the Add New Project dialog box.

10. Save and close the file.

11. In Solution Explorer, right-click the Project Template or Item Template project and click Reload Project.

To include a template that you create manually

1. In the VSIX project, add a new folder to the project to contain the template.

2. Under this new folder, create the following subfolders, and then add the template (.zip) file to the Locale ID folder.

        YourTemplateFolder

             SharePoint

                  SharePoint14

                       Locale ID

                            YourTemplateName.zip

   For example, if you have an item template named ContosoCustomAction.zip that supports the English (United States) locale, the full path might be ItemTemplates\SharePoint\SharePoint14\1033\ContosoCustomAction.zip.

3. In Solution Explorer, click the template file (YourTemplateName.zip).

4. In the Properties window, set the Build Action property to Content.

5. Double-click the source.extension.vsixmanifest file to open the file in the designer.

6. In the Content section of the editor, click the Add Content button.

7. In the Add Content dialog box, in the Select a content type list box, select Item Template or Project Template.

8. Under Select a source, click the File in Project radio button, and select the full path of the template in the list box next to it. For example, ItemTemplates\SharePoint\SharePoint14\1033\ContosoCustomAction.zip.

9. Click OK.

To include a wizard for a project template or item template

1. In the VSIX project, double-click the source.extension.vsixmanifest file to open the file in the designer.

2. In the Content section of the editor, click the Add Content button.

3. In the Add Content dialog box, in the Select a content type list box, select Template Wizard.

4. Under Select a source, perform one of the following steps:

   • If the wizard assembly is built from a project that is in the same solution as the VSIX project, click the Project radio button and select the name of the project in the list box next to it.

   • If the wizard assembly is included as a file in your project, click the File in Project radio button and select the assembly in the list box next to it.

   • If the wizard assembly is located in some other location, click the File radio button, and then use the Choose File dialog box to locate and select the assembly.

5. Click OK.

Related Walkthroughs

The following table lists walkthroughs that demonstrate how to use a VSIX project to deploy different types of SharePoint tools extensions.

Creating VSIX Packages Manually

If you want to manually create the VSIX package for your SharePoint tools extension, perform the following steps:

1. Create the extension.vsixmanifest file, the [Content_Types].xml, and the VSIX package file (.vsix file). For more information, see Anatomy of a VSIX Package and How to: Manually Package an Extension (VSIX Deployment).

2. Add your extension assembly to the VSIX package. If your extension includes a SharePoint command, also add the assembly that implements the SharePoint command to the VSIX package.

3. Modify the extension.vsixmanifest file:

   • Add a MefComponent element under the Content element. Set the element value to the relative path of the assembly that implements your extension in the VSIX package. For more information, see MEFComponent Element (VSX Schema).

   • If your extension includes a SharePoint command that calls into the SharePoint server object model, add a new CustomExtension element under the Content element. Set the element value to the relative path of the assembly that implements the SharePoint command in the VSIX package, and set the Type attribute to the value SharePoint.Commands.v4. For more information, see CustomExtension Element (VSX Schema).

   • If your extension includes a project template or item template, add a new ProjectTemplate or ItemTemplate element under the Content element. Set the element value to the relative path of the folder that contains the template in the VSIX package. For more information, see ProjectTemplate Element (VSX Schema) and ItemTemplate Element (VSX Schema).

   • If your extension includes a custom wizard for a project template or item template, add a new Assembly element under the Content element. Set the element value to the relative path of the assembly in the VSIX package, and set the AssemblyName attribute to the full assembly name (including version, culture, and public key token). For more information, see Assembly Element (VSX Schema).

Example

The following example shows the contents of an extension.vsixmanifest file for a SharePoint tools extension. The extension is implemented in an assembly named Contoso.ProjectExtension.dll. The extension includes a SharePoint command assembly named Contoso.ExtensionCommands.dll and an item template under a folder named ItemTemplates in the VSIX package. This example assumes that both of the assemblies are in the same folder as the extension.vsixmanifest file in the VSIX package.

<?xml version="1.0" encoding="utf-8"?>
<Vsix xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      Version="1.0.0" xmlns="https://schemas.microsoft.com/developer/vsx-schema/2010">
  <Identifier Id="CustomActionProjectItem.Contoso.b1d75407-01bd-459d-9d04-d12e9113af49">
    <Name>Custom Action Project Item</Name>
    <Author>Contoso</Author>
    <Version>1.0</Version>
    <Description xml:space="preserve">A SharePoint project item that represents a custom action.</Description>
    <Locale>1033</Locale>
    <SupportedProducts>
      <VisualStudio Version="10.0">
        <Edition>Pro</Edition>
      </VisualStudio>
    </SupportedProducts>
    <SupportedFrameworkRuntimeEdition MinVersion="4.0" MaxVersion="4.0" />
  </Identifier>
  <References />
  <Content>
    <MefComponent>Contoso.ProjectExtension.dll</MefComponent>
    <CustomExtension Type="SharePoint.Commands.v4">Contoso.ExtensionCommands.dll</CustomExtension>
    <ItemTemplate>ItemTemplates</ItemTemplate>
  </Content>
</Vsix>

See Also

Concepts

Extending the SharePoint Project System

Calling into the SharePoint Object Models

Debugging Extensions for the SharePoint Tools in Visual Studio

Other Resources

Extending the SharePoint Connections Node in Server Explorer