Using Web Deploy in Visual Studio Team Services Release Management

This post does not really cover something new, but since I find myself explain this to people now and then, I thought that I’d write a quick post on the subject.

So, we want to create a web deploy package as part of our automated build, and then take this package and deploy it to multiple environments, where each environment can have different configuration settings, using VSTS Release Management. Since we only want to build our package once, we have to apply the environment specific settings at deployment time, which means we will use Web Deploy parameters.

 

Here are the overall steps needed:

  1. – Create a parameters.xml file in your web project
  2. – Create a publish profile for the web deploy package
  3. – Set up a VSTS build creates the web deploy package, and uploads the package to the server
  4. – Create a Release definition in VSTS that consumes the web deploy package
  5. – In each RM environment, replaces the tokens in the SetParameters file

Let’s run through these steps in detail:

Create a parameters.xml file

As you will see later on, a publish profile contains configurable settings for the web site name and any connection strings,that will end up in the *.SetParameters.xml file that is used when at deployment time. But in order for other configuration settings, like appSettings, to end up in this file, you need to define these settings. This is done by creating a file called parameters.xml in the root of your web application.

Tip: A fellow MVP, Richard Fennell,  has created a nifty Visual Studio extension that simplifies the process of creating the parameters.xml file. It will look at your web.config file and the create a parameters.xml file with all the settings that it finds.

image

 

In this case, I have three application settings in the web.config file, so I end up with this parameters.xml file. Note that I have set the defaultvalue attribute for all parameters to __TOKEN__. These are the configuration values that will end up in the MyApp.SetParameters.xml file, together with the web deployment package. We will replaced these values at deployment time, by a task in our release definition.

<parameters> <parameter name="IsDevelopment" description="Description for IsDevelopment" defaultvalue="__ISDEVELOPMENT__" tags=""> <parameterentry kind="XmlFile" scope="\\web.config$" match="/configuration/applicationSettings/MyApp.Properties.Settings/setting[@name='IsDevelopment']/value/text()" /> </parameter> <parameter name="WebApiBaseUrl" description="Description for WebApiBaseUrl" defaultvalue="__WEBAPIBASEURL__" tags=""> <parameterentry kind="XmlFile" scope="\\web.config$" match="/configuration/applicationSettings/MyApp.Properties.Settings/setting[@name='WebApiBaseUrl']/value/text()" /> </parameter> <parameter name="SearchFilterDelta" description="Description for SearchFilterDelta" defaultvalue="__SEARCHFILTERDELTA__" tags=""> <parameterentry kind="XmlFile" scope="\\web.config$" match="/configuration/applicationSettings/MyApp.Properties.Settings/setting[@name='SearchFilterDelta']/value/text()" /> </parameter> </parameters>

Creating a Publish Profile

Now, let’s create a publish profile that define how the web deployment package should be created. Right-click on the web application project and then select Publish. Then select the Custom option:

image

 

Since the publish profile will be used to create a web deployment package, I like to call it CreatePackage (but you are of course free to call it whatever you want)

image

On the Connection tab, select Web Deploy Package as the publish method, then give the generated package a name (including .zip).

As the Web Site name, we enter a tokenized value __WEBSITE__. This token will also end up in the MyApp.SetParameters.xml file.

image

Save the publish profile and commit and push your changes. Now it’s time to create a build definition.

 

Create a Build Definition that generates a web deploy package

I won’t go through all the details of creating a build definition in VSTS, but just focus on the relevant parts for this blog post.

To generate a web deploy package, we need to pass some magic MSBuild parameters as part of the Visual Studio build task. Since we have a publish profile that contains our settings, we need to refer to this file. We also want to specify where the resulting files should be placed.

Enter the following string in the MSBuild Arguments field:

/p:DeployOnBuild=true /p:PublishProfile=CreatePackage /p:PackageLocation=$(build.stagingDirectory)

image

 

DeployOnBuild=true is required to trigger the web deployment publishing process, and the we use the PackageLocation property to specify that the output should be places in the staging directory of the build. This will make it easy to upload the artifacts at the end of the build, like so:

image

 

This will generate an artifact called drop in the build that contains all files needed to deploy this application using MSDeploy:

image

As you can see, we have all the generated web deploy files here. We will use three of them:

MyApp.zip – The web deploy package

MyApp.SetParameters.xml – The parameterization file that contains our tokenized parameters

MyApp.Deploy.cmd – A command file that simplifies running MSDeploy with the correct parameters

 

Creating a Release Definition

Finally, we will create a release definition that deploys this web deploy package to two different environments, let’s call them Test and Prod. In each environment we need to apply the correct configuration values. To do this, we have to replace the token variables in our MyApp.SetParameters.xml file.

There is no out of the box task to do this currently, but there are already several of them in the Visual Studio Marketplace. Here, I will use the Replace Tokens task from Guillaume Rochon, available at https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens. Install it to your Visual Studio Team Services account, and then the task will be available in the build/release task catalog, in the Utility category:

 

image

 

Each environment in the release definition will just contain two tasks, the first one for the token replacement and the other one for deploying the web deploy package. To do this, we just run the MyApp.deploy.cmd file that was generated by the build. Since the parameters have already been set with the correct values, we can just run this without any extra arguments.

image

 

Also, we must specify the values for each variable in the environment. Right click on the environment and the add these variables:

image

 

Tip: Create the Test environment first with all variables and tasks. Once it’s done, use the Clone environment feature to create a Prod environment, and then just replace the configuration values

 

That’s it, now you can run the release and it will deploy your web application with the correct configuration to each environment.

 

image

 

 

 

 

Talking Visual Studio ALM Extensibility at DevSum16

Last year I had a great time speaking at the DevSum conference, the biggest .NET developer conference in Sweden. Back then, I talked about moving your development to the cloud using Visual Studio Team Services. Active Solution, where I work, was a gold partner for this event and in addition to me my colleagues Alan Smith and Peter Örneholm also spoke at the conference. We had a lot of fun in our booth showing the Lego robots running on Raspberry PIs, connected to Azure for movement control and result collection.

This year I had the fortune to be selected again to speak at DevSum16, and this time I will talk about the different options around integration and extensibility of the Visual Studio ALM platform. This means that I will talk about things like Service Hooks, OAuth, REST API and UI extensibility among other things.

 

Here is the session description (http://www.devsum.se/speaker/jakob-ehn/), hope to see you there!

Don’t be locked in – Integrate and Extend the Visual Studio ALM Platform

The days when you used one tool chain for all your development are long gone. Developing modern applications today often requires a variety of tools, both 3rd party tools and services

but also homegrown systems are often used as part of the process. In the new era of Microsoft the term “Open ALM” is key, focusing on trying to build best in breed tools for software development companies, but at the same time make sure that it is open and extensible.

 

In this session we will look at the different options for integrating and extending Visual Studio TFS and Team Services. We will look at:

  • Using Service Hooks to automate workflows with other services such as Trello, GitHub and Jenkins.
  • Utilizing the REST API to automate processes in TFS
  • Extending the Web UI itself with custom extensions, from simple context menus to full-fledged custom pages and hubs. We will also look at how we can publish these extensions
    to the new Visual Studio Marketplace

Publish a GitHub Release from Visual Studio Team Services

The new build system in Team Foundation Server 2015 and Visual Studio Team Services has from the start made it very easy to integrate with GitHub. This integration allows you to create a build in TFS/VSTS that fetches the source code from a GitHub repository. I have blogged about this integration before, at http://blog.ehn.nu/2015/06/building-github-repositories-in-tfs-build-vnext/.

 

Publisinh a GitHubRelease from VSTS

This integration allows you to use GitHub for source code, but use the powerful build system in TFS/VSTS to run your automated builds. But, when maintaining the project at GitHub you often want to publish your releases there as well, with the output from your build.

To make this easy, I have developed a custom build task lets you publish your build artifacts into a release at GitHub.

The task is available over at the new Visual Studio Marketplace, you can find the extension here:
https://marketplace.visualstudio.com/items?itemName=jakobehn.jakobehn-vsts-github-tasks

 

image

To use it, just press the Install button and select the VSTS account where you want to install it. After this, the Publish GitHub Release build task will be available in your build task catalog, in the Deploy category.

image

 

From Team Foundation Server 2015 Update 2, it is possible to install the extensions from the VS Marketplace on premise. To do so, use the Download button and follow the instructions.

 

After adding the build task to a build definition, you need to configure a few parameters:

image

These parameters are:

  • Application Name
    You can use any name here, this is what is sent to the GitHub API in the request header.
  • Token
    Your GitHub Personal Access Token (PAT). For more information about GitHub tokens, please see https://help.github.com/articles/creating-an-access-token-for-command-line-use/

    Repository Name
    The name of the repository where the release should be created

  • Owner
    The GitHub account of the owner of the release
  • Tag Name
  • A unique tag for the release. Often it makes sense to include the build number here
  • Release Name
    The name of the release. Also, including the build number here can make sense
  • Draft
    Enable this to create a draft release
  • Prerelease
    Enable this to create a prerelease

    Assets to upload
    Specified which files that should be included in the GitHub release

 

Hope that you will find this extension useful, if you find bugs or have feature suggestions, please report them on the GitHub site at https://github.com/jakobehn/VSTSGitHubTasks