[New for Release 1.2.0.0]

The SharePointDeployment activity can be used to deploy a SharePoint solution to a SharePoint 2010 site via PowerShell commands. In this example we aim to show the the basic steps that are required to get the activity integrated into a build.

The activity uses PowerShell to manage SharePoint tasks, and can be used in a two scenarios

  • A local SharePoint instance hosted on the build agent (not that common a scenario) 
  • A remote SharePoint farm that the build user account has access to e.g. in the same domain or a trusted domain

Remote tasks are performed via WinRM. For details on configuring WinRM see MSDN
REMEMBER you only need WinRM to access remote SharePoint servers, it is not required for local instances of SharePoint on the build agent. 

WinRM relies on there being a trust relationship between machines. If there is not a trust relationship between the build user and the SharePoint farm then you will not be able to use this activity. In this case you will probably need to investigate using your own signed PowerShell scripts to perform the deployment.

A quick way to test if using the activity should work to a remote machine is to login on the build agent box as the build user and in a PowerShell prompt issue the command

invoke-command  -computerName RemoteMachineName -scriptblock {Get-ChildItem}

If all is workjing with WinRM then you should get a list of files returned, if you get an error you need to resolve this prior to attempting to use this activity.

Before you can make use of any of the TFS 2010 community build activities you have to make sure they are available for the build system and on your development PC. Instructions for this process can be found in the ALM Rangers build guide or in the StyleCop page of this wiki. This page assumes the SharePointDeployment activity is available in the developers build process workflow toolbox. Hence we are able to build the workflows shown below

Actions Available

The activity can perform the following actions which can be used in the workflow in either the Build Agent or Build Controller.

Action Description Properties Used
AddSolution Add a new solution by issuing an add-spsolution command
  • WSPLiteralPath – path to WSP file e.g. c:\tmp\mysolution.wsp
InstallSolution Deploys a solution by issuing  an install-spsolution command
  • WSPName – name of solution e.g. mysolution.wsp
  • Force – to force deployment
  • GACInstall – to install assemblies to the GAC
  • SiteUrl – the webapplication to deploy to e.g. http://mysite 
UpdateSolution Updates an already installed solution by issuing an update-spsolution command
  • WSPLiteralPath – path to WSP file e.g. c:\tmp\mysolution.wsp
  • WSPName – name of solution e.g. mysolution.wsp
  • Force – to force deployment
  • GACInstall – to install assemblies to the GAC
UnInstallSolution Retracts a solution by issuing an uninstall-spsolution command
  • WSPName – name of solution e.g. mysolution.wsp
  • SiteUrl – the webapplication to retract from e.g. http://mysite
RemoveSolution Removes a solution by issuing a remove-spsolution command
  • WSPName – name of solution e.g. mysolution.wsp
EnableFeature Enables a feature by issuing an enable-spfeature command
  • FeatureName as GUID or string e.g. my_feature (note underscores replacing spaces)
  • SiteUrl – the site to activate on e.g. http://mysite/sites/site1
DisableFeature Disables a feature by issuing a disable-spfeature command
  • FeatureName as GUID or string e.g. my_feature (note underscores replacing spaces)
  • SiteUrl – the site to deactivate on e.g. http://mysite/sites/site1
GetFeature Either gets a list of all features installed or a single named feature by issuing a get-spfeature command
  • No properties to list all
  • FeatureName as GUID or string e.g. my_feature (note underscores replacing spaces)
GetSolution Either gets a list of all solutions installed or a single named solution by issuing a get-spsolution command
  • No properties to list all
  • WSPName as GUID or string e.g. mysolution.wsp

Actions will usually be used in the following sequence

Add Solution to SharePoint Farm
     Deploy Solution to Site(s)
          Activate Feature(s)
                [Use the feature(s)]
         Deactivate Feature(s)
     Retract Solution from Site(s)
Delete Solution from Farm

There are other important properties

Property Description
ComputerName This enables remote operations. It should be set to the name (or IP address) of the remote machine the PowerShell command should run on via WinRM.

