Azure Web App deployment

Azure Pipelines | TFS 2018 | TFS 2017

Note

Build and release pipelines are called definitions in Microsoft Team Foundation Server (TFS) 2018 and in older versions. Service connections are called service endpoints in TFS 2018 and in older versions.

You can automatically deploy your web app to an Azure App Service web app after every successful build. Before you read this topic, you should understand the type of pipeline that you're creating: designer or YAML.

Note

This guidance applies to Team Foundation Server (TFS) version 2017.3 and later.

Example

If you want some sample code that works with this guidance, import (into Azure Repos or TFS) or fork (into GitHub) this repo:

https://github.com/MicrosoftDocs/pipelines-dotnet-core

Follow the guidance in .NET Core to build the sample code.

The preceding sample code includes an azure-pipelines.yml file at the root of the repository. This file contains code to build, test, and publish the source as an artifact. To learn more about building .NET Core apps, see Build .NET Core projects with Azure Pipelines or Team Foundation Server.

YAML builds are not yet available on TFS.

Azure App Service Deploy task

The simplest way to deploy to an Azure Web App is to use the Azure App Service Deploy (AzureRmWebAppDeployment) task.

Deploy a Web Deploy package (ASP.NET)

To deploy a .zip Web Deploy package (for example, from an ASP.NET web app) to an Azure Web App, add the following snippet to your azure-pipelines.yml file:

- task: AzureRmWebAppDeployment@3
  inputs:
    azureSubscription: '<Azure service connection>'
    WebAppName: '<Name of web app>'
    Package: $(System.ArtifactsDirectory)/**/*.zip

The snippet assumes that the build steps in your YAML file produce the zip archive in the $(System.ArtifactsDirectory) folder on your agent.

For information on Azure service connections, see the following section.

Deploy a Java app

If you're building a Java app, use the following snippet to deploy the web archive (.war):

- task: AzureRmWebAppDeployment@3
  inputs:
    azureSubscription: '<Azure service connection>'
    WebAppName: '<Name of web app>'
    Package: '$(System.DefaultWorkingDirectory)/**/*.war'

The snippet assumes that the build steps in your YAML file produce the .war archive in one of the folders in your source code folder structure; for example, under <project root>/build/libs. If your build steps copy the .war file to $(System.ArtifactsDirectory) instead, change the last line in the snippet to $(System.ArtifactsDirectory)/**/*.war.

For information on Azure service connections, see the following section.

Deploy a JavaScript Node.js app

If you're building a JavaScript Node.js app, you publish the entire contents of your working directory to the web app. The following snippet also generates a Web.config file during deployment and starts the iisnode handler on the Azure Web App:

- task: AzureRmWebAppDeployment@3
  inputs:
    azureSubscription: '<Azure service connections>'
    WebAppName: '<Name of web app>'
    Package: '$(System.DefaultWorkingDirectory)'
    GenerateWebConfig: true
    WebConfigParameters: '-Handler iisnode -NodeStartFile server.js -appType node'

For information on Azure service connections, see the following section.

YAML builds are not yet available on TFS.

Azure service connection

The Azure App Service Deploy task, similar to other built-in Azure tasks, requires an Azure service connection as an input. The Azure service connection stores the credentials to connect from Azure Pipelines or TFS to Azure.

You must supply an Azure service connection to the AzureRmWebAppDeployment task. The Azure service connection stores the credentials to connect from Azure Pipelines to Azure. See Create an Azure service connection.

YAML builds are not yet available on TFS.

Deploy to a virtual application

By default, your deployment happens to the root application in the Azure Web App. You can deploy to a specific virtual application by using the following:

- task: AzureRmWebAppDeployment@3
  inputs:
    VirtualApplication: '<name of virtual application>'

YAML builds are not yet available on TFS.

Deploy to a slot

You can configure the Azure Web App to have multiple slots. Slots allow you to safely deploy your app and test it before making it available to your customers.

The following example shows how to deploy to a staging slot, and then swap to a production slot:

- task: AzureRmWebAppDeployment@3
  inputs:
    azureSubscription: '<Azure service connection>'
    WebAppName: '<name of web app>'
    DeployToSlotFlag: true
    ResourceGroupName: '<name of resource group>'
    SlotName: staging

- task: AzureAppServiceManage@0
  inputs:
    azureSubscription: '<Azure service connection>'
    WebAppName: '<name of web app>'
    ResourceGroupName: '<name of resource group>'
    SourceSlot: staging

YAML builds are not yet available on TFS.

Deploy to multiple web apps

You can use jobs in your YAML file to set up a pipeline of deployments. By using jobs, you can control the order of deployment to multiple web apps.

jobs:

- job: buildandtest
  pool:
    vmImage: 'ubuntu-16.04'
  steps:

  # add steps here to build the app

  # the following will publish an artifact called drop
  - task: PublishBuildArtifacts@1

  - task: AzureRmWebAppDeployment@3
    inputs:
      azureSubscription: '<Test stage Azure service connection>'
      WebAppName: '<name of test stage web app>'

- job: prod
  pool:
    vmImage: 'ubuntu-16.04'
  dependsOn: buildandtest
  condition: succeeded()
  steps:

  # step to download the artifacts from the previous job
  - task: DownloadBuildArtifacts@0
    inputs:
      artifactName: drop

  - task: AzureRmWebAppDeployment@3
    inputs:
      azureSubscription: '<Prod stage Azure service connection>'
      WebAppName: '<name of prod stage web app>'

YAML builds are not yet available on TFS.

Configuration changes

You might want to apply a specific configuration for your web app target before deploying to it. This is particularly useful when you deploy the same build to multiple web apps in a pipeline. For example, if your Web.config file contains a connection string named connectionString, you can change its value before deploying to each web app. You can do this either by applying a Web.config transformation or by substituting variables in your Web.config file.

The following snippet shows an example of variable substitution:

jobs:
- job: test
  variables:
    connectionString: <test-stage connection string>
  steps:
  - task: AzureRmWebAppDeployment@3
    inputs:
      azureSubscription: '<Test stage Azure service connection>'
      WebAppName: '<name of test stage web app>'
      enableXmlVariableSubstitution: true

- job: prod
  dependsOn: test
  variables:
    connectionString: <prod-stage connection string>
  steps:
  - task: AzureRmWebAppDeployment@3
    inputs:
      azureSubscription: '<Prod stage Azure service connection>'
      WebAppName: '<name of prod stage web app>'
      enableXmlVariableSubstitution: true

YAML builds are not yet available on TFS.

Deploying conditionally

You can choose to deploy only certain builds to your Azure Web App.

To do this in YAML, you can use one of these techniques:

  • Isolate the deployment steps into a separate job, and add a condition to that job.
  • Add a condition to the step.

The following example shows how to use step conditions to deploy only builds that originate from the master branch:

- task: AzureRmWebAppDeployment@3
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master'))
  inputs:
    azureSubscription: '<Azure service connection>'
    WebAppName: '<Name of web app>'

To learn more about conditions, see Specify conditions.

YAML builds are not yet available on TFS.

Deploy to an Azure Government cloud or to Azure Stack

Create a suitable service connection:

Deployment mechanisms

The preceding examples rely on the built-in Azure App Service Deploy task, which provides simplified integration with Azure.

If you use a Windows agent, this task uses Web Deploy technology to interact with the Azure Web App. Web Deploy provides several convenient deployment options, such as renaming locked files and excluding files from the App_Data folder during deployment.

If you use the Linux agent, the task relies on the Kudu REST APIs.

The Azure App Service Manage task is another task that's useful for deployment. You can use this task to start, stop, or restart the web app before or after deployment. You can also use this task to swap slots, install site extensions, or enable monitoring of the web app.

If the built-in tasks don't meet your needs, you can use other methods to script your deployment. View the YAML snippets in each of the following tasks for some examples: