Walkthrough: Creating a Custom Deployment Step for SharePoint Projects

Article
04/28/2015

When you deploy a SharePoint project, Visual Studio executes a series of deployment steps in a specific order. Visual Studio includes many built-in deployment steps, but you can also create your own.

In this walkthrough, you will create a custom deployment step to upgrade solutions on a server that's running SharePoint. Visual Studio includes built-in deployment steps for many tasks, such retracting or adding solutions, but it doesn't include a deployment step for upgrading solutions. By default, when you deploy a SharePoint solution, Visual Studio first retracts the solution (if it's already deployed) and then redeploys the entire solution. For more information about the built-in deployment steps, see Deploying, Publishing, and Upgrading SharePoint Solution Packages.

This walkthrough demonstrates the following tasks:

Creating a Visual Studio extension that performs two main tasks:
- The extension defines a custom deployment step to upgrade SharePoint solutions.
- The extension creates a project extension that defines a new deployment configuration, which is a set of deployment steps that are executed for a given project. The new deployment configuration includes the custom deployment step and several built-in deployment steps.
Creating two custom SharePoint commands that the extension assembly calls. SharePoint commands are methods that can be called by extension assemblies to use APIs in the server object model for SharePoint. For more information, see Calling into the SharePoint Object Models.
Building a Visual Studio Extension (VSIX) package to deploy both of the assemblies.
Testing the new deployment step.

Prerequisites

You need the following components on the development computer to complete this walkthrough:

Supported editions of Windows, SharePoint, and Visual Studio. For more information, see Requirements for Developing SharePoint Solutions.
The Visual Studio SDK. This walkthrough uses the VSIX Project template in the SDK to create a VSIX package to deploy the extension. For more information, see Extending the SharePoint Tools in Visual Studio.

Knowledge of the following concepts is helpful, but not required, to complete the walkthrough:

Using the server object model for SharePoint. For more information, see Using the SharePoint Foundation Server-Side Object Model.
SharePoint solutions. For more information, see Solutions Overview.
Upgrading SharePoint solutions. For more information, see Upgrading a Solution.

Creating the Projects

To complete this walkthrough, you must create three projects:

A VSIX project to create the VSIX package to deploy the extension.
A class library project that implements the extension. This project must target the .NET Framework 4.5.
A class library project that defines the custom SharePoint commands. This project must target the .NET Framework 3.5.

Start the walkthrough by creating the projects.

To create the VSIX project

Start Visual Studio.
On the menu bar, choose File, New, Project.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then choose the Extensibility node.

Note

The Extensibility node is available only if you install the Visual Studio SDK. For more information, see the prerequisites section earlier in this topic.
At the top of the dialog box, choose .NET Framework 4.5 in the list of versions of the .NET Framework.
Choose the VSIX Project template, name the project UpgradeDeploymentStep, and then choose the OK button.

Visual Studio adds the UpgradeDeploymentStep project to Solution Explorer.

To create the extension project

In Solution Explorer, open the shortcut menu for the UpgradeDeploymentStep solution node, choose Add, and then choose New Project.

Note

In Visual Basic projects, the solution node appears in Solution Explorer only when the Always show solution check box is selected in the General, Projects and Solutions, Options Dialog Box.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then choose the Windows node.
At the top of the dialog box, choose .NET Framework 4.5 in the list of versions of the .NET Framework.
Choose the Class Library project template, name the project DeploymentStepExtension, and then choose the OK button.

Visual Studio adds the DeploymentStepExtension project to the solution and opens the default Class1 code file.
Delete the Class1 code file from the project.

To create the SharePoint command project

In Solution Explorer, open the shortcut menu for the UpgradeDeploymentStep solution node, choose Add, and then choose New Project.

Note

In Visual Basic projects, the solution node only appears in Solution Explorer when the Always show solution check box is selected in the General, Projects and Solutions, Options Dialog Box.
In the New Project dialog box, expand Visual C# or Visual Basic, and then choose the Windows node.
At the top of the dialog box, choose .NET Framework 3.5 in the list of versions of the .NET Framework.
Choose the Class Library project template, name the project SharePointCommands, and then choose the OK button.

Visual Studio adds the SharePointCommands project to the solution and opens the default Class1 code file.
Delete the Class1 code file from the project.

Configuring the Projects

Before you write code to create the custom deployment step, you must add code files and assembly references, and you must configure the projects.

To configure the DeploymentStepExtension project

In the DeploymentStepExtension project, add two code files that have the following names:
- UpgradeStep
- DeploymentConfigurationExtension
Open the shortcut menu on the DeploymentStepExtension project, and then choose Add Reference.
On the Framework tab, select the check box for the System.ComponentModel.Composition assembly.
On the Extensions tab, select the check box for the Microsoft.VisualStudio.SharePoint assembly, and then choose the OK button.

To configure the SharePointCommands project

In the SharePointCommands project, add a code file that's named Commands.
In Solution Explorer, open the shortcut menu on the SharePointCommands project node, and then choose Add Reference.
On the Extensions tab, select the check boxes for the following assemblies, and then click choose the OK button
- Microsoft.SharePoint
- Microsoft.VisualStudio.SharePoint.Commands

Defining the Custom Deployment Step

Create a class that defines the upgrade deployment step. To define the deployment step, the class implements the IDeploymentStep interface. Implement this interface whenever you want to define a custom deployment step.

To define the custom deployment step

In the DeploymentStepExtension project, open the UpgradeStep code file, and then paste the following code into it.

Note

After you add this code, the project will have some compile errors, but they'll go away when you add code in later steps.

Imports System
Imports Microsoft.VisualStudio.SharePoint
Imports Microsoft.VisualStudio.SharePoint.Deployment
Imports System.ComponentModel.Composition

Namespace Contoso.DeploymentSteps.Upgrade

    ' Export attribute: Enables Visual Studio to discover and load this deployment step. 
    ' DeploymentStep attribute: Specifies the ID for this new deployment step. 
    ' UpgradeStep class: Defines a new deployment step that can be used to upgrade a solution  
    '     on a SharePoint site.
    <Export(GetType(IDeploymentStep))> _
    <DeploymentStep("Contoso.DeploymentSteps.UpgradeSolution")> _
    Friend Class UpgradeStep
        Implements IDeploymentStep

        Private solutionName As String 
        Private solutionFullPath As String 

        Private Sub Initialize(ByVal stepInfo As IDeploymentStepInfo) _
            Implements IDeploymentStep.Initialize
            stepInfo.Name = "Upgrade solution"
            stepInfo.StatusBarMessage = "Upgrading solution..."
            stepInfo.Description = "Upgrades the solution on the local machine." 
        End Sub 

        ' Specifies whether the solution can be upgraded. 
        Private Function CanExecute(ByVal context As IDeploymentContext) As Boolean _
            Implements IDeploymentStep.CanExecute

            ' SharePoint returns all the installed solutions names in lower case.
            solutionName = (context.Project.Package.Model.Name & ".wsp").ToLower()
            solutionFullPath = context.Project.Package.OutputPath
            Dim solutionExists As Boolean = _
                context.Project.SharePointConnection.ExecuteCommand(Of String, Boolean)(
                "Contoso.Commands.IsSolutionDeployed", solutionName)

            ' Throw exceptions in error cases because deployment cannot proceed. 
            If context.Project.IsSandboxedSolution = True Then 
                Dim sandboxMessage As String = "Cannot upgrade the solution. Upgrade deployment " & _
                    "configuration does not support Sandboxed solutions."
                context.Logger.WriteLine(sandboxMessage, LogCategory.Error)
                Throw New InvalidOperationException()
            ElseIf solutionExists = False Then 
                Dim notDeployedMessage As String = String.Format("Cannot upgrade the solution. The IsSolutionDeployed " & _
                    "command cannot find the following solution on the SharePoint site: {0}.", solutionName)
                context.Logger.WriteLine(notDeployedMessage, LogCategory.Error)
                Throw New InvalidOperationException(notDeployedMessage)
            End If 

            ' Execute step and continue with deployment. 
            Return True 
        End Function 

        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 

    End Class 
End Namespace

using System;
using Microsoft.VisualStudio.SharePoint;
using Microsoft.VisualStudio.SharePoint.Deployment;
using System.ComponentModel.Composition;

namespace Contoso.DeploymentSteps.Upgrade
{
    // Enables Visual Studio to discover and load this deployment step.
    [Export(typeof(IDeploymentStep))]

    // Specifies the ID for this new deployment step.
    [DeploymentStep("Contoso.DeploymentSteps.UpgradeSolution")]

    // Defines a new deployment step that can be used to upgrade a solution on a SharePoint site. 
    internal class UpgradeStep : IDeploymentStep
    {
        private string solutionName;
        private string solutionFullPath;

        // Implements IDeploymentStep.Initialize. 
        public void Initialize(IDeploymentStepInfo stepInfo)
        {
            stepInfo.Name = "Upgrade solution";
            stepInfo.StatusBarMessage = "Upgrading solution...";
            stepInfo.Description = "Upgrades the solution on the local machine.";
        }

        // Implements IDeploymentStep.CanExecute. Specifies whether the solution can be upgraded. 
        public bool CanExecute(IDeploymentContext context)
        {
            // SharePoint returns all the installed solutions names in lower case.
            solutionName = (context.Project.Package.Model.Name + ".wsp").ToLower();
            solutionFullPath = context.Project.Package.OutputPath;
            bool solutionExists = context.Project.SharePointConnection.ExecuteCommand<string, bool>(
                "Contoso.Commands.IsSolutionDeployed", solutionName);

            // Throw exceptions in error cases because deployment cannot proceed. 
            if (context.Project.IsSandboxedSolution)
            {
                string sandboxMessage = "Cannot upgrade the solution. The upgrade deployment configuration " +
                    "does not support Sandboxed solutions.";
                context.Logger.WriteLine(sandboxMessage, LogCategory.Error);
                throw new InvalidOperationException(sandboxMessage);
            }
            else if (!solutionExists)
            {
                string notDeployedMessage = string.Format("Cannot upgrade the solution. The IsSolutionDeployed " +
                    "command cannot find the following solution: {0}.", solutionName);
                context.Logger.WriteLine(notDeployedMessage, LogCategory.Error);
                throw new InvalidOperationException(notDeployedMessage);
            }

            // Execute step and continue with deployment. 
            return true;
        }

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

Creating a Deployment Configuration that Includes the Custom Deployment Step

Create a project extension for the new deployment configuration, which includes several built-in deployment steps and the new upgrade deployment step. By creating this extension, you help SharePoint developers to use the upgrade deployment step in SharePoint projects.

To create the deployment configuration, the class implements the ISharePointProjectExtension interface. Implement this interface whenever you want to create a SharePoint project extension.

To create the deployment configuration

In the DeploymentStepExtension project, open the DeploymentConfigurationExtension code file, and then paste the following code into it.

Imports Microsoft.VisualStudio.SharePoint
Imports Microsoft.VisualStudio.SharePoint.Deployment
Imports System.ComponentModel.Composition

Namespace Contoso.DeploymentSteps.Upgrade

    ' Export attribute: Enables Visual Studio to discover and load this project-level extension. 
    ' DeploymentConfigurationExtension class: Defines a project-level extension. The extension creates  
    '     a new deployment configuration that includes the upgrade deployment step.
    <Export(GetType(ISharePointProjectExtension))> _
    Friend Class DeploymentConfigurationExtension
        Implements ISharePointProjectExtension

        Private Sub Initialize(ByVal projectService As ISharePointProjectService) _
            Implements ISharePointProjectExtension.Initialize
            AddHandler projectService.ProjectInitialized, AddressOf ProjectInitialized
        End Sub 

        ' Creates the new deployment configuration. 
        Private Sub ProjectInitialized(ByVal Sender As Object, ByVal e As SharePointProjectEventArgs)
            Dim deploymentSteps As String() = New String() _
            {
                DeploymentStepIds.PreDeploymentCommand, _
                DeploymentStepIds.RecycleApplicationPool, _
                "Contoso.DeploymentSteps.UpgradeSolution", _
                DeploymentStepIds.PostDeploymentCommand _
            }
            Dim retractionSteps As String() = New String() _
            {
                DeploymentStepIds.RecycleApplicationPool, _
                DeploymentStepIds.RetractSolution
            }
            Dim configuration As IDeploymentConfiguration = e.Project.DeploymentConfigurations.Add( _
                "Upgrade", deploymentSteps, retractionSteps)
            configuration.Description = "This is the upgrade deployment configuration" 
        End Sub 

    End Class 
End Namespace

using Microsoft.VisualStudio.SharePoint;
using Microsoft.VisualStudio.SharePoint.Deployment;
using System.ComponentModel.Composition;

namespace Contoso.DeploymentSteps.Upgrade
{
    // Enables Visual Studio to discover and load this project-level extension.
    [Export(typeof(ISharePointProjectExtension))]

    // Defines a project-level extension. The extension creates a new deployment configuration that includes the 
    // upgrade deployment step. 
    internal class DeploymentConfigurationExtension : ISharePointProjectExtension
    {
        // Implements ISharePointProjectExtension.Initialize. 
        public void Initialize(ISharePointProjectService projectService)
        {
            projectService.ProjectInitialized += ProjectInitialized;
        }

        // Creates the new deployment configuration. 
        private void ProjectInitialized(object sender, SharePointProjectEventArgs e)
        {
            string[] deploymentSteps = new string[] 
            {
                DeploymentStepIds.PreDeploymentCommand,
                DeploymentStepIds.RecycleApplicationPool,
                "Contoso.DeploymentSteps.UpgradeSolution",
                DeploymentStepIds.PostDeploymentCommand 
            };

            string[] retractionSteps = new string[] 
            {
                DeploymentStepIds.RecycleApplicationPool,
                DeploymentStepIds.RetractSolution                
            };

            IDeploymentConfiguration configuration = e.Project.DeploymentConfigurations.Add(
                "Upgrade", deploymentSteps, retractionSteps);
            configuration.Description = "This is the upgrade deployment configuration";
        }
    }
}

Creating the Custom SharePoint Commands

Create two custom commands that call into the server object model for SharePoint. One command determines whether a solution is already deployed; the other command upgrades a solution.

To define the SharePoint commands

In the SharePointCommands project, open the Commands code file, and then paste the following code into it.

Imports System
Imports System.IO
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Administration
Imports Microsoft.VisualStudio.SharePoint.Commands

Namespace Contoso.DeploymentSteps.Upgrade

    Friend Class Commands

        ' Determines whether the specified solution has been deployed to the local SharePoint server.
        <SharePointCommand("Contoso.Commands.IsSolutionDeployed")> _
        Private Function IsSolutionDeployed(ByVal context As ISharePointCommandContext, ByVal solutionName As String) As Boolean 
            Dim solution As SPSolution = SPFarm.Local.Solutions(solutionName)
            Return solution IsNot Nothing 
        End Function 

        ' Upgrades the specified solution to the local SharePoint server.
        <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 

    End Class 
End Namespace

using System;
using System.IO;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
using Microsoft.VisualStudio.SharePoint.Commands;

namespace Contoso.DeploymentSteps.Upgrade
{
    internal class Commands
    {
        // Determines whether the specified solution has been deployed to the local SharePoint server.
        [SharePointCommand("Contoso.Commands.IsSolutionDeployed")]
        private bool IsSolutionDeployed(ISharePointCommandContext context, string solutionName)
        {
            SPSolution solution = SPFarm.Local.Solutions[solutionName];
            return solution != null;
        }

        // Upgrades the specified solution to the local SharePoint server.
        [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);
        }
    }
}

Checkpoint

At this point in the walkthrough, all the code for the custom deployment step and the SharePoint commands are now in the projects. Build them to make sure that they compile without errors.

To build the projects

In Solution Explorer, open the shortcut menu for the DeploymentStepExtension project, and then choose Build.
Open the shortcut menu for the SharePointCommands project, and then choose Build.

Creating a VSIX Package to Deploy the Extension

To deploy the extension, use the VSIX project in your solution to create a VSIX package. First, configure the VSIX package by modifying the source.extension.vsixmanifest file in the VSIX project. Then create the VSIX package by building the solution.

To configure and create the VSIX package

In Solution Explorer, under the UpgradeDeploymentStep project, open the shortcut menu for the source.extension.vsixmanifest file, and then choose Open.

Visual Studio opens the file in the manifest editor. The source.extension.vsixmanifest file is the basis for the extension.vsixmanifest file that all VSIX packages require. For more information about this file, see VSX Schema for Extensions.
In the Product Name box, enter Upgrade Deployment Step for SharePoint Projects.
In the Author box, enter Contoso.
In the Description box, enter Provides a custom upgrade deployment step that can be used in SharePoint projects.
In the Assets tab of the editor, choose the New button.

The Add New Asset dialog box appears.
In the Type list, choose Microsoft.VisualStudio.MefComponent.

Note

This value corresponds to the MefComponent element in the extension.vsixmanifest file. This element specifies the name of an extension assembly in the VSIX package. For more information, see MEFComponent Element.
In the Source list, choose A project in current solution.
In the Project list, choose DeploymentStepExtension, and then choose the OK button.
In the manifest editor, choose the New button again.

The Add New Asset dialog box appears.
In the Type list, enter SharePoint.Commands.v4.

Note

This element specifies a custom extension that you want to include in the Visual Studio extension. For more information, see CustomExtension Element.
In the Source list, choose A project in current solution.
In the Project list, choose SharePointCommands, and then choose the OK button.
On the menu bar, choose Build, Build Solution, and then make sure that the solution compiles without errors.
Make sure that the build output folder for the UpgradeDeploymentStep project now contains the UpgradeDeploymentStep.vsix file.

By default, the build output folder is the ..\bin\Debug folder under the folder that contains your project file.

Preparing to Test the Upgrade Deployment Step

To test the upgrade deployment step, you must first deploy a sample solution to the SharePoint site. Start by debugging the extension in the experimental instance of Visual Studio. Then create a list definition and list instance to use to test the deployment step, and then deploy them to the SharePoint site. Next, modify the list definition and list instance and redeploy them to demonstrate how the default deployment process overwrites solutions on the SharePoint site.

Later in this walkthrough, you'll modify the list definition and list instance, and then you'll upgrade them on the SharePoint site.

To start debugging the extension

Restart Visual Studio with administrative credentials, and then open the UpgradeDeploymentStep solution.
In the DeploymentStepExtension project, open the UpgradeStep code file, and then add a breakpoint to the first line of code in the CanExecute and Execute methods.
Start debugging by choosing the F5 key or, on the menu bar, choosing Debug, Start Debugging.
Visual Studio installs the extension to %UserProfile%\AppData\Local\Microsoft\VisualStudio\11.0Exp\Extensions\Contoso\Upgrade Deployment Step for SharePoint Projects\1.0 and starts an experimental instance of Visual Studio. You'll test the upgrade deployment step in this instance of Visual Studio.

To create a SharePoint project with a list definition and a list instance

In the experimental instance of Visual Studio, on the menu bar, choose File, New, Project.
In the New Project dialog box, expand the Visual C# node or the Visual Basic node, expand the SharePoint node, and then choose the 2010 node.
At the top of the dialog box, make sure that .NET Framework 3.5 appears in the list of versions of the .NET Framework.

Projects for Microsoft SharePoint Foundation 2010 and Microsoft SharePoint Server 2010 require this version of the .NET Framework.
In the list of project templates, choose SharePoint 2010 Project, name the project EmployeesListDefinition, and then choose the OK button.
In the SharePoint Customization Wizard, enter the URL of the site that you want to use for debugging.
Under What is the trust level for this SharePoint solution, choose the Deploy as a farm solution option button.

Note

The upgrade deployment step doesn't support sandboxed solutions.
Choose the Finish button.

Visual Studio creates the EmployeesListDefinition project.
Open the shortcut menu for the EmployeesListDefinition project, choose Add, and then choose New Item.
In the Add New Item – EmployeesListDefinition dialog box, expand the SharePoint node, and then choose the 2010 node.
Choose the List item template, name the item Employees List, and then choose the Add button.

The SharePoint Customization Wizard appears
On the Choose List Settings page, verify the following settings, and then choose the Finish button:
1. Employees List appears in the What name do you want to display for your list? box.
2. The Create a customizable list based on: option button is chosen.
3. Default (Blank) is chosen in the Create a customizable list based on: list.
Visual Studio creates the Employees List item with a Title column and a single empty instance and opens the List Designer.
In the List Designer, on the Columns tab, choose the Type a new or existing column name row, and then add the following columns in the Column Display Name list:
1. First Name
2. Company
3. Business Phone
4. E-Mail
Save all files, and then close the List Designer.
In Solution Explorer, expand the Employees List node, and then expand the Employees List Instance child node.

In the Elements.xml file, replace the default XML in this file with the following XML. This XML changes the name of the list to Employees and adds information for an employee who's named Jim Hance.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <ListInstance Title="Employees"
                OnQuickLaunch="TRUE"
                TemplateType="10000"
                Url="Lists/Employees"
                Description="Simple list to test upgrade deployment step">
    <Data>
      <Rows>
        <Row>
          <Field Name="Title">Hance</Field>
          <Field Name="FirstName">Jim</Field>
          <Field Name="Company">Contoso</Field>
          <Field Name="Business Phone">555-555-5555</Field>
          <Field Name="E-Mail">jim@contoso.com</Field>
        </Row>
      </Rows>
    </Data>
  </ListInstance>
</Elements>

Save and close the Elements.xml file.
Open the shortcut menu for the EmployeesListDefinition project, and then choose Open or Properties.

The Properties Designer opens.
On the SharePoint tab, clear the Auto-retract after debugging check box, and then save the properties.

To deploy the list definition and list instance

In Solution Explorer, choose the EmployeesListDefinition project node.
In the Properties window, make sure that the Active Deployment Configuration property is set to Default.
Choose the F5 key or, on the menu bar, choose Debug, Start Debugging.
Verify that the project builds successfully, that the web browser opens to the SharePoint site, that the Lists item in the Quick Launch bar includes the new Employees list, and that the Employees list includes the entry for Jim Hance.
Close the web browser.

To modify the list definition and list instance and redeploy them

In the EmployeesListDefinition project, open the Elements.xml file that's a child of the Employee List Instance project item.

Remove the Data element and its children to remove the entry for Jim Hance from the list.

When you finish, the file should contain the following XML.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <ListInstance Title="Employees"
                OnQuickLaunch="TRUE"
                TemplateType="10000"
                Url="Lists/Employees"
                Description="Simple list to test upgrade deployment step">
  </ListInstance>
</Elements>

Save and close the Elements.xml file.
Open the shortcut menu for the Employees List project item, and then choose Open or Properties.
In the List Designer, choose the Views tab.
In the Selected columns list, choose Attachments, and then choose the < key to move that column to the Available columns list.
Repeat the previous step to move the Business Phone column from the Selected columns list to the Available columns list.

This action removes these fields from the default view of the Employees list on the SharePoint site.
Start debugging by choosing the F5 key or, on the menu bar, choosing Debug, Start Debugging.
Verify that the Deployment Conflicts dialog box appears.

This dialog box appears when Visual Studio tries to deploy a solution (the list instance) to a SharePoint site to which that solution has already been deployed. This dialog box won't appear when you execute the upgrade deployment step later in this walkthrough.
In the Deployment Conflicts dialog box, choose the Resolve Automatically option button.

Visual Studio deletes the list instance on the SharePoint site, deploys the list item in the project, and then opens the SharePoint site.
In the Lists section of the Quick Launch bar, choose the Employees list, and then verify the following details:
- The Attachments and Home Phone columns don't appear in this view of the list.
- The list is empty. When you used the Default deployment configuration to redeploy the solution, the Employees list was replaced with the new empty list in your project.

Testing the Deployment Step

You are now ready to test the upgrade deployment step. First, add an item to the list instance in SharePoint. Then change the list definition and list instance, upgrade them on the SharePoint site, and confirm that the upgrade deployment step doesn't overwrite the new item.

To manually add an item to the list

In the ribbon on the SharePoint site, under the List Tools tab, choose the Items tab.
In the New group, choose New Item.

As an alternative, you can choose the Add new item link in the item list itself.
In the Employees – New Item window, in the Title box, enter Facilities Manager.
In the First Name box, enter Andy.
In the Company box, type Contoso.
Choose the Save button, verify that the new item appears in the list, and then close the web browser.

Later in this walkthrough, you will use this item to verify that the upgrade deployment step doesn't overwrite the contents of this list.

To test the upgrade deployment step

In the experimental instance of Visual Studio, in Solution Explorer, open the shortcut menu for the EmployeesListDefinition project node, and then choose Properties.

The Properties Editor/Designer opens.
On the SharePoint tab, set the Active Deployment Configuration property to Upgrade.

This custom deployment configuration includes the new upgrade deployment step.
Open the shortcut menu for the Employees List project item, and then choose Properties or Open.

The Properties Editor/Designer opens.
On the Views tab, choose the E-Mail column, and then choose the < key to move that column from the Selected columns list to the Available columns list.

This action removes these fields from the default view of the Employees list on the SharePoint site.
Start debugging by choosing the F5 key or, on the menu bar, choosing Debug, Start Debugging.
Verify that the code in the other instance of Visual Studio stops on the breakpoint that you set earlier in the CanExecute method.
Choose the F5 key again or, on the menu bar, choose Debug, Continue.
Verify that the code stops on the breakpoint that you set earlier in the Execute method.
Choose the F5 key or, on the menu bar, choose Debug, Continue a final time.

The web browser opens the SharePoint site.
In the Lists section of the Quick Launch area, choose the Employees list, and then verify the following details:
- The item that you manually added earlier (for Andy, the facilities manager) is still in the list.
- The Business Phone and E-mail Address columns don't appear in this view of the list.
The Upgrade deployment configuration modifies the existing Employees list instance on the SharePoint site. If you used the Default deployment configuration instead of the Upgrade configuration, you would encounter a deployment conflict. Visual Studio would resolve the conflict by replacing the Employees list, and the item for Andy, the facilities manager, would be deleted.

Cleaning up the Development Computer

After you finish testing the upgrade deployment step, remove the list instance and list definition from the SharePoint site, and remove the deployment step extension from Visual Studio.

To remove the list instance from the SharePoint site

Open the Employees list on the SharePoint site, if the list isn't already open.
In the ribbon on the SharePoint site, choose the List Tools tab, and then choose the List tab.
In the Settings group, choose the List Settings item.
Under Permissions and Management, choose the Delete this list command, choose OK to confirm that you want to send the list to the Recycle Bin, and then close the web browser.

To remove the list definition from the SharePoint site

In the experimental instance of Visual Studio, on the menu bar, choose Build, Retract.

Visual Studio retracts the list definition from the SharePoint site.

To uninstall the extension

In the experimental instance of Visual Studio, on the menu bar, choose Tools, Extensions and Updates.

The Extensions and Updates dialog box opens.
In the list of extensions, choose Upgrade Deployment Step for SharePoint Projects, and then choose the Uninstall command.
In the dialog box that appears, choose Yes to confirm that you want to uninstall the extension, and then choose Restart Now to complete the uninstallation.
Close both instances of Visual Studio (the experimental instance and the instance of Visual Studio in which the UpgradeDeploymentStep solution is open).

Share via