Create Virtual Applications and Directories in your Azure Web App using ARM templates

When I start on a project that uses Azure resources, one of the first things I do is build the infrastructure and automate the deployment using VSTS or TFS. The definition of the infrastructure is defined using ARM templates.
When you search online you will find plenty of examples on how to create and use ARM templates. But when you move beyond the basics, you’ll find out the documentation is lacking.

In this post, I’ll explain how you can extend Azure Web Apps with Virtual Applications and Virtual Directories using ARM templates.

I will not be covering on reasons why you would want to use Virtual Applications or Directories. If you’re interested in more background on these, you can read Understanding Sites, Applications, and Virtual Directories on IIS 7.

At the end of the article, you will find the link to the source code.

The Web App definition

We start with a basic site template, for brevity I skipped the app service definition.
The resources property is an empty collection by default.

{
  "type": "Microsoft.Web/sites",
  "kind": "app",
  "name": "LoremIpsumWebApp",
  "apiVersion": "2015-08-01",
  "location": "[resourceGroup().location]",
  "resources": [],
  "dependsOn": [
    "[resourceId('Microsoft.Web/serverfarms', 'LoremIpsumAppService')]"
  ]
}

Adding the Configuration resource

Configuration of the Web App properties is done with a resource with the type of Microsoft.Web/sites/config.

The name of the resource starts with the name of the parent Web App extended with /web.

In the property properties, you can configure several configuration properties like Virtual Applications, enabling Always On or disabling PHP.

A Web App always contains a root application.

{
  "type": "Microsoft.Web/sites/config",
  "name": "LoremIpsumWebApp/web",
  "apiVersion": "2015-08-01",
  "dependsOn": [
    "[resourceId('Microsoft.Web/sites', 'LoremIpsumWebApp')]"
  ],
  "properties": {
    "phpVersion": "",
    "alwaysOn": "true",
    "virtualApplications": [
      {
        "virtualPath": "/",
        "physicalPath": "site\\wwwroot",
        "virtualDirectories": null
      }
    ]
  }
}

We add the new config resource as a child resource to the Web App:

{
  "type": "Microsoft.Web/sites",
  ...
  "resources": [
    {
      "type": "Microsoft.Web/sites/config",
      ...
    }
  ],
  ...
}

Other properties trimmed for brevity.

Adding Virtual Applications

We can add a Virtual Application by adding it to the virtualApplications array.
There are two required properties:

• The virtualPath is the relative path to the root URL of the website.
• The physicalPath is the (relative) path on disk where the files for this application are stored.

{
  "virtualPath": "/DolorSitAmet",
  "physicalPath": "site\\dolor-sit-amet",
  "virtualDirectories": null
}

Adding Virtual Directories

Virtual Directories are always a part of a Virtual Application.

A Virtual Directory has the same two required properties that are needed for a Virtual Application: virtualPath and physicalPath.

{
  "virtualPath": "/Images",
  "physicalPath": "site\\path-to\\images"
}

This object is added to the Virtual Application:

{
  "virtualPath": "/DolorSitAmet",
  "physicalPath": "site\\dolor-sit-amet",
  "virtualDirectories": [
    {
      "virtualPath": "/Images",
      "physicalPath": "site\\path-to\\images"
    }
  ]
}

Now you can deploy the ARM template to your Azure Resource Group and then configure a Web Deploy to your brand-new Virtual Application!

Source code

I have created a GitHub Gist with a full working deployment template sample for reference.

Related posts:

ARM Template User-defined Functions: Build a Storage Account Connection String Manage Azure AD applications from an Azure DevOps Pipeline “Missing” Azure APIs when adding permissions to an Azure AD app