Azure Site Extensions

Overview

When you have an Azure Web Site, an IIS applicationhost.config gets generated by Azure for your site. In some scenarios, it can be interesting to tweak how this file is generated. Site Extensions provide a powerful way to do this.

Site Extensions are either pre-installed by Azure (Kudu and Monaco are examples of this), or are installed by the user as part of the site files.

Generally, site extensions can modify applicationhost.config in arbitrary ways by applying transforms to it. Some common usage:

1. Adding new applications to the 'scm' site: the Kudu service runs at the root of the scm site, but you can add sub-applications. e.g. /foo on the scm endpoint can be an unrelated app. The advantage of running under the scm endpoint is that it is protected by authentication, making it a great place to run admin tools of all kind.
2. Adding new applications (and vdirs) to the main site. Note that there is a simpler way to do this via the Azure Portal, so using Site Extensions this way is less common.
3. Arbitrary other changes: e.g. tweak the <fastCgi>, <httpCompression/> or <httpModules/> sections, etc...

All pre-installed Site Extensions are under d:\Program Files (x86)\SiteExtensions. e.g.

d:\Program Files (x86)
    SiteExtensions
        Kudu
            extension.xml
            1.24.12345
                applicationHost.xdt
                kudu bits...
            1.24.34567-preview
                applicationHost.xdt
                kudu bits...

extension.xml has the following format:

<extension>
    <version>disabled|latest|beta|1.2.3456</version>
</extension>

The extension.xml indicates what version is used by default. Each site can override the version by specifying <extension>_EXTENSION_VERSION in the AppSettings (e.g. from the Azure Portal). For above example, we have 2 versions of Kudu in different semver folders. The default version setting is latest which means using the latest version excluding preview/beta (in this case, 1.24.12345). However, if you want to try beta or preview version, you may set KUDU_EXTENSION_VERSION to beta and it will look for latest including such. Other available version values include disabled if you want to disable this extension entirely, as well as specific semver if you only want to use specific version.

ApplicationHost Config Transformation

You may wonder how Kudu or other extensions gets setup in the SCM site. The key is the applicationHost.xdt (notice one exists for each versioned folders). The Xml Document Transform file is used to transform the actual applicationHost.config for the site. For instance, a simple site extension applicationHost.xdt could just add a /somepath IIS application under the SCM site.

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.applicationHost>
    <sites>
      <site name="%XDT_SCMSITENAME%" xdt:Locator="Match(name)">
        <application path="/somepath" xdt:Locator="Match(path)" xdt:Transform="Remove" />
        <application path="/somepath" applicationPool="%XDT_APPPOOLNAME%" xdt:Transform="Insert">
          <virtualDirectory path="/" physicalPath="%XDT_EXTENSIONPATH%" />
        </application>
      </site>
    </sites>
  </system.applicationHost>
</configuration>

There are a set of environment variables passed to the XDT to assist in locating the appropriate elements and set the proper property.

• XDT_SITENAME is the current site name
• XDT_SCMSITENAME is the current scm site name
• XDT_APPPOOLNAME is the application pool name
• XDT_EXTENSIONPATH is the version specific extension physical path
• HOME is the site root path

Private Extensions

The site owner can overwrite the existing site extensions with their own implementations or introduce a totally new set of site extensions altogether.

The first step to use this is to set WEBSITE_PRIVATE_EXTENSIONS=1 in the site AppSettings.

Important note: Site Extensions only get applied after the site is restarted. Initially, setting WEBSITE_PRIVATE_EXTENSIONS=1 will restart the site, but if you later add/remove extensions, you will need to manually restart the site from the portal. However, if you modify existing extensions without changing the applicationHost.xdt, no manual restart is needed.

There are two flavors of Private site extensions: 'named' and 'top level'.

Named private extensions

These work the same way as the 'pre-installed' extensions discussed above, except they're brought in by the site owner.

Here is a complete simple extension sample.

All you need to do is upload the extension bits into a SiteExtensions folder. Below examples illustrate overriding the Kudu extension as well as introducing a new Foo extension. Note that unlike pre-installed extensions, these are not in versioned folders.

    /site
    /LogFiles
    /SiteExtensions
        /Kudu
            applicationHost.xdt
            kudu bits...
        /Foo
            applicationHost.xdt
            foo bits...

Top level private extension

There can be only one such extension for a given site, and it consists of a single applicationHost.xdt file living in the site folder. It is typically used to make general tweaks to your site's ApplicationHost.config.

    /site
        applicationHost.xdt
        wwwroot
    /LogFiles

Example: this applicationHost.xdt adds a mime type to <httpCompression> section:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.webServer>
    <httpCompression>
      <dynamicTypes>
        <add mimeType="application/foo" enabled="true" xdt:Transform="Insert" />
      </dynamicTypes>
    </httpCompression>
  </system.webServer>
</configuration>

Debugging private Extensions

Finding your applicationhost.config

Before trying to apply any transform, you may want to see what the applicationhost.config looks like. Likewise, after applying a transform, you'll want to look at applicationhost.config to make sure it looks ok.

Here is one way to do it (we should try to make this easier in the future):

• Go to the Kudu Console
• Type md MyConfig to create a temporary folder
• Type copy %TMP%\..\config\app*.config MyConfig to copy applicationhost.config into your new folder
• Refresh the console so the MyConfig folder shows up, and click on it
• Click the 1st button next to applicationhost.config to download it, or the second button to view it.

Finding the log of what happened during the transform

If you look under /LogFiles/Transform you should see a log that gives info about what happened during the transforms. This can be very useful when errors happen.

Disabling the private extension transform

If you run into problems and hose your site, all you have to do is set WEBSITE_PRIVATE_EXTENSIONS=0 (or remove it) in the site AppSettings, and none of your XDT will be applied.