Getting started with the SharePointDeployment activity
[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 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 working 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 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 on the getting started 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
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 |
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
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.
A build variable of type SharePointDeploymentStatus[] with a scope of the whole workflow is the most convenient.
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.
Drop the SharePointDeployment activity onto the workflow
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:
The ForEach activity needs to be set to the type of SharePointDeploymentStatus and to enumerate across the SharePointResult variable.
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 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
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
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.
To check if a solution is installed we use the following settings
- Action: GetSolution
- FailBuildOnError: defaults to false, so useful to set to true
- ScriptResults: SharePointResault, 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 the solution requires four activity
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.
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.
This activity is set to delay for 30 seconds, again this could be passed as an argument to aid workflow reuse.
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
- 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
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.
There is also the case that you may wish to remove a solution or feature. This is the reverse process of the installation sequence.
First we disable the feature on a given site
- 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
- 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
Finally we can remove the solution
- Action: AddSolution
- FailBuildOnError: defaults to false, so useful to set to true
- WSPName: The name or GUID of the solution
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
