Sitecore TDS

Web Deploy files

Sitecore TDS can generate WebDeploy packages at build time. These packages can contain compiled C# projects and Sitecore items. The WebDeploy package generated by TDS supports all TDS deployment functions, and the result of installing a TDS WebDeploy package has the same result as installing an update package generated by Sitecore TDS or pointing Sitecore TDS at the server and building directly to the server.

There are many aspects to deploying a Sitecore website. Sitecore TDS tries to automate some of the more difficult parts of the deployment process, but will not be a complete end-to-end solution. The developer will still need to setup build and deployment pipelines using their preferred build and deployment automation tools. Sitecore TDS is designed to be easily integrated into the deployment process the DevOps team wants to use.

Deployment process

When Sitecore TDS generates a WebDeploy package containing items, the items are stored in the package in a folder under the /temp/WebDeployItems folder. These files are installed in Sitecore when the server restarts after the WebDeploy package is deployed.

The WebDeploy package also contains an assembly in the /bin folder that performs the deployment. This assembly also installs a WebAPI service to allow the deployment to be monitored. The WebAPI service can also remove itself after the deployment. See below for more details on the WebAPI service.

Building WebDeploy packages

Sitecore TDS can be configured to build WebDeploy packages simply by enabling WebDeploy package generation in the WebDeploy package tab of the Sitecore TDS property pages.

The package is generated in a folder under the project root /bin/WebDeploy_[Configuration name]. The package is named [Package name].wdp.zip.

TDS also adds a file called PublishWebDeploy.ps1. This file contains scripts that can be used to deploy the web deploy package on a Sitecore server. This script can be run standalone or on a build/release server that supports executing Powershell scripts.

Deployment Powershell Script

The PublishWebDeploy.ps1 script installs the package on a server using MSDeploy. It also uses the WebAPI endpoint exposed by the item installer assembly to monitor the installation of items in the package.

The PublishWebDeploy.ps1 script will wait until all items in the deployment are installed on the server. It can also display verbose installation logs from the server so the developer can monitor and/or log the progress of the items being installed.

The PublishWebDeploy.ps1 script accepts the following parameters:

PackagePath - Path for the WebDeploy package being installed. This parameter is optional, and if left out, the script will monitor all package installations on the server. This is useful on build/deployment servers that support installing one or more WebDeploy packages as part of their deployment process.
PublishSettingsPath - Path to a .publishsettings file. This file can be generated by Azure or through the WebDeploy configuration console. This parameter is optional, but if it isn’t specified, the user must specify the parameters ComputerName, SiteName, UserName, Password and AuthType. One of the advantages to using .publishsetting files generated by Azure is the credentials are encrypted in the file, preventing them from showing up in build logs.
MSDeployAllowUntrusted - Adds the -AllowUntrusted switch to the MSDeploy command used by the script to install the package. By default, MSDeploy requires a valid https certificate on the server. In some cases, the server may have a self-signed certificate and this setting allows MSDeploy to proceed with the deployment even though the certificate isn’t valid.
Username - The username used by MSDeploy to authenticate to the server where the package is being deployed. This needs to be supplied to the script if the PublishSettingsPath is not specified.
Password - The password used by MSDeploy to authenticate to the server where the package is being deployed. This needs to be supplied to the script if the PublishSettingsPath is not specified.
ComputerName - The name of the server MSDeploy will publish the package to. This name will also be used to monitor the deployment through the deployment service WebAPI. This needs to be supplied to the script if the PublishSettingsPath is not specified.
SiteName - The name of the IIS website where MSDeploy is installing the WebDeploy package. This needs to be supplied to the script if the PublishSettingsPath is not specified.
AuthType - The Authentication type used to authenticate the username and password when deploying the package. The two values for this are ‘Basic’ and ‘NTLM’. This needs to be supplied to the script if the PublishSettingsPath is not specified.
UseHttp - If this switch is specified, MSDeploy uses http to communicate with the Web Deploy agent instead of https.
ViewLogs - If this switch is specified, installation logs and status messages are displayed as the item deployment progresses.
Remove - When this switch is specified, the item deployment service assembly is removed from the /bin folder once the deployment is complete. This will cause the App Pool to recycle.

PaaS deployment to Azure

Sitecore PaaS Azure instances use App Services to host Sitecore instances. This offers a number of advantages to managing the servers in Azure. One of the benefits is the installation and configuration of Web Deploy is built in automatically.

The Azure App Service can generate a .publishsettings file that will be used by the PublishWebDeploy.ps1 script. The .publishsettings file contains the fully qualified server name and credentials MSDeploy needs to deploy the WebDeploy package.

To generate a .publishsettings file, open the App Service in the Azure dashboard and click on the “Get publish profile” button:

Please note: If “Reset publish profile” is clicked, any existing publish profiles will cease to work, causing any deployments using them to fail.

This is an example of using the PublishWebDeploy.ps1 script deploy to a Sitecore instance using the publish profile from Azure:

.\PublishWebDeploy.ps1 -PackagePath .\MyPackage.wdp.zip -PublishSettingsPath .\MyAzure.PublishSettings -ViewLogs

This will deploy the package to the Azure App Service specified in the publish settings and display progress logs. The script will wait until the deployment completes before returning. This is useful for synchronizing and monitoring the deployment progress.

PaaS deployment using a VSO Release Pipeline

Visual Studio online allows users to create and manage very powerful release pipelines. There are a number of other build and release tools available in the marketplace. We are using VSO as an example of how to setup a release using the WebDeploy packages created by Sitecore TDS. In our sample release pipeline, we only had two steps:

The first step deploys the web deploy package using the VSO Azure App Service deployment step instead of the letting the Powershell script deploy it.

There are no other settings in the collapsed sections of the tasks. This task was configured exactly as shown above.

The second step runs the Powershell script supplied by Sitecore TDS:

There are no other settings in the collapsed sections of the tasks. This task was configured exactly as shown above.

IaaS or Standalone deployments

The WebDeploy packages created by Sitecore TDS are not tied to the Azure infrastructure, so they can be used on any server that supports Web Deploy. This allows the same packages and scripts to be used across multiple environments, following best practices in release management.

The biggest challenge to using Web Deploy scripts on environments other than Azure is setting up Web Deploy. There are many resources on the web for this, so I will not reproduce the steps here. Here are the websites I found useful:

NOTE

The first link above, shows how to switch the client machine to use TLS 1.2. Sitecore specifies that TLS 1.0 and 1.1 are disabled on the server, and MSDeploy defaults to TLS 1.0. I found this issue difficult to track down because MSDeploy would not communicate with my server at all until I forced it to TLS 1.2. Once I was communicating with the server, there were a few authentication issues to resolve. Solutions to the error I faced along with a number of other possible problems are covered in the other links.

Once Web Deploy is working on the server, installing the package works much like the example above:

.\PublishWebDeploy.ps1 -PackagePath .\HHogSSSS.Master.wdp.zip -ComputerName MyServer 
		-Username DeployUser -Password MyPassword -SiteName MySite -AuthType Basic 
		-MSDeployAllowUntrusted -ViewLogs 

This example uses explicit connection information instead of a publish settings file.

NOTE

When configuring Web Deploy on a server, you can generate a .publishsettings file. This file contains everything needed to deploy except the password. If you use this file, you can specify -PublishSettingsPath and -Password as parameters to the PublishWebDeploy.ps1 script.

WebAPI Service Functions

The TDS WebAPI deployment service is designed to return status information and detailed logs while a deployment is taking place. The endpoint for the Deployment service is http://[server]/Api/TDS/WebDeploy. The WebAPI service exposes the following actions:

public string Invoke(): Triggers the deployment process if it isn’t already running. Normally, the deployment process starts when Sitecore starts. Calling Invoke will ensure it has started.
- Return Value: Always returns “OK”.
public string[] Messages(bool flush): Returns any messages in the message log. If flush is true, the message log is emptied. This is used to get any messages generated by the install process. Messages generated by the install process are also written to the Sitecore logs.
- Return Value: An array of strings representing messages in the message log.
public string Remove(): Removes the service assembly from the /bin folder. This will cause the App Pool to recycle since an assembly is being deleted from the /bin folder.
- Return Value: Returns “Removed” if the service was removed successfully.
public InstallServiceStatus Status(): Returns the status of the installation process in an InstallServiceStatus object.
- Return Value: Returns an InstallServiceStatus object. This object has the following fields:
  - ProgressPercent: 0-100 number indication a very rough estimate on how far along the install is. This tries to be slightly more accurate than the windows file copy, but no promises ;-)
  - DeploymentStatus: Returns one of [Idle, Deploying, Complete, Failed, AnotherServerBusy]. These values describe the service state. The value AnotherServerBusy indicates that a deployment is happening on a load balanced or scaled out instance of Sitecore and the load balancer sent the status request to a server in the cluster that is not performing the install.
public void ClearLogs(): Empties the message log without returning the contents of the log. This performs the same function as passing true to Messages().

All actions use the HttpGet request verb to invoke their function.