Enter Visual Studio Team Services

When I set out to investigate, work with, and document CD approaches with Umbraco Cloud the one I most wanted to try was VSTS. This is not necessarily a new approach. In fact, Morten Christensen had come up with the idea in June 2016. #H5YR Morten! If you were one of the lucky attendees at uDuf in Gold Coast, Australia what follows may sound familiar as it is similar to what I presented there.

This approach uses VSTS for the build and the deploy services rather than using discreet offerings for each of those. It makes for a more obvious configuration, perhaps at the expense of some flexibility. In any case, once you get the initial configuration completed it can be very quick to adjust and to add additional configurations for other projects. The VSTS configuration is well-documented at the GitHub repo for the VSTS task. Note that some of the following duplicates the documentation found there, but here I cover the complete setup and approach.

Getting Set Up

There are two parts to configure for this VSTS CD approach; 1) the VSTS Umbraco Cloud Deploy Task, and 2) the Visual Studio Web Application project. The VSTS Deploy Task needs to be configured just one time and then can be used across all your VSTS projects that target Umbraco Cloud. The Visual Studio project configuration is needed per project. However, you can leverage some of the Umbraco provided guidance on setting up a Visual Studio solution from the official documentation. Note that the Umbraco provided setup utility, UaaS.cmd, creates a Web Site project but that the VSTS approach assumes a Web Application project. You will need to make this change manually - see the Configuring the Visual Studio Project section below. Sorry 🙁

Building and Installing the VSTS Tas

In order to use this approach, you'll need to complete a one-time build and upload of a VSTS task as it is not available in the Visual Studio Marketplace. The steps are simple, but will require some tools if this is not something you’ve done before. The steps are:

Clone the repository for the VSTS Deploy to Umbraco Cloud Task

Open the solution, restore the nuget packages, and build the solution

