SharePoint 2010 Code Deployment, Part Three
Part One of this series gave a general overview of SharePoint 2010 code deployment using Visual Studio 2010. Part Two described the creation and use of SharePoint Commands. In this installment we will explore SharePoint Deployment Steps and their relationship with both SharePoint Commands and SharePoint Deployment Configurations.
A Deployment Step defines the order in which custom commands are called and which commands are associated with the required CanExecute and Execute methods. As with SharePoint Commands, a Deployment Step may be referenced by numerous Deployment Configurations and are surfaced in the SharePoint configuration page of the project properties. They can be explicitly defined as part of an immutable configuration or mixed and matched within design-time configurations specified by the developer.
Continuing the previously established scenario, in which we created custom SharePoint Commands to remove orphaned List Instance objects from a site after updating the associated List Template, the next step in the process is to create a SharePoint Deployment Step which calls the custom commands. For all intents and purposes, a custom Deployment Command is simply a pointer which allows users to select a specific piece of functionality in the configuration settings and bundle one or more sets of functionality into a packaged Deployment Configuration. In our example, the new Deployment Step will call our DeploymentCommands.SPCommand.ListExists and DeploymentCommands.SPCommand.DeleteLists custom commands when the developer adds it to a configuration and deploys the solution within Visual Studio 2010.
Setting Up the Project
As mentioned previously, SharePoint Commands must be compiled using the .NET 3.5 Framework since they reference the core SharePoint 2010 assemblies; however, Deployment Steps and Deployment Configurations both require .NET Framework 4.0. In order to account for the different platform requirements, we must add a new project to the solution which will contain classes for both steps and the configuration. The final VSIX package, which will be created in a third project, will bundle both sets of assemblies together for activation within Visual Studio.
Begin by opening the Contoso.CustomDeployment solution and adding a class project with a namespace of Contoso.DeploymentSteps (the project should default to the .NET 4.0 Framework):
Writing the Code
The Deployment Step performs two functions: 1) Calling the DeploymentCommands.SPCommand.ListExists method to determine if any lists of the specified type in the target site exist, and 2) If any do exist, executing the code contained in the DeploymentCommands.SPCommand.DeleteLists method to remove them before re-deploying the solution. Deployment steps must include an ExportAttribute of Type IDeploymentStep and reference the Microsoft.VisualStudio.SharePoint.Deployment and System.ComponentModel.Composition namespaces. Furthermore, each Deployment Step has a collection of IDeploymentStepInfo parameters which describe the step, specify its display name and provide a message to be displayed in the Visual Studio IDE status bar while executing.
Attributes and Naming Conventions
As with SharePoint Commands, Deployment Steps are referenced by their literal string name which is defined as part of an attribute decoration on each class. There are no explicit rules pertaining to naming conventions; however, as the use of custom Deployment Steps grows within a development team it may be necessary to enforce some kind of explicit notation. For this example we will use a dotted hierarchy which includes the namespace but this is simply an arbitrary choice and has no bearing on the overall functionality.
Begin by creating the RemoveListInstances class and include the necessary attributes. Bear in mind that the name applied in the DeploymentStep attribute will be used later in the Deployment Configuration to reference the step:
Before moving on to the actual methods, it will be necessary to define a variable for the Feature ID of the List Template Feature created in the Contoso.CustomLists project (refer to the code samples in Part Two of this series). The GUID for the Feature can be located by opening the Contoso.CustomLists.Orders.Feature and clicking on the "Manifest" option in the Feature Explorer – this exposes the underlying XML from which the ID may be copied. In addition, we will also define the IDeploymentStepInfo parameters:
class RemoveListInstances : IDeploymentStep
public void Initialize(IDeploymentStepInfo stepInfo)
The first method to be defined invokes the DeploymentCommands.SPCommand.ListExists method within the custom Deployment Command class by its attributed name and passes in the value stored in the definitionFeatureId variable. Execution of the command is achieved by utilizing the ExecuteCommand of the IDeploymentContext and ISharePointProject.SharePointConnection interfaces:
public bool CanExecute(IDeploymentContext context)
b = context.Project.SharePointConnection.ExecuteCommand<string, bool>("DeploymentCommands.SPCommand.ListExists", definitionFeatureId);
The above code returns a Boolean value indicating whether or not any List Instances associated to the specified Feature ID exist within the target site. If they do, the Execute method can be called; if not, a message is logged to the IDE as a Warning and the step terminates.
The final Execute method is quite simple: it logs a status message indicating that it is running and calls the DeploymentCommands.SPCommand.DeleteLists method of the Deployment Command class, passing in the definitionFeatureId value as a parameter:
public void Execute(IDeploymentContext context)
Building and Packaging
As with the Deployment Command project, at this stage there is nothing more to be done other than to build the project and insure it compiles correctly. Later, in the VSIX portion, we will discuss how to include the resultant assemblies in the final deployment package.
While the custom command methods were easily testable, the same cannot be said for the Deployment Steps or Deployment Configuration. This is primarily due to the fact that the steps are designed to run as part of the Visual Studio host process and rely upon context information only available at runtime. It may be possible to mock or Mole the containing processes to derive state and context information but the code required to do so is well beyond the scope of this tutorial. Refer to the TypeMock forums and PEX/MOLES documentation for more information on this topic.
SharePoint Deployment Steps build upon SharePoint Commands by providing a method for referencing custom commands and a functional element which the developer can select as part of a custom deployment solution. They can be used individually or packaged together in a custom Deployment Configuration. In Part Four of this series we will discuss the creation of a custom configuration that utilizes the step defined in our example code. In Part Five, the final article in this series, we will investigate how the commands, steps and configurations are activated within Visual Studio 2010 and their effects on the deployment of our List Template solution.