Creating Azure WebSites Site Extensions

What is Site Extensions

Site extensions are web apps with a metadata file. Hosts with your Azure web apps and can be written with any language Azure web apps support. Site extensions share the same resources with your Azure Web apps, can access to Web Apps file system, Certificate Store, Environment variables, etc..

Who is this for and Why Should I use Site Extensions

Site Extensions for anyone who is trying to extend Azure Web apps capabilities, automate tasks (renew certificates, Minify Resources), add Diagnostic and Monitoring to their Azure Web apps

I use Azure Let’s Encrypt to Automate SSL cert
AppDynamics.WindowsAzure.SiteExtension  to connect to AppDynamics
and 3 private Site Extensions to
Combine all Environment variables per Web App to see what settings are applied.
Log Aggregator
Running Health-checks on demands and in a scheduled interval and Showing them in a dashboard

When Should I create a new Site Extension

Before creating a new site extension, there is already a wide range of extensions available and you can check them from your the Azure portal or Kudu’s extension page. You can just install and use them (Click your web app in Azure portal and select extension on the menu or Go Kudu and click Extension button on the right top corner),
you may see the link to https://www.siteextensions.net/packages but last year Microsoft changed the site extension repository and merged into Nuget and the link is outdated.

As those Extensions haven’t been validated on their behaviors (Extensions uses Nuget Servers as a repository and, you are taking a risk on installing them to your environment as they may have malicious can access everything your web app can access.

How to Create a new Site Extensions

Firstly I am using ASP.NET Core 2.2 but you can write your extension with ASP.NET, ASP.NET Core, Java, Ruby, Node.js, PHP, or Python.

I already created a Github Repo you can clone from https://github.com/mmercan/Creating-Azure-WebSites-Site-Extensions
if you want to follow along run https://github.com/mmercan/Creating-Azure-WebSites-Site-Extensions/blob/master/createWebApp.ps1 in the main folder you want to create your project

Create applicationHost.xdt file in the main folder and copy the XML below.
The path I want to access to the extension is /healthcheck, it will be different for your extension. just change /healthcheck to the path you desire in the save it.

<?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="/healthcheck" xdt:Locator="Match(path)" xdt:Transform="Remove" />
        <application path="/healthcheck" preloadEnabled="%XDT_PRELOADENABLED%" xdt:Transform="Insert">
          <virtualDirectory path="/" physicalPath="%XDT_EXTENSIONPATH%" />
        </application>
      </site>
    </sites>
  </system.applicationHost>
</configuration>

Create a HealthCheck.nuspec file in the main folder and copy the XML below.
if you ever worked with nuspec file this is just regular Nuget package metadata except
<packageType name=”AzureSiteExtension” /> which defined this package as an AzureSiteExtension
if you want to more about package metadata https://docs.microsoft.com/en-us/nuget/reference/nuspec

<?xml version="1.0"?>
<package >
  <metadata>
    <id>healthvheckerv2</id>
    <title>Health Checker V2</title>
    <version>1.0.1</version>
    <authors>Matt Mercan</authors>
    <licenseUrl>http://opensource.org/licenses/Apache-2.0</licenseUrl>
    <projectUrl>https://github.com/mmercan/Creating-Azure-WebSites-Site-Extensions</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>A tool to check the application health</description>
    <iconUrl>https://raw.githubusercontent.com/projectkudu/AzureSiteReplicator/master/AzureSiteReplicator/Content/WebsiteReplicator50x50.png</iconUrl>
    <tags>AzureSiteExtension</tags>
    <packageTypes>
      <packageType name="AzureSiteExtension" />
    </packageTypes>
  </metadata>
  <files>
    <file src="artifacts\**\*.*" target="content" />
  </files>
</package>

Create publish.ps1 file in the main folder and copy the script below.
Publish script simply publish the web app to artifacts folder copies the applicationHost.xdt file to artifacts folder too. it will create a NuGet package from artifacts folder in the root folder and push it to the NuGet feed.
when you open the Azure portal and check the extension on your Azure web app you can see the extension is there now.

$aspnetfolderPath = "extension\HealthCheck"
$scriptpath = $MyInvocation.MyCommand.Path 
$dir = Split-Path $scriptpath 

$aspnetfolder = $dir + "\" + $aspnetfolderPath
$aspnetfolder

Set-Location -Path $aspnetfolder
dotnet publish --output ../../artifacts/ -f netcoreapp2.2 -c Release
Copy-Item "$dir/applicationHost.xdt" ../../artifacts/

Set-Location -Path $dir
./nuget pack -NoPackageAnalysis
$nupkgfilename = @(Get-Childitem -path ./* -Include health* -exclude *.nuspec)[0].Name
"file found : $nupkgfilename"

dotnet nuget push $nupkgfilename -k [Your_Nuget_Key] -s https://api.nuget.org/v3/index.json

Move-Item health*.nupkg ./outputs -Force
Set-Location -Path $dir

What Can we do with the Site Extensions

What we deploy is just an empty MVC application.
We can use Controllers to interact with users or We can use IHostedService for Background tasks or Scheduled Tasks

How to Host it anywhere other than Nuget feeds

in some cases, you don’t want to clutter the NuGet feed and separate our extensions.
just replace your dotnet NuGet push lane with

 dotnet nuget push $nupkgfilename -k [your_myget_key] -s https://www.myget.org/F/[your_user_name]/api/v3/index.json 

and Add SCM_SITEEXTENSIONS_FEED_URL to your Web Apps Configuration and set it to your MyGet (or any other public NuGet) feed

SCM_SITEEXTENSIONS_FEED_URL= https://www.myget.org/F/[your_user_name]/api/v3/index.json