Skip to content

[11.0 P1] Blazor Web can use BasePath component instead of <base href=""> #36428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[11.0 P1] Blazor Web can use BasePath component instead of <base href=""> #36428

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e087c7e
Doc changes proposal.
ilonatommy Dec 3, 2025
ae37edb
Apply @guardrex's improvements.
ilonatommy Dec 3, 2025
045723f
Update aspnetcore/blazor/host-and-deploy/app-base-path.md
ilonatommy Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 33 additions & 9 deletions aspnetcore/blazor/host-and-deploy/app-base-path.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,19 +60,23 @@ For the sources of links that pertain to Blazor in ASP.NET Core apps:

If you're rendering a Blazor app from different documents (for example, `/Admin/B/C/` and `/Admin/D/E/`), you must take the app base path into account, or the base path is different when the app renders in each document and the resources are fetched from the wrong URLs.

There are two approaches to deal with the challenge of resolving relative links correctly:
Choose one of the following strategies to keep relative links resolving correctly:

* Map the resources dynamically using the document they were rendered on as the root.
* Set a consistent base path for the document and map the resources under that base path.
* Map resources dynamically using the document they were rendered on as the root. This requires custom routing logic (for example, <xref:Microsoft.AspNetCore.Routing.IDynamicEndpointMetadata> or a <xref:Microsoft.AspNetCore.Routing.MatcherPolicy>) and is typically reserved for highly dynamic sites.

The first option is more complicated and isn't the most typical approach, as it makes navigation different for each document. Consider the following example for rendering a page `/Something/Else`:
:::moniker range=">= aspnetcore-11.0"

* Rendered under `/Admin/B/C/`, the page is rendered with a path of `/Admin/B/C/Something/Else`.
* Rendered under `/Admin/D/E/`, the page is rendered ***at the same path*** of `/Admin/B/C/Something/Else`.
* Establish a consistent base path for the document and map all app resources beneath that path. Blazor Web Apps can rely on the `BasePath` component to render `<base href>` automatically, while standalone WebAssembly apps (or scenarios that always use a fixed value) configure the literal `<base>` tag in the host page.

Under the first approach, routing offers <xref:Microsoft.AspNetCore.Routing.IDynamicEndpointMetadata> and <xref:Microsoft.AspNetCore.Routing.MatcherPolicy>, which in combination can be the basis for implementing a completely dynamic solution that determines at runtime about how requests are routed.
:::moniker-end

:::moniker range="< aspnetcore-11.0"

* Establish a consistent base path for the document and map all app resources beneath that path. Configure the literal `<base>` tag in the host page for both server-side Blazor apps and Blazor WebAssembly apps (or scenarios that always use a fixed value).

:::moniker-end

For the second option, which is the usual approach taken, the app sets the base path in the document and maps the server endpoints to paths under the base. The following guidance adopts this approach.
The remainder of this article focuses on implementing a consistent base path.

## Server-side Blazor

Expand Down Expand Up @@ -126,7 +130,13 @@ By configuring the app base path, a component that isn't in the root directory c

Place the `<base>` tag in `<head>` markup ([location of `<head>` content](xref:blazor/project-structure#location-of-head-and-body-content)) before any elements with attribute values that are URLs, such as the `href` attributes of `<link>` elements.

:::moniker range=">= aspnetcore-8.0"
:::moniker range=">= aspnetcore-11.0"

In many hosting scenarios, the relative URL path to the app is the root of the app. When the app runs at `/`, `<BasePath />` renders `<base href="/" />` automatically in [`<head>` content](xref:blazor/project-structure#location-of-head-and-body-content). For any other deployment path, the component emits a `<base>` element that matches the current request's path base.

:::moniker-end

:::moniker range=">= aspnetcore-8.0 < aspnetcore-11.0"

In many hosting scenarios, the relative URL path to the app is the root of the app. In these default cases, the app's relative URL base path is `/` configured as `<base href="/" />` in [`<head>` content](xref:blazor/project-structure#location-of-head-and-body-content).

Expand All @@ -146,6 +156,18 @@ In many hosting scenarios, the relative URL path to the app is the root of the a

* In a server-side Blazor app, use ***either*** of the following approaches:

:::moniker range=">= aspnetcore-11.0"

* Option 1: Use the `BasePath` component to set the app's base path ([location of `<head>` content](xref:blazor/project-structure#location-of-head-and-body-content)):

```razor
<BasePath />
```

The component renders `<base href>` automatically based on the current request path base.

:::moniker range="< aspnetcore-11.0"

* Option 1: Use the `<base>` tag to set the app's base path ([location of `<head>` content](xref:blazor/project-structure#location-of-head-and-body-content)):

```html
Expand All @@ -154,6 +176,8 @@ In many hosting scenarios, the relative URL path to the app is the root of the a

**The trailing slash is required.**

:::moniker-end

* Option 2: Call <xref:Microsoft.AspNetCore.Builder.UsePathBaseExtensions.UsePathBase%2A> ***first*** in the app's request processing pipeline (`Program.cs`) immediately after the <xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder> is built (`builder.Build()`) to configure the base path for any following middleware that interacts with the request path:

```csharp
Expand Down
Loading