This requires that WinRM is installed on the target and all the required rights are in place. If left blank the commands are run locally as the build user account
OtherParameters The properties listed above do not cover all the options available in PowerShell for SharePoint. Any other parameters can be placed in the OtherParameters property and these will be appended to the command.
ScriptTimeout How long for the activity to wait for the script to complete in milliseconds, the default is 0 which means wait forever
FailBuildOnError Inherited from the base class, this defaults to false but I have found it very useful to set this to true. This means if the PowerShell command returns any errorlevel other than zero the build is stopped

 

General Notes

What are we building?

In this sample we have created a build  of a default SharePoint 2010 Visual Webpart solution. The only change from accepting defaults for the Visual Studio solution and the build is that in the build we are passing the MSBuild argument to /p:IsPackaging=true to make sure the WSP is created as part of the build

Add Variable

The SharePointDeployment activity usually does not return a value as the signalling for success is whether the PowerShell script completed or not. However the two Get actions do return arrays of data. To capture these results a build variable is required.

image

A build variable of type SharePointDeploymentStatus[] with a scope of the whole workflow is the most convenient.

Build Arguments

In this sample many properties are hard coded strings. For a production build you would probably want to make use of build arguments so a build process template can be reused for different projects.

Listing Features and Solutions (on a remote server)

Configuring the activities

Drop the SharePointDeployment activity onto the workflow

image

 image

Set the following settings

  • Action: GetFeature (could also use same basic technique for GetSolution)
  • FailBuildOnError: defaults to false, so useful to set to true
  • ScriptResults: SharePointResult, the the build variable setup as detailed above
  • ScriptTimeout: How long in Milliseconds to give the script be it is terminated (0 is wait for ever)
  • ServerName: The name of the remote SharePoint server, this is all that has to be set to change from a local SharePoint server to a remote one

Next add a Foreach activity and inside add a WriteBuildMessage activity. These are configured as follows:

 

image

The ForEach activity needs to be set to the type of SharePointDeploymentStatus and to enumerate across the SharePointResult variable.

image

The message is then set to output the item.ToString(). Note I set the importance to high to make sure it appears in the log.

Running the activity

Running the build should list all the features on the SharePoint instance. Also the PowerShell command is shown, note it is wrappered  with the invoke-command to allow the command to be run via WinRM

invoke-command -computername typhoon{Add-PsSnapin Microsoft.SharePoint.PowerShell; get-spfeature | fl -property Displayname, Id ;}

Also note the handling of the get-spfeature output, it might look rather complex, but piping the result via this filter makes sure the returned values are the same for both local and remotely run commands

image

 

Installing and Updating Features and Solutions (on the local instance)

The most usual operations that you will want to do with this activity to install, deploy and activate a feature. Once a solution/feature is installed you may also want to update it with a new revision. This can be achieved within a build workflow.

Note this sample assume that SharePoint 2010 is installed on the same box as the build agent.

[Remember to make this a remote command just set a value for the ServerName property]

However for this to work the build agent must be running as a domain user that as rights on the Sharepoint server to manage SharePoint via PowerShell

Configuring the activities

From the toolbox drag on the activities as shown below (each activity starting SPD is a SharePointDeployment activity). Basically we check to see of the solution is installed, we then either use a sequence of command to install the solution or do an upgrade.

image

To check if a solution is installed we use the following settings

image

  • Action: GetSolution
  • FailBuildOnError: defaults to false, so useful to set to true
  • ScriptResults: SharePointResault, the the build variable setup as detailed above
  • WSPname: The name of the WSP we are looking for (this could also be its GUID)

This activity will return an array of solutions details that match the WSPName. We use a workflow if activity to check if this array contains zero entries (solution not installed) or more (solution is installed). This allows us to run the correct set of SharePointDeployment activity actions.

Adding a Solution

Adding the solution requires four activity

image

First we add the solution, this requires the settings

  • Action: AddSolution
  • FailBuildOnError: defaults to false, so useful to set to true
  • WSPLiteralPath: The path of the WSP file we wish to install, this can be an area where a problem appears. If you are using a SharePoint installation on the same box as the Build Agent (a local install, where no ServerName is set) then you can pickup the WSP file from the drop location using BuildDetail.DropLocation + ”\VisualWebParkProject1.wsp”. However, if you are using a remote SharePoint installation, and all the commands are being run via PowerShell invoke-command then there is a problem accessing resource not on the SharePoint server such as UNC shares like the drops folder. This issue is discussed in this post by Ravikanth Chaganti. The same problem is seen using the SharePoint Teams build integration, you have to issue commands on both the build agent (client) and SharePoint server (server) to allow remote access for the client and the ability to make network calls out from the server.

The easiest solution to this problem, avoiding the need to grant these rights and pass certificates, to use a Build activity such as the RoboCopy one in this project to copy the WSP from the drop to a UNC share on the SharePoint server. This means that the WSPLiteralPath can be set to something like “C:\SHARE\VisualWebParkProject1.wsp” i.e. adding the solution from a location locally on the SharePoint server, hence removing any questions of double hope remote access to a network share.

image

Once the solution has been installed it needs to be deployed to either the farm or a specific site. In this sample we deploy to a web application, this requires the settings

  • Action: InstallSolution
  • FailBuildOnError: defaults to false, so useful to set to true
  • SiteUrl: If deploying to a web application this should be set, in my case to the  local site http://typhoon, again hard coded but would usually be an argument or variable
  • WSPname: The name of the WSP we are deploying (this could also be its GUID)
  • GACDeploy: Deploy the assemblies to the GAC

The problem with this action is that the deployment is asynchronous. The script will complete before the solution is deployed. To address this you need to  drop delay activity in the sequence.

image

This activity is set to delay for 30 seconds, again this could be passed as an argument to aid workflow reuse.

image

Finally we can enable the feature on a specific site

  • Action: EnableFeature
  • FailBuildOnError: defaults to false, so useful to set to true
  • SiteUrl: This time we pass in the url of a specfic site to active the feature on e.g. http://typhoon/sites/site1
  • FeatureName: The name of the feature (can also use its GUID)

Update

The alternate path is to just run the upgrade command

image

  • Action: UpgradeSolution
  • FailBuildOnError: defaults to false, so useful to set to true
  • WSPLiteralPath: The path of the WSP file we wish to install, see discussion of issues with remote servers above in section on Add-Solution
  • WSPname: The name of the WSP we are deploying (this could also be its GUID)
  • GACDeploy: Deploy the assemblies to the GAC <!--EndFragment-->

Running the activity

When the activity is run the steps can be seen in the build log. The lines show the full PowerShell commands run, thus allowing you to try any failing command in a PowerShell console. Note all commands are prefixed with Add-psSnapin Microsoft.SharePoint.PowerShell to load the correct assemblies.

If any PowerShell command fails the build will fail.

image

Removing Features and Solutions

There is also the case that you may wish to remove a solution or feature. This is the reverse process of the installation sequence.

Configuring the activities

image

First we disable the feature on a given site

image

  • Action: DisableFeature
  • FailBuildOnError: defaults to false, so useful to set to true
  • SiteUrl: This time we pass in the url of a specific site to de-active the feature on e.g. http://typhoon/sites/site1
  • FeatureName: The name of the feature (can also use its GUID)

We can then retract the solution

image

  • Action: UninstallSolution
  • FailBuildOnError: defaults to false, so useful to set to true
  • SiteUrl: If deploying to a web application this should be set, in my case to the local site http://typhoon
  • WSPname: The name of the WSP we are retracting (this could also be its GUID)

Again we need to apply a delay to allow the retract to complete

image

Finally we can remove the solution

image

  • Action: AddSolution
  • FailBuildOnError: defaults to false, so useful to set to true
  • WSPName: The name or GUID of the solution

Running the activity

Again when we run the workflow we can see all the commands issued in the build log. Note all the commands are set to not prompt for confirmation

image

Last edited Jan 24, 2012 at 5:09 PM by rfennell, version 6

Comments

No comments yet.