Document Details

For more information, see [az webapp deployment slot swap](/cli/azure/webapp/deployment/slot#az-webapp-deployment-slot-swap).

# [Azure PowerShell](#tab/powershell)

To swap a slot into production with preview, run the following cmdlet in an Azure PowerShell terminal:

To complete the swap, run the following cmdlet:

For more information, see [az webapp deployment slot auto-swap](/cli/azure/webapp/deployment/slot#az-webapp-deployment-slot-auto-swap).

# [Azure PowerShell](#tab/powershell)

Run the following command in an Azure PowerShell terminal:

For more information, see [az monitor activity-log list](/cli/azure/monitor/activity-log#az-monitor-activity-log-list).

# [Azure PowerShell](#tab/powershell)

Run the following Azure PowerShell command:

For more information, see [Get-AzLog](/powershell/module/az.monitor/get-azlog).

-----

## Route production traffic automatically

By default, all client requests to the app's production URL are routed to the production slot. You can route a portion of the traffic to another slot. This feature is useful if you need user feedback for a new update but you're not ready to release it to production.

# [Azure portal](#tab/portal)

1. Go to your web app's resource page and select **Deployment** > **Deployment slots**.

1. In the **Traffic %** column of the slot that you want to route to, specify a percentage (between 0 and 100) to represent the amount of total traffic that you want to route. Then select **Save**.

   :::image type="content" source="media/web-sites-staged-publishing/route-traffic-to-slot.png" alt-text="Screenshot that shows portal selections for routing a percentage of request traffic to a deployment slot." lightbox="media/web-sites-staged-publishing/route-traffic-to-slot.png":::

After you save the setting, the specified percentage of clients is randomly routed to the nonproduction slot.

# [Azure CLI](#tab/cli)

To add a routing rule on a slot and transfer 15% of production traffic to it, run the following command:

For more information, see [az webapp traffic-routing set](/cli/azure/webapp/traffic-routing#az-webapp-traffic-routing-set).

# [Azure PowerShell](#tab/powershell)

To add a routing rule on a slot and transfer 15% of production traffic to it, run the following command:

For more information, see [az webapp deployment slot delete](/cli/azure/webapp/deployment/slot#az-webapp-deployment-slot-delete).

# [Azure PowerShell](#tab/powershell)

Run the following cmdlet in an Azure PowerShell terminal:

For more information, see [Remove-AzWebAppSlot](/powershell/module/az.websites/remove-azwebappslot).

-----

## Automate with Resource Manager templates

[Azure Resource Manager templates](../azure-resource-manager/templates/overview.md) are declarative JSON files for automating the deployment and configuration of Azure resources. To swap slots by using Resource Manager templates, you set two properties on the `Microsoft.Web/sites/slots` and `Microsoft.Web/sites` resources:

- `buildVersion`: A string property that represents the current version of the app deployed in the slot. For example: `v1`, `1.0.0.1`, or `2019-09-20T11:53:25.2887393-07:00`.
- `targetBuildVersion`: A string property that specifies what `buildVersion` value the slot should have. If the `targetBuildVersion` value doesn't equal the current `buildVersion` value, it triggers the swap operation by finding the slot with the specified `buildVersion` value.

### Example Resource Manager template

The following Resource Manager template swaps two slots by updating the `buildVersion` value of the `staging` slot and setting the `targetBuildVersion` value on the production slot. You must have a slot called `staging`.

This Resource Manager template is idempotent. You can run it repeatedly and produce the same state of the slots. Without any change to the template, subsequent runs of the same template don't trigger any slot swap because the slots are already in the desired state.

## Troubleshoot swaps

If any error occurs during a [slot swap](#AboutConfiguration), the error appears in `D:\home\LogFiles\eventlog.xml`. It's also logged in the application-specific error log.

Here are some common swap errors:

- An HTTP request to the application root is timed. The swap operation waits for 90 seconds for each HTTP request, and it retries up to five times. If all retries are timed out, the swap operation is stopped.

- Local cache initialization might fail when the app content exceeds the local disk quota that's specified for the local cache. For more information, see [Azure App Service local cache overview](overview-local-cache.md).

- During a site update operation, the following error can occur: "The slot cannot be changed because its configuration settings have been prepared for swap." This error can occur if the first phase in a multiple-phase swap finishes but the second phase hasn't happened. It can also occur if a swap failed. There are two ways to resolve this problem:

  - Cancel the swap operation, which resets the site back to the old state.
  - Complete the swap operation, which updates the site to the desired new state.

  To learn how to cancel or complete the swap operation, see [Swap with preview (multiple-phase swap)](#swap-with-preview-multiple-phase-swap) earlier in this article.

- During [custom warm-up](#Warm-up), the HTTP requests are made internally without going through the external URL. They can fail with certain URL rewrite rules in `Web.config`. For example, rules for redirecting domain names or enforcing HTTPS can prevent warm-up requests from reaching the app code. To work around this problem, modify your rewrite rules by adding the following two conditions:

    

For more information, see [az webapp deployment slot create](/cli/azure/webapp/deployment/slot#az-webapp-deployment-slot-create).

# [Azure PowerShell](#tab/powershell)

Run the following cmdlet in an Azure PowerShell terminal:

For more information, see [az webapp deployment slot swap](/cli/azure/webapp/deployment/slot#az-webapp-deployment-slot-swap).

# [Azure PowerShell](#tab/powershell)

Run the following cmdlet in an Azure PowerShell terminal:

To cancel the swap, run the following cmdlet:

For more information, see [Switch-AzWebAppSlot](/powershell/module/az.websites/switch-azwebappslot).

-----

If you have any problems, see [Troubleshoot swaps](#troubleshoot-swaps) later in this article.

<a name="Rollback"></a>

## Roll back a swap

If any errors occur in the target slot (for example, the production slot) after a slot swap, restore the slots to their pre-swap states by swapping the same two slots immediately.

<a name="Auto-Swap"></a>

## Configure auto swap

Auto swap streamlines Azure DevOps scenarios where you want to deploy your app continuously with zero cold starts and zero downtime for customers of the app. When auto swap is enabled from a slot into production, every time you push your code changes to that slot, App Service automatically [swaps the app into production](#swap-operation-steps) after it's warmed up in the source slot.

> [!NOTE]
> Auto swap isn't supported in web apps on Linux and in Web App for Containers.
>
> Before you configure auto swap for the production slot, consider testing it on a nonproduction target slot.

# [Azure portal](#tab/portal)

1. Go to your app's resource page. Select **Deployment** > **Deployment slots**, and then select the desired source slot.

1. On the left menu, select **Settings** > **Configuration** > **General settings**.

1. For **Auto swap enabled**, select **On**. For **Auto swap deployment slot**, select the target slot. Then select **Save** on the command bar.

    :::image type="content" source="media/web-sites-staged-publishing/auto-swap.png" alt-text="Screenshot that shows selections for configuring auto swap into the production slot in the portal.":::

1. Run a code push to the source slot. Auto swap happens after a short time. The update is reflected at your target slot's URL.

# [Azure CLI](#tab/cli)

To configure auto swap into the production slot, run the following command in a terminal:

For more information, see [Set-AzWebAppSlot](/powershell/module/az.websites/set-azwebappslot).

-----

If you have any problems, see [Troubleshoot swaps](#troubleshoot-swaps) later in this article.

<a name="Warm-up"></a>

## Specify custom warm-up

Some apps might require custom warm-up actions before the swap. You can specify these custom actions by using the `applicationInitialization` configuration element in `Web.config`. The [swap operation](#AboutConfiguration) waits for this custom warm-up to finish before swapping with the target slot. Here's a sample `Web.config` fragment:

Get the URL for that deployment slot from the **Deployment slots** page in the Azure portal.

For more information, see [Add-AzWebAppTrafficRouting](/powershell/module/az.websites/add-azwebapptrafficrouting). To update an existing rule, use [Update-AzWebAppTrafficRouting](/powershell/module/az.websites/update-azwebapptrafficrouting).

-----

After a client is automatically routed to a specific slot, it's *pinned* to that slot for one hour or until the cookies are deleted. On the client browser, you can see which slot your session is pinned to by looking at the `x-ms-routing-name` cookie in your HTTP headers. A request that's routed to the staging slot has the cookie `x-ms-routing-name=staging`. A request that's routed to the production slot has the cookie `x-ms-routing-name=self`.

## Route production traffic manually

In addition to automatic traffic routing, App Service can route requests to a specific slot. This option is useful when you want your users to be able to opt in to or opt out of your beta app. To route production traffic manually, you use the `x-ms-routing-name` query parameter.

To let users opt out of your beta app, for example, you can put this link on your webpage: