With SPClientSideDeployment you can point Visual Studio to any environment and deploy your files to that environment. This is fine for development, but typically is not good practice for higher environments. Most organisations dictate that a package is given to IT Ops, who will perform the deployment to these higher environments.
The 1.1 release of SPClientSideDeployment adds a new feature that allows you to generate a deployment package for your project. The package comes with a PowerShell script that can be executed to deploy the files to your target environment, which can be any local or remote SharePoint instance, including SharePoint Online. Once generated, the package is ready to be handed over to another party to execute the deployment.
Download it now!
You can download the latest version of SPClientSideDeployment from the Visual Studio Gallery.
Publishing the Package
There are a couple of ways to publish the package for a project.
- Alt Q + A: Publish the package for the solution’s StartUp project. This can also be accessed from Tools \ SharePoint Deployment \ Publish Deployment Package.
You are then prompted to select a location for the package.
Click OK and a package is generated at the selected location for your project.
What does the package contain?
The following items are copied to the selected package location:
- All items in the project that are referenced in the project’s DeploymentSettings.xml file
- The project’s DeploymentSettings.xml file
- A PowerShell script file, namely DeployFiles.ps1. This file is generated by the tool and can be used to deploy the files.
- SharePoint client-side assemblies
Executing the DeployFiles.ps1 script
This script uses CSOM to deploy the files in the package to a local or remote SharePoint instance, including SharePoint Online. The SharePoint client-side assemblies are included in the package. This means you can execute the script on any machine, even one that does not have SharePoint installed.
Note that the script must be executed from within the package folder.
The parameters for the script are as follow:
- [string] SiteUrl: Mandatory. URL for the target SharePoint web. All files will be deployed to this web or sub-web(s) under this web.
- [string] DeploymentSettingsFilePath: Mandatory. The path to the DeploymentSettings.xml file that will be used to deploy the files. This file must be located within the package folder.
- [string] UserName: Optional. User name that will be used to authenticate to the target web(s) and deploy the files. This parameter is only optional when Windows is specified for the AuthenticationMethod parameter. If this parameter is not specified, and the authentication method is Windows, then the credentials of the current user will be used for deployment.
- [string] Password: Optional. Password for the specified user name. This parameter is only optional when Windows is specified for the AuthenticationMethod parameter. If this parameter is not specified, and the authentication method is Windows, then the credentials of the current user will be used for deployment.
- [string] AuthenticationMethod: Optional. The authentication method that will be used. Valid values are Windows, Forms or SharePointOnline. The default is Windows.
- [switch] Force: Optional. If Force is specified, existing files that are checked out to another user on the target instance will be overwritten. Else, these files will not be deployed.
What does the DeployFiles.ps1 script do?
Similar to SPClientSideDeployment’s Visual Studio command, this script reads the DeploymentSettings.xml file and deploys files to the specified locations. It however does the extra things below that the Visual Studio command does not.
- The script creates all folders on the path specified in the targetFolder attribute in the DeploymentSettings.xml file if they do not exist at the target instance. For example, if the targetFolder is Style Library/MyPortal/CSS/Mobile, and the CSS and Mobile folders do not exist, then they will be created by the script. The first level on the path is the target library, and for libraries underneath _catalogs it is the first two levels, e.g. _catalogs/masterpage. These levels are never created by the script.
- The script publishes a major version for all deployed files. If content approval is enabled on the target library, the script will approve the files.
- If the Force parameter is specified, the script will overwrite existing files that are checked out to another user (other than the current user) at the target instance. Similar to the Visual Studio command, existing files that are checked out to the current user will always be overwritten.
Customising the DeployFiles.ps1 script
Each time you republish the deployment package, all existing files in the selected package location will be overwritten. For this reason, never modify the DeployFiles.ps1 file directly.
On execution, the DeployFiles.ps1 script loads a second script, namely DeployFiles-Custom.ps1, if it is present in the package folder. You therefore can customise any function in DeployFiles.ps1 using the following steps:
- Create DeployFiles-Custom.ps1 at the root of the package folder (where DeployFiles.ps1 is found)
- Copy the function to be customised from DeployFiles.ps1 to the custom file in step 1. Do not change the function signature.
- Customise the body of the function in the custom file
The script calls the PreDeployFiles function and PostDeployFiles function before and after deploying the files. To hook into these events, override these functions in the DeployFiles-Custom.ps1.
SPClientSideDeployment has always allowed you to quickly deploy files from Visual Studio to SharePoint during development. This new feature takes this further by allowing you to publish your project as a ready-to-go package for promotion that reuses the same deployment configuration that has been tested during development.
I hope you find this feature useful and let me know if you have any feedback or suggestion.