Create an Azure App Service Virtual Directory with PowerShell

Azure App Service can map a URL path such as /app2 to a physical folder such as sitewwwrootapp2. This virtual application or directory feature is available for Windows App Service apps; it is not the equivalent configuration for Linux apps.

The original tutorial used the retired AzureRM module. Use the current Az PowerShell module and the Get-AzWebApp and Set-AzWebApp cmdlets instead. Microsoft documents the AzureRM-to-Az change in its Azure PowerShell migration guide.

Before you change the path mapping

• Confirm that the App Service app runs on Windows.
• Verify that the physical folder exists in the deployed app.
• Use an Azure account with permission to update the web app.
• Review the existing mappings so you do not unintentionally replace the root application.

1. Install Az PowerShell and sign in

Install-Module Az -Scope CurrentUser
Connect-AzAccount

If Az is already installed, update it according to your organization's PowerShell module policy rather than installing a second unmanaged copy.

2. Define the app and mapping

$ResourceGroupName = 'my-resource-group'
$WebAppName = 'my-web-app'
$VirtualPath = '/app2'
$PhysicalPath = 'sitewwwrootapp2'
$PreloadEnabled = $false

A virtual path should start with /. The physical path is relative to the App Service file root used by the configuration.

3. Retrieve the current web app configuration

$webApp = Get-AzWebApp -ResourceGroupName $ResourceGroupName -Name $WebAppName

Inspect $webApp.SiteConfig.VirtualApplications before making changes:

$webApp.SiteConfig.VirtualApplications | Select-Object VirtualPath, PhysicalPath, PreloadEnabled

4. Add or update the virtual application

The following script updates an existing mapping with the same virtual path; otherwise, it creates a new one. This avoids blindly adding a duplicate entry.

$existing = $webApp.SiteConfig.VirtualApplications | Where-Object { $_.VirtualPath -eq $VirtualPath }

if ($existing) {
  $existing.PhysicalPath = $PhysicalPath
  $existing.PreloadEnabled = $PreloadEnabled
}
else {
  $virtualApp = New-Object Microsoft.Azure.Management.WebSites.Models.VirtualApplication
  $virtualApp.VirtualPath = $VirtualPath
  $virtualApp.PhysicalPath = $PhysicalPath
  $virtualApp.PreloadEnabled = $PreloadEnabled
  $webApp.SiteConfig.VirtualApplications.Add($virtualApp)
}

5. Save and verify the change

Set-AzWebApp $webApp

Retrieve the app again and confirm the mapping:

(Get-AzWebApp -ResourceGroupName $ResourceGroupName -Name $WebAppName).SiteConfig.VirtualApplications | Select-Object VirtualPath, PhysicalPath, PreloadEnabled

Then test the mapped URL in a non-production slot or maintenance window. A correct path mapping does not deploy the application's files; the target folder and its content must already exist.

Portal alternative

In the Azure portal, open the Windows App Service app, go to Settings > Configuration > Path mappings, and add a virtual application or directory. Microsoft maintains the current instructions in Configure an App Service app.

Common problems

• The option is missing: Check whether the app is running on Linux; this path-mapping feature is Windows-only.
• The mapped URL returns 404: Verify the virtual path, deployed folder, routing, and default document.
• Existing routes stop working: Review whether the root / mapping was changed accidentally.
• The script uses Get-AzureRmWebApp: Migrate it to Az rather than building new automation on the deprecated AzureRM module.