How to: Execute a SharePoint Command

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. After you define the command and deploy it with your SharePoint tools extension, your extension can execute the command to call into the SharePoint server object model. To execute the command, use one of the ExecuteCommand methods of an ISharePointConnection object.

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

To execute a SharePoint command

1. In your SharePoint tools extension, get an ISharePointConnection object. The way you get an ISharePointConnection object depends on the type of extension you are creating:

   • In an extension of the SharePoint project system, use the ISharePointProject.SharePointConnection property.

     For more information about project system extensions, see Extending the SharePoint Project System.

   • In an extension of the SharePoint Connections node in Server Explorer, use the IExplorerNodeContext.SharePointConnection property. To get an IExplorerNodeContext object, use the IExplorerNode.Context property.

     For more information about Server Explorer extensions, see Extending the SharePoint Connections Node in Server Explorer.

   • In code that is not part of an extension of the SharePoint tools, such as a project template wizard, use the ISharePointProjectService.SharePointConnection property.

     For more information about retrieving the project service, see Using the SharePoint Project Service.

2. Call one of the ExecuteCommand methods of the ISharePointConnection object. Pass the name of the command you want to execute to the first argument of the ExecuteCommand method. If your command has a custom parameter, pass that parameter to the second argument of the ExecuteCommand method.

   There is a different ExecuteCommand overload for each supported command signature. The following table lists the supported signatures and which overload to use for each signature.

   Command signature	ExecuteCommand overload to use
   The command has only the default ISharePointCommandContext parameter and no return value.	ExecuteCommand(String)
   The command has only the default ISharePointCommandContext parameter and a return value.	ExecuteCommand``1(String)
   The command has two parameters (the default ISharePointCommandContext parameter and a custom parameter) and no return value.	ExecuteCommand``1(String, UMP)
   The command has two parameters and a return value.	ExecuteCommand``2(String, UMP)

Example

The following code example demonstrates how to use the ExecuteCommand``1(String, UMP) overload to call the Contoso.Commands.UpgradeSolution command that is described in How to: Create a SharePoint Command.

Private Sub Execute(ByVal context As IDeploymentContext) _
    Implements IDeploymentStep.Execute
    context.Logger.WriteLine("Upgrading solution: " & solutionName, LogCategory.Status)
    context.Project.SharePointConnection.ExecuteCommand("Contoso.Commands.UpgradeSolution", _
        solutionFullPath)
End Sub

public void Execute(IDeploymentContext context)
{
    context.Logger.WriteLine("Upgrading solution: " + solutionName, LogCategory.Status);
    context.Project.SharePointConnection.ExecuteCommand("Contoso.Commands.UpgradeSolution",
        solutionFullPath);
}

The Execute method shown in this example is an implementation of the Execute method of the IDeploymentStep interface in a custom deployment step. To see this code in the context of a larger example, see Walkthrough: Creating a Custom Deployment Step for SharePoint Projects.

Note the following details about the call to the ExecuteCommand``1(String, UMP) method:

• The first parameter identifies the command that you want to call. This string matches the value that you pass to the SharePointCommandAttribute on the command definition.

• The second parameter is the value that you want to pass to the custom second parameter of the command. In this case, it is the full path of the .wsp file that is being upgraded to the SharePoint site.

• The code does not pass the implicit ISharePointCommandContext parameter to the command. This parameter is passed into the command automatically when you call the command from an extension of the SharePoint project system or an extension of the SharePoint Connections node in Server Explorer. In other types of solutions, such as in a project template wizard that implements the Microsoft.VisualStudio.TemplateWizard.IWizard interface, this parameter is null.

Compiling the Code

This example requires a reference to the Microsoft.VisualStudio.SharePoint assembly.

See Also

Tasks

Walkthrough: Extending Server Explorer to Display Web Parts

Concepts

Calling into the SharePoint Object Models

How to: Create a SharePoint Command