Raygun.AzureAppService.Extension 3.0.14

.NET Raygun APM Azure App Service extension

This directory contains the Azure App Service extension assets and the canonical package builder. The distributable is a NuGet package with package ID Raygun.AzureAppService.Extension and package type AzureSiteExtension. It is installed through the Azure portal extension flow; it is not an application package reference.

The canonical operational documentation is:

• Azure App Service APM extension architecture
• Package and feed publication runbook
• App Service setup and test runbook
• Troubleshooting runbook

Customer installation

1. Open the App Service in the Azure portal.
2. Under Extensions, install .NET Raygun APM.
3. Add an application setting named Raygun_ApiKey with the Raygun application API key.
4. Restart the App Service.
5. Confirm that the RaygunAPM continuous WebJob is running.

The Azure Agent exposes its status endpoint on the sandbox-local management port. It does not initialize the Windows machine-management endpoints or their Local System credential ACL. Azure App Service blocks ownership and ACL changes inside its sandbox, and the extension configures profiling through its XDT transform instead of changing IIS through the Agent. The continuous WebJob returns the Agent process exit code so Kudu reports startup failures instead of showing them as successful runs.

During installation, the operating system assigns an unused ephemeral UDP port for the profiler-to-Agent command stream. The installer writes that same port to the Agent configuration and the application-host XDT. It does not use a fixed Azure application port. Azure runs the profiled application in the main site sandbox and the Agent WebJob in the separate SCM sandbox, so loopback and private-IP unicast cannot connect them. The profiler sends to the Azure-only multicast group 239.100.15.215, and the Agent joins that group on the selected port. Normal Windows and Linux installations remain loopback-only. The XDT also maps the documented Raygun_ApiKey application setting to the profiler without copying the key into the extension package or generated build evidence.

Profiler payloads are installed side-by-side beneath their numeric version. An upgrade must not delete the previous version while the App Service worker can still have that profiler DLL loaded. A repeat install keeps identical profiler files instead of rewriting them, then publishes the new XDT only after the new profiler and WebJobs are complete. Restart the App Service after an upgrade so the worker loads the newly selected version.

See the Raygun Azure App Service documentation for customer configuration and troubleshooting.

Canonical package input

The extension package is a third Windows distribution artifact. It reuses the exact canonical, signed BetaRelease Windows payload. It does not build the Agent or profiler, and it does not sign or modify binaries.

build-package.ps1 accepts the payload root and payload-manifest.json produced by build-windows-installer.ps1. It validates the manifest, source commit, one numeric version, file hashes, and required Authenticode signatures before it packs the extension. The package is then checked by tests/Package.Tests.ps1.

Local output remains outside Git beneath:

src/artifacts/Proton/Raygun.AzureAppService.Extension/
  packages/<version>/<phase>/

The extension content uses an explicit allowlist. These are the only files copied from payload-root:

Agent3/
  RaygunAgent.exe
  appsettings.json
Profiler/
  x64/
    RaygunProfiler.dll
    msvcp140.dll
    vcruntime140.dll
    vcruntime140_1.dll
  x86/
    RaygunProfiler.dll
    msvcp140.dll
    vcruntime140.dll

The package also contains only these extension-owned files beneath content:

README.md
applicationHost.xdt.template
scmApplicationHost.xdt
defaultBlacklist.txt
install.cmd
install.ps1
uninstall.cmd
run.ps1
run-diagnostics-status.ps1
settings.job

Anything else beneath content, or selected from payload-root, is rejected. In particular, the package must not contain the Configuration Utility, InstallerSupport, InstallerBinary, MSI files, payload ZIP files, PDB or RGC files, Debug or ReJIT profiler binaries, build intermediates, credentials, or feed configuration. NuGet's generated package metadata remains outside content.

Version identity

The build accepts one mandatory, three-field numeric Version. That exact value identifies the Agent, profiler, Windows payload, Azure package, extension manifest, evidence, and profiler installation directory. For example, version 3.0.12 produces Raygun.AzureAppService.Extension.3.0.12.nupkg and installs the profiler beneath Raygun\Profiler\3.0.12.

Every accepted build receives a new version. The cancelled 3.0.13 allocation was never published and must not be reused, so the build after 3.0.12 is 3.0.14. The same version must not be rebuilt with different bytes. A later minor release can move to 3.1.0. Do not add a second distribution, package, product, or CI-suffix version.

TeamCity artifact contract

Build - Windows publishes this private TeamCity artifact layout from the same signed payload that produced the MSI:

release/azure-app-service-extension/package/
  Raygun.AzureAppService.Extension.<version>.nupkg
  azure-extension-build-evidence.json
  SHA256SUMS

The evidence records the package ID and type, one version, source commit, input manifest hash, package hash and length, and every allowed packaged file. A consumer must validate the evidence and checksum before it publishes the package.

Publication boundary

The Azure extension does not belong in downloads.raygun.com and is not published by the unified Linux/Windows Deploy - Beta S3 build. Beta feed publication is a separate protected TeamCity operation. It consumes the exact successful Build - Windows package artifact and pushes it to the Azure Artifacts AzureAPM feed:

https://pkgs.dev.azure.com/raygunio/AzureAPMNugetFeed/_packaging/AzureAPM/nuget/v3/index.json

Feed credentials are secure TeamCity parameters. They must not be passed into the package build or stored in source, build evidence, package content, or logs. Building and testing the package does not authorize publication.

Retired paths

Do not recreate the removed root build.ps1 or buildv2.ps1 Azure tasks. Do not use build.cmd, the old nuget.exe pack command, or the former build/Release and build/Debug input layout. Those paths could mix stale or Debug profiler files and did not prove that the package contained the signed Windows release payload.