Document Details
Deploy Staging Slots
❌
This page contains Windows bias
About This Page
This page is part of the Azure documentation. It contains code examples and configuration instructions for working with Azure services.
Bias Analysis
Bias Types:
⚠️
windows_first
⚠️
powershell_heavy
⚠️
windows_tools
⚠️
missing_linux_example
Summary:
The documentation demonstrates a Windows bias in several ways: PowerShell examples are provided alongside Azure CLI and portal instructions, with equal prominence, but there is no mention of Linux-native scripting or shell environments (e.g., Bash). The use of Windows-specific tools and configuration files, such as Web.config and applicationInitialization, is presented without Linux or cross-platform alternatives. Troubleshooting and advanced configuration sections reference Windows file paths (D:\home\LogFiles\eventlog.xml) and IIS-specific features, which may not apply to Linux-based App Service environments. Additionally, the auto swap feature is noted as unsupported on Linux, but no Linux-specific guidance or alternatives are offered.
Recommendations:
- Add explicit Bash or Linux shell examples where scripting is demonstrated, especially alongside Azure CLI commands.
- Clearly indicate when features (such as auto swap) are not supported on Linux, and provide alternative workflows or mitigations for Linux users.
- When referencing configuration files like Web.config or IIS features, include parallel instructions for Linux-based apps (e.g., using app settings, startup scripts, or other Linux-appropriate mechanisms).
- In troubleshooting sections, mention log file locations and diagnostic steps for both Windows and Linux App Service environments.
- Review all examples and ensure that Linux users are not left without actionable guidance, especially where Windows/IIS-specific features are discussed.
Create pull request
Scan History
| Date | Scan ID | Status | Bias Status |
|---|---|---|---|
| 2025-09-14 00:00 | #111 | completed | ✅ Clean |
| 2025-09-13 00:00 | #110 | completed | ✅ Clean |
| 2025-09-12 00:00 | #109 | completed | ✅ Clean |
| 2025-09-11 00:00 | #108 | completed | ✅ Clean |
| 2025-09-10 00:00 | #107 | completed | ✅ Clean |
| 2025-09-09 00:00 | #106 | completed | ✅ Clean |
| 2025-09-08 00:00 | #105 | completed | ❌ Biased |
| 2025-09-07 00:00 | #104 | completed | ❌ Biased |
| 2025-09-06 00:00 | #103 | completed | ❌ Biased |
| 2025-08-15 00:01 | #81 | in_progress | ❌ Biased |
| 2025-07-13 21:37 | #48 | completed | ✅ Clean |
| 2025-07-13 21:25 | #47 | cancelled | ✅ Clean |
| 2025-07-13 20:48 | #44 | cancelled | ✅ Clean |
| 2025-07-09 13:09 | #3 | cancelled | ✅ Clean |
| 2025-07-08 04:23 | #2 | cancelled | ❌ Biased |
Flagged Code Snippets
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 [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:
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:
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:
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: