AurorisNet.Umbraco.ApplicationVirtualPathFix
18.3.2.1
dotnet add package AurorisNet.Umbraco.ApplicationVirtualPathFix --version 18.3.2.1
NuGet\Install-Package AurorisNet.Umbraco.ApplicationVirtualPathFix -Version 18.3.2.1
<PackageReference Include="AurorisNet.Umbraco.ApplicationVirtualPathFix" Version="18.3.2.1" />
<PackageVersion Include="AurorisNet.Umbraco.ApplicationVirtualPathFix" Version="18.3.2.1" />
<PackageReference Include="AurorisNet.Umbraco.ApplicationVirtualPathFix" />
paket add AurorisNet.Umbraco.ApplicationVirtualPathFix --version 18.3.2.1
#r "nuget: AurorisNet.Umbraco.ApplicationVirtualPathFix, 18.3.2.1"
#:package AurorisNet.Umbraco.ApplicationVirtualPathFix@18.3.2.1
#addin nuget:?package=AurorisNet.Umbraco.ApplicationVirtualPathFix&version=18.3.2.1
#tool nuget:?package=AurorisNet.Umbraco.ApplicationVirtualPathFix&version=18.3.2.1
Umbraco Application Virtual Path Fix
AurorisNet.Umbraco.ApplicationVirtualPathFix lets an Umbraco 17 or 18 site run under an
application virtual path, such as an IIS application at /SomeTestPath.
Umbraco builds many backoffice, media, preview and sign-in URLs from the host root. The
package adds the configured path to each of them, so the backoffice at
/SomeTestPath/umbraco signs in, loads its scripts and stylesheets, shows media and
previews, and renews sessions under the path. It does this in three ways:
- It patches Umbraco's backoffice scripts and stylesheets in memory at startup and serves the patched copies at the original URLs.
- It adds middleware that moves the path into the request's path base, and restores the path for the Umbraco features that expect it there.
- It wraps Umbraco's import map, media URL and sign-in link services, so the URLs they build include the path.
A site at the root gains one fix: a fresh browser starts sign-in directly, and Umbraco's initial token refresh runs only when a session may exist. What the package fixes lists every URL the package corrects.
Install
Reference the package with your site's Umbraco major version, so NuGet installs the newest package for it:
<PackageReference Include="AurorisNet.Umbraco.ApplicationVirtualPathFix" Version="18.*" />On Umbraco 17, use
Version="17.*". With central package management, a floating version needsCentralPackageFloatingVersionsEnabledset totrue; otherwise give an exact package version.Set the site's application path in
appsettings.json. For an IIS child application, use the application's path.{ "Umbraco": { "CMS": { "Hosting": { "ApplicationVirtualPath": "/SomeTestPath" } } } }Start the site and open
/SomeTestPath/umbraco.
The package registers itself through an Umbraco composer, so the site needs no code. The Application virtual path health check confirms that requests arrive under the path and that every patch applied.
Hosting requirements
- Requests reach the site with the prefix. Either the request path starts with the
prefix, which the package moves into the path base, or the host has set the path base
already: IIS for a child application, or
UseForwardedHeaderswithX-Forwarded-Prefixbehind a proxy that strips the prefix. Route only the prefix to the site, because Kestrel also answers requests outside it. - Absolute URLs built on the server, such as the links in emails, start from Umbraco's
application URL. Behind a proxy that changes the host or scheme, apply
X-Forwarded-HostandX-Forwarded-ProtowithUseForwardedHeadersbeforeUseUmbraco(), or setUmbraco:CMS:WebRouting:UmbracoApplicationUrl. - Response compression. Register
UseResponseCompression()beforeUseUmbraco(). Patched files compress like any other file. - Several Umbraco sites on one host need different cookie names, because a browser sends
a host's
Path=/cookies to every application on it. Give each site its ownUmbraco:CMS:Security:BackOfficeTokenCookie:SiteNameandUmbraco:CMS:Security:AuthCookieName. - Third-party backoffice plugins. The package adds the prefix to their import map entries. Each plugin builds its other URLs itself.
- Restart the site after updating Umbraco. The package patches Umbraco's backoffice files in memory at startup and leaves the files on disk unchanged.
When the site's own startup code needs the path, VirtualPathHosting.Prefix(builder.Configuration)
returns it with one leading slash, such as /SomeTestPath, or null for a site at the root.
The browser tests cover five set-ups: HTTPS under a nested path with media outside
wwwroot, a path base set by the host as IIS does, a reverse proxy that forwards the prefix,
the same proxy at the root, and basic authentication.
Health check
Settings → Health Check → Configuration → Application virtual path reports each part of the fix, and the startup log carries the same warnings and errors. At the root, the check reports the Umbraco release and notes that only the session restore fix applies.
| Check | Message when something is wrong | What to do |
|---|---|---|
| Umbraco release | The package supports Umbraco list, but the site runs Umbraco release. | Install a package version that lists the site's release. |
| Path base | The site is configured for /SomeTestPath, but this request arrived with the path base "". |
Send requests with the prefix in their path, or set the path base through IIS or X-Forwarded-Prefix. |
| Patched files | Expected one Umbraco file for path, found n, so it is not patched. | The site's Umbraco files differ from the tested releases. Install a package version that lists the site's release. |
| Patched files | Umbraco's file reason, so that part of the fix is not applied. | As above. |
| Patched files | The backoffice files have not been patched yet. | The files are patched when Umbraco's pipeline starts. Run the check again once the site has started. |
| Requests outside the path | n requests have reached the site outside /SomeTestPath since it started, most recently path. |
Route only the prefix to the site. Load balancer probes at the root also count. |
In the browser, a missing fix shows in the developer tools' Network tab as a request without
the prefix, such as /umbraco/management/api/v1/... in place of
/SomeTestPath/umbraco/management/api/v1/.... Find the URL's row in
What the package fixes,
and report it in the
issue tracker
with the site's Umbraco release and package version.
Supported versions
| Umbraco | Supported releases | Runtime |
|---|---|---|
| 18 | 18.0.0 to 18.3.2 | .NET 10 |
| 17 | 17.5.0 to 17.8.2 | .NET 10 |
Every release in these ranges is tested.
Directory.Build.props
lists them in UmbracoReleases, and the package's Umbraco dependency spans the oldest to the
newest. Upgrade the package when you upgrade Umbraco.
Outside that range, restore stops with error NU1107. A site that references
Umbraco.Cms.Web.Common or Umbraco.Cms.StaticAssets directly gets warning NU1608
instead. On a release the list leaves out, including a prerelease, the startup log and the
health check warn, and the startup log names each patch that no longer applies.
Documentation
| Guide | Covers |
|---|---|
| What the package fixes | Each URL that Umbraco builds without the path, the result with the package, and how the fixes apply. |
Developing
Building needs the .NET 10 SDK, which global.json selects, and PowerShell 7 for the
scripts. On Windows, clone to a short path unless long paths are enabled: the test matrix
builds Playwright's files about 200 characters below the repository root.
dotnet build tests/AurorisNet.Umbraco.ApplicationVirtualPathFix.Tests
# The quick tests, on the newest supported Umbraco release
dotnet test --project tests/AurorisNet.Umbraco.ApplicationVirtualPathFix.Tests --no-build -- --filter-not-class '*SiteEndToEndTests'
# Chromium for the browser cases: install once after the build, and again after a Playwright update
pwsh tests/AurorisNet.Umbraco.ApplicationVirtualPathFix.Tests/bin/Debug/net10.0/playwright.ps1 install chromium
# The browser cases, on the newest supported Umbraco release
dotnet test --project tests/AurorisNet.Umbraco.ApplicationVirtualPathFix.Tests --no-build -- --filter-class '*SiteEndToEndTests'
# The full matrix: the quick tests, then the browser cases, on every release in UmbracoReleases
pwsh tests/Test-UmbracoReleases.ps1
pwsh tests/Test-UmbracoReleases.ps1 -Browser
# Chosen releases
pwsh tests/Test-UmbracoReleases.ps1 -Releases 17.5.3,18.3.1
pwsh tests/Test-UmbracoReleases.ps1 -Releases 17.5.3,18.3.1 -Browser
# Add an Umbraco release by hand, with AurorisNet.Build cloned beside this repository
pwsh ../AurorisNet.Build/scripts/Add-UmbracoRelease.ps1 -Releases 18.3.2
# A local package, numbered with count 0
dotnet pack src/AurorisNet.Umbraco.ApplicationVirtualPathFix.csproj -c Release -o artifacts/packages
The quick tests check each patch against Umbraco's files and source maps, and test the middleware, file provider, Tag Helper and health check. The browser cases drive new Umbraco sites with the starter kit through Chromium.
Test-UmbracoReleases.ps1 builds each release into artifacts/umbraco-releases/<release>,
prints one line per release and exits with 1 when a release fails. The full matrix runs on a
developer's machine. GitHub tests the newest supported release, and each new Umbraco release
when it appears.
Add-UmbracoRelease.ps1 adds the release to UmbracoReleases, moves UmbracoMaximumVersion
and UmbracoVersion to the newest listed release, and rewrites the ranges in the
Supported versions table.
When you run the tests:
dotnet buildanddotnet testuseUmbracoVersioninDirectory.Build.props. Add-p:UmbracoVersion=17.5.3to build against another listed release. Outside a Git checkout, also add-p:SourceTimestamp=2026-11-14T12:00:00Z: the build reads the commit time from Git, and patched files use it as theirLast-Modifiedtime.AVPF_E2E_CASEselects browser cases:full,iis,proxy,proxy-rootandbasic-auth, separated by commas. Umbraco 17 keeps the first site's services for the whole process, so run one case per process on it, asTest-UmbracoReleases.ps1does.- Each browser case writes its output, Playwright trace and site log to
e2e-artifacts/<case>/<run>in the test project's output folder.AVPF_KEEP_TEST_SITE=1keeps each test site's folder. - After changing a patch entry, test the releases from its
Fromup to itsBefore. After changing other package code, run the full matrix. - CI and the Release workflow treat build warnings as errors.
Fix a release that fails
A new Umbraco release that fails the tests gets an issue titled
Umbraco <release> fails the tests, which links the run and its logs. To fix it:
- Add the release with
Add-UmbracoRelease.ps1, then run the quick tests withpwsh tests/Test-UmbracoReleases.ps1 -Releases 18.3.2. Each failure names its patch entry, andPatchOriginTestssays whether Umbraco changed the code or only its minified output. - Fix each entry that no longer matches, and keep the earlier releases' entries as they are.
For an entry in a major version's file, such as
src/Patchsets/Umbraco18/Umbraco18Patches.cs, set itsBeforeto the new release, add a copy withFromset to the new release andBeforeset to the next major version (19.0.0), and update the copy. An entry in an area file, such asSignInPatches.cs, applies to every major version: move it into each major version's file, limited to that version, keep its edits in the area file for the copies to share, and update the new release's copy.src/Patchsets/BackOfficeAssetPatches.csexplains the entry format. - Run the quick tests again, then the browser cases with
pwsh tests/Test-UmbracoReleases.ps1 -Releases 18.3.2 -Browser. - Commit the changes to
main, with the release listed, and close the issue. Then startrelease.ymlby hand to publish.
Add an Umbraco major version
Add-UmbracoRelease.ps1 and the daily workflow accept releases of the listed major versions
only. When Umbraco publishes a new major version, the workflow opens an issue titled
Support Umbraco <major>, and a person adds it. Umbraco 19 runs on .NET 11, and NuGet picks
a package's assembly by the site's .NET version, so Umbraco 19 needs a second build of the
package:
- Install the .NET 11 SDK, raise the SDK in
global.json, and add the SDK to the workflows'setup-dotnetsteps. - Target
net10.0;net11.0in the package project, with Umbraco 17 and 18 for .NET 10 and Umbraco 19 for .NET 11. Make the test project target .NET 11 whenUmbracoVersionis a 19 release, and add the Umbraco 19 starter kit toDirectory.Build.props. - Add
src/Patchsets/Umbraco19/Umbraco19Patches.csandsrc/UmbracoVersions/Umbraco19/Umbraco19Major.csto the .NET 11 build, and addUmbraco19MajortoUmbracoMajor.Allunder#if NET11_0_OR_GREATER. - Add its first release to
UmbracoReleasesinDirectory.Build.props, and setUmbracoMaximumVersionandUmbracoVersionto it. - Add a row to the Supported versions table with
umbraco-releases 19markers like those in the rows above, and add the major version to the text and badge that name the supported versions. - Test the release and fix its patches, from step 1 of Fix a release that fails.
Releases
The package follows Umbraco. Each day umbraco-releases.yml looks on nuget.org for new
Umbraco releases and tests the package on each. A release that passes is added to
UmbracoReleases and to the Supported versions table, and release.yml publishes the
package to nuget.org and GitHub. A release that fails gets an issue.
A package version is <newest supported Umbraco release>.<count>, such as 18.3.2.1. Each
release publishes one package for each supported major version, such as 18.3.2.1 and
17.8.2.1, so a site can float on 18.* or 17.*. The count starts at 1 for each Umbraco
release.
The release guide describes the workflows and how to start a release by hand.
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Umbraco.Cms.StaticAssets (>= 17.5.0 && <= 18.3.2)
- Umbraco.Cms.Web.Common (>= 17.5.0 && <= 18.3.2)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on AurorisNet.Umbraco.ApplicationVirtualPathFix:
| Package | Downloads |
|---|---|
|
AurorisNet.Umbraco.AppHost
A shared base for Umbraco sites: single sign-on and account policy, application blocks and Interactive Reports, website and application themes, virtual-path hosting, and the workarounds for upstream Umbraco gaps. |
GitHub repositories
This package is not used by any popular GitHub repositories.