Share via

How to: Create a SharePoint Command

  • Article

If you want to use the server object model in a SharePoint tools extension, you must create a custom SharePoint command to call the API. You define the SharePoint command in an assembly that can call into the server object model directly.

For more information about the purpose of SharePoint commands, see Calling into the SharePoint Object Models.

To create a SharePoint command

  1. Create a class library project that has the following configuration:

    Note

    You cannot implement a SharePoint command in the same project that defines a SharePoint tools extension, because SharePoint commands target the .NET Framework 3.5 and SharePoint tools extensions target the .NET Framework 4. You must define any SharePoint commands that are used by your extension in a separate project. For more information, see Deploying Extensions for the SharePoint Tools in Visual Studio.

  2. Add references to the following assemblies:

    • Microsoft.VisualStudio.SharePoint.Commands

    • Microsoft.SharePoint

  3. In a class in the project, create a method that defines your SharePoint command. The method must conform to the following guidelines:

    • It can have one or two parameters.

      The first parameter must be a ISharePointCommandContext object. This object provides the Microsoft.SharePoint.SPSite or Microsoft.SharePoint.SPWeb in which the command is executed. It also provides an ISharePointCommandLogger object that can be used to write messages to the Output window or Error List window in Visual Studio.

      The second parameter can be a type of your choice, but this parameter is optional. You can add this parameter to your SharePoint command if you need to pass data from your SharePoint tools extension to the command.

    • It can have a return value, but this is optional.

    • The second parameter and return value must be a type that can be serialized by the Windows Communication Foundation (WCF). For more information, see Types Supported by the Data Contract Serializer and Using the XmlSerializer Class.

    • The method can have any visibility (public, internal, or private), and it can be static or non-static.

  4. Apply the SharePointCommandAttribute to the method. This attribute specifies a unique identifier for the command; this identifier does not have to match the method name.

    You must specify the same unique identifier when you call the command from your SharePoint tools extension. For more information, see How to: Execute a SharePoint Command.

Example

The following code example demonstrates a SharePoint command that has the identifier Contoso.Commands.UpgradeSolution. This command uses APIs in the server object model to upgrade to a deployed solution.

<SharePointCommand("Contoso.Commands.UpgradeSolution")> _
Private Sub UpgradeSolution(ByVal context As ISharePointCommandContext, ByVal fullWspPath As String)
    Dim solution As SPSolution = SPFarm.Local.Solutions(Path.GetFileName(fullWspPath))
    If solution Is Nothing Then
        Throw New InvalidOperationException("The solution has not been deployed.")
    End If
    solution.Upgrade(fullWspPath)
End Sub

[SharePointCommand("Contoso.Commands.UpgradeSolution")]
private void UpgradeSolution(ISharePointCommandContext context, string fullWspPath)
{
    SPSolution solution = SPFarm.Local.Solutions[Path.GetFileName(fullWspPath)];

    if (solution == null)
    {
        throw new InvalidOperationException("The solution has not been deployed.");
    }

    solution.Upgrade(fullWspPath);
}

In addition to the implicit first ISharePointCommandContext parameter, this command also has a custom string parameter that contains the full path of the .wsp file that is being upgraded to the SharePoint site. To see this code in the context of a larger example, see Walkthrough: Creating a Custom Deployment Step for SharePoint Projects.

Compiling the Code

This example requires references to the following assemblies:

  • Microsoft.VisualStudio.SharePoint.Commands

  • Microsoft.SharePoint

Deploying the Command

To deploy the command, include the command assembly in the same Visual Studio extension (VSIX) package with the extension assembly that uses the command. You must also add an entry for the command assembly in the extension.vsixmanifest file. For more information, see Deploying Extensions for the SharePoint Tools in Visual Studio.

See Also

Tasks

How to: Execute a SharePoint Command

Walkthrough: Extending Server Explorer to Display Web Parts

Concepts

Calling into the SharePoint Object Models