dotnet / dotnet/aspnetcore

[Validation] BasePath when hosting a Blazor Web App under a sub-path

Open
#68,810 4 comments 0 reactions 1 assignee Claimed by @BharatRamsf3693 View on GitHub
area-blazor Validation validation-scenario
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 6h
Merged PRs (30d)
290

Description

**Scenario contact:** @ilonatommy

## Scenario

Apps are frequently deployed somewhere other than the root of a site: under a virtual directory, behind a gateway that adds a prefix, or alongside other apps on one hostname. Getting this right used to mean editing the base href by hand and keeping it in step with the deployment. The new `BasePath` component renders the `` element from the path the request actually arrived on, so the app no longer carries a hardcoded address. The Blazor Web App template now uses it in place of ``.

This validates the fix for [#6818](https://github.com/dotnet/aspnetcore/issues/6818). The bug reported there is narrower than "the app works under a prefix": an app mounted at `/dashboard` with a hardcoded base href only worked when the URL used that exact casing, so `/Dashboard/counter` broke while `/dashboard/counter` was fine. Cover that specifically, alongside the general sub-path behavior.

## Minimum build

.NET 11 Preview 7 or later.

## Configurations to cover

* Blazor Web App
* [x] Static SSR
* [x] Interactive Server
* [x] Interactive WebAssembly
* [ ] Interactive Auto
* [ ] Standalone WebAssembly
* [ ] Hybrid (MAUI)

## Also exercise

* [x] Published output
* [x] An existing .NET 10 app upgraded to .NET 11
* [ ] Trimming or ahead-of-time compilation
* [x] More than one server instance, or a proxy in front
* [ ] Hot Reload
* [ ] An IDE as well as the command line
* [ ] Container

## Setup

You need a way to serve the app under a path prefix. Configuring a path base in the app itself is the easiest, and hosting the published output under an IIS virtual directory or behind a reverse proxy is the more realistic variant. Testing both is valuable. Use a prefix with at least one capital letter in it, such as `/Dashboard`, so that casing is actually in play.

## What to build

An app with enough moving parts that a wrong base address is impossible to miss: several pages including one on a nested route, navigation links between them, an image and a stylesheet loaded from the app's own static files, a form that posts to the server, and a page that shows a URL it built itself from a relative path. Then run the whole thing under a path prefix rather than at the root.

## Things to try

* Running the app at the root first, so you have a known-good comparison.
* Running it under a prefix, and opening the nested route directly instead of navigating to it.
* The case reported in the issue: reaching the app through a prefix whose casing differs from the one it is mounted under, for example opening `/dashboard/counter` and `/Dashboard/counter` on an app mounted at `/Dashboard`. Try both spellings for a page opened directly and for one reached by clicking a link.
* Reloading the browser while on the nested route.
* Navigating between pages using the links, then using browser back and forward.
* Submitting the form and checking where it posted.
* Viewing the page source and looking at the base element and the script and stylesheet addresses.
* Publishing the app and hosting the published output under a prefix, rather than running it from the development server.
* Changing the prefix to a different value and running again without rebuilding.
* An app upgraded from .NET 10, which still has a literal ``, before and after swapping in ``. The component lives in `Microsoft.AspNetCore.Components.Endpoints`, which the .NET 10 template does not import, so note whether the build failure you get points you at the missing `@using`.

## Expected behavior

The app works under the prefix exactly as it does at the root, without a source change when the prefix changes.

### Must hold

* No request in the browser network log returns 404, including scripts, stylesheets and images.
* The rendered `` matches the prefix the app is served under, including its casing, rather than the casing the app was mounted with.
* The app works through either spelling of the prefix. Neither one produces a blank page, a routing failure, or an error in the browser console or the server log.
* Opening a nested route directly under the prefix returns that page, and reloading it returns the same page again.
* Navigation links resolve to addresses that include the prefix.
* A form post reaches the correct address under the prefix and is handled.
* Changing the prefix and restarting requires no source change and no rebuild.

### Expected differences between configurations

* The `` element itself is produced the same way in every render mode, because the root component is statically rendered in all of them. The render modes differ in what breaks when the base address is wrong: Interactive Server has to reach its connection endpoint under the prefix, and Interactive WebAssembly has to fetch its framework files under it. Interactive Auto is not listed separately because it is those two cases together.
* Standalone WebAssembly is out of scope: `BasePath` is a server-side component, and that template still writes a literal ``.

## Evidence to capture

The rendered `` value under the prefix, and under each spelling of it, together with the browser network log for a full page load showing the status of every asset request.

## Documentation to use

* [New BasePath component, .NET 11 release notes](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-11#new-basepath-component)
* [ASP.NET Core Blazor app base path](https://learn.microsoft.com/aspnet/core/blazor/host-and-deploy/app-base-path?view=aspnetcore-11.0)

The base path page presents `` as the first option for a Blazor Web App, but it does not mention that the component preserves the casing of the requested path, which is the behavior this scenario is mainly about, and it does not mention the namespace the component lives in. Say so in the report if either gap cost you time.

## What to report

Report results using the format described in the [validation testing manual](https://github.com/dotnet/aspnetcore/issues/68479). Include link to a repository with the test app.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.