You may want to edit the ToFileSys.pubxml file at this time (don't worry if it’s not familiar, I cover it in more detail later)

You may want to edit the file at this time (don't worry if it’s not familiar, I cover it in more detail later) Install the TFS CLI client

npm install -g tfx-cli

Authenticate to your VSTS project using a personal access token

That's its own article, here's the best reference

That's its own article, here's the best reference Upload the task to your VSTS project

tfx build tasks upload --task-path C:\path\to\tasks\DeployUmbracoCloudRepository

With that done you will see the “Deploy to Umbraco Cloud” task in your VSTS project’s tasks under the Deploy tab. You rock!

Configuring the Build and Deploy Task

The idea with using the Deploy task from this repository is that we have a Visual Studio solution with Umbaco installed that is built in VSTS, and then use the build output for deploying the changes to Umbraco Cloud. In order to achieve this there is a minimal and recommended Build setup with the steps outlined below. The "Build solution" step uses the following parameters:

/p:UseWPP_CopyWebApplication=True /p:PipelineDependsOnBuild=False /p:PublishProfile=ToFileSys.pubxml /p:DeployOnBuild=true /p:AutoParameterizationWebConfigConnectionStrings=False /p:PublishOutDir=$(Build.StagingDirectory)\_Publish

Notice that the build is published to $(Build.StagingDirectory)\_Publish and that it uses a publishing profile called ToFileSys.pubxml. This pubxml file should be placed in /Properties/PublishProfiles/ToFileSys.pubxml under the Web Application project where Umbraco is installed (more on that in the next section). The content of that xml file is as follows:

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <PropertyGroup> <WebPublishMethod>FileSystem</WebPublishMethod> <ExcludeApp_Data>True</ExcludeApp_Data> <publishUrl>$(PublishOutDir)</publishUrl> <DeleteExistingFiles>False</DeleteExistingFiles> </PropertyGroup> </Project>

This is what the Build solution configuration looks like:

You will need to create the two variables and set their values:

BuildConfiguration

BuildPlatform

Note I have also created the GitPassword variable so that there is one level of obfuscation at least (talk to the hand).

The Test Assemblies step is optional and only necessary if you have and want to run tests from the Visual Studio solution that is being built, but that’s a topic for a different article. Finally, the Deploy task needs to be configured to deploy to the Umbraco Cloud Project’s deployment repo.

The Clone Url (aka deployment repository) is the git repository url for either Development or Live (depending on the type of Project you created). Username and Password are the credentials you use to clone the repository.

The Source Path is where the build output is published to and the Destination Path is where this Deploy task will clone the Umbraco Cloud git repository to. This task will then handle copying the build output to the git repository, commit the changed files, and finally push it to Umbraco Cloud. It presents a relatively safe deployment approach as merge conflicts will show up at this point in the process and the deploy will not continue so that you can address the conflicts.

Configuring the Visual Studio Project

With the Build and Deploy task configured, we’ll create a Visual Studio solution with a Web Application and install the UmbracoCms using nuget – this is what will be deployed to the Umbraco Cloud Project. This is a departure from the approach used in the previous article and what is recommended by the official Umbraco Cloud documentation. Follow along and I’ll get you there.

In Visual Studio create a new and empty Web Application. Install the following nuget packages:

Install-Package UmbracoCms

Install-Package UmbracoForms

The package versions will correspond to the version of Umbraco and Forms that your Umbraco Cloud Project is using. Umbraco Deploy is currently not available as a nuget package, so you will need to download the release from

Download the zip with the latest version called Umbraco.Deploy.vX.XX.X.zip. Unzip and copy the files to the root of the Web Application where Umbraco was installed (it's a good idea to copy the assemblies to a /lib/ folder for reference in the Web Application project).

We then copy some dependencies and settings from the Umbraco Cloud git repository - clone the repository to your local machine if you haven't already done so. From the cloned repository you’ll copy the following files to your Web Application project:

/Config/UmbracoDeploy.config (contains settings for the environments/workspaces in your Project)

(contains settings for the environments/workspaces in your Project) /Config/Dashboard.config (copy the <tab caption="Your workspace">... section)

(copy the section) /App_Plugins/UmbracoLicenses/umbracoForms.lic (to ensure that Forms works)

(to ensure that Forms works) /data/backoffice/* (your backoffice users from Umbraco Cloud)

(your backoffice users from Umbraco Cloud) /data/Revision/* (schema from your Umbraco Cloud site)

FYI the /data/* folder doesn't need to be included in a Project in VS, as long as it is committed to your git repository it will be deployed to Umbraco Cloud as part of the build and deploy task)

(schema from your Umbraco Cloud site) FYI the folder doesn't need to be included in a Project in VS, as long as it is committed to your git repository it will be deployed to Umbraco Cloud as part of the build and deploy task) .gitignore file (which is set to include/exclude the correct files)

Note, you may need to git add some files, i.e., folder level web.config if they are excluded by default)

Add or update the following AppSettings in web.config (the version should of course correspond to the one installed):

<add key="umbracoConfigurationStatus" value="7.10.4" />

<add key="UmbracoLicensesDirectory" value="~/App_Plugins/UmbracoLicenses/" />

<add key="umbracoVersionCheckPeriod" value="0" />

<add key="umbracoDisableElectionForSingleServer" value="true" />

<add key="Umbraco.Deploy.ApiKey" value="<the key from your cloned site>" />

Set the connection string for umbracoDbDSN to:

<add name="umbracoDbDSN" connectionString="Data Source=|DataDirectory|\Umbraco.sdf" providerName="System.Data.SqlServerCe.4.0" />

Now run from Visual Studio. Umbraco will create a LocalDb database and install the Umbraco database schema on startup. And with that you should be up and running locally and ready to write some code.

With the the configuration complete you commit the solution to your git repository and push to GitHub, Bitbucket, Gitlab, VSTS, or whatever flavor of git hosting you use. In the VSTS Build definition you configure this repository in the Get Source task and this will in turn be used to deploy your changes to Umbraco Cloud. The Get Source step will start the build and deploy process when a commit is made the specified branch in the configured git repository.

Wrap Up

In spite of the numerous steps to get the initial setup completed, I’ve found the actual usage of this approach to be very efficient. With the single drawback of needing to accommodate upgrades that have been applied to the Umbraco Cloud Project, I have experienced virtually none of the usual CD issues related to merge conflicts and file versions.

As with the previous article I have placed the supporting code, scripts, and documentation in a public repo for your use and comment https://bitbucket.org/proworks/clouddeploy. Most of the assets you’ll need to configure this CD process can be found at the VSTS Deploy Task repo maintained by Umbraco. As always, comments are welcome and pull requests are gold.

Happy deployments!