API proposal for `IHostEnvironmentNavigationManager.Initialize`

[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.

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;
    }
);

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.