API proposal for `IHostEnvironmentNavigationManager.Initialize` and SSR navigation switch

[ilonatommy]

Background and Motivation

• The IHostEnvironmentNavigationManager interface is responsible for managing navigation state in Blazor applications, particularly in host environments such as Blazor WebAssembly and Blazor Server. Previously, the Initialize method allowed setting the base URI and current URI, but did not provide a way to hook into navigation events at initialization.

This proposal introduces a new overload of Initialize that accepts an onNavigateTo callback. This enables host environments to intercept and handle navigation events as part of the initialization process, providing greater flexibility for scenarios such as custom navigation handling, logging, or integration with platform-specific navigation systems.

• We're introducing a switch for changing SSR navigation behavior. We used to throw NavigationException (old behavior) and now we introduced an even handler that communicates the need to navigate away to the renderer. By default we stick to the old behavior. Switch name: "Microsoft.AspNetCore.Components.Endpoints.NavigationManager.DisableThrowNavigationException". Default value: false.

Proposed API

namespace Microsoft.AspNetCore.Components.Routing
{
    public interface IHostEnvironmentNavigationManager
    {
        void Initialize(string baseUri, string uri);
+       void Initialize(string baseUri, string uri, Func<string, Task> onNavigateTo);
    }
}

Usage Examples

// Example: Custom navigation interception during initialization
hostEnvironmentNavigationManager.Initialize(
    baseUri: "https://example.com/",
    uri: "https://example.com/app/page",
    onNavigateTo: async (targetUri) =>
    {
        Console.WriteLine($"Navigating to: {targetUri}");
        // Perform custom logic, e.g., analytics, permission checks, etc.
        await Task.CompletedTask;
    }
);

AppContext.SetSwitch("Microsoft.AspNetCore.Components.Endpoints.NavigationManager.DisableThrowNavigationException", false);

Alternative Designs

• An alternative could have been to expose a separate event or registration method, but providing the callback directly in Initialize ensures it is set up before any navigation occurs.

Risks

• Existing consumers of the interface must ensure they use the correct overload for their scenario; however, the original overload remains for backward compatibility.

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.