Allow cancellation of navigation events in Blazor

src/Components/Components/src/NavigationManager.cs

@@ -1,10 +1,13 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Buffers;
 using Microsoft.AspNetCore.Components.Routing;
 
 namespace Microsoft.AspNetCore.Components;
 
+using LocationChangingHandler = Func<LocationChangingContext, Task>;
+
 /// <summary>
 /// Provides an abstraction for querying and managing URI navigation.
 /// </summary>
@@ -31,6 +34,10 @@ public event EventHandler<LocationChangedEventArgs> LocationChanged
 
     private EventHandler<LocationChangedEventArgs>? _locationChanged;
 
+    private readonly List<LocationChangingHandler> _locationChangingHandlers = new();
+
+    private CancellationTokenSource? _locationChangingCts;
+
     // For the baseUri it's worth storing as a System.Uri so we can do operations
     // on that type. System.Uri gives us access to the original string anyway.
     private Uri? _baseUri;
@@ -274,6 +281,111 @@ protected void NotifyLocationChanged(bool isInterceptedLink)
         }
     }
 
+    /// <summary>
+    /// Notifies the registered handlers of the current location change.
+    /// </summary>
+    /// <param name="uri">The destination URI. This can be absolute, or relative to the base URI.</param>
+    /// <param name="isNavigationIntercepted">Whether this navigation was intercepted from a link.</param>
+    /// <returns>A <see cref="ValueTask{TResult}"/> representing the completion of the operation. If the result is <see langword="true"/>, the navigation should continue.</returns>
+    protected async ValueTask<bool> NotifyLocationChangingAsync(string uri, bool isNavigationIntercepted)
+    {
+        _locationChangingCts?.Cancel();
+        _locationChangingCts = null;
+
+        var handlerCount = _locationChangingHandlers.Count;
+
+        if (handlerCount == 0)
+        {
+            return true;
+        }
+
+        _locationChangingCts = new();
+
+        var context = new LocationChangingContext(uri, isNavigationIntercepted, _locationChangingCts);
+        var cancellationToken = _locationChangingCts.Token;
+
+        try
+        {
+            if (handlerCount == 1)
+            {
+                await _locationChangingHandlers[0].Invoke(context);
+            }
+            else
+            {
+                var locationChangingHandlersCopy = ArrayPool<LocationChangingHandler>.Shared.Rent(handlerCount);
+
+                try
+                {
+                    _locationChangingHandlers.CopyTo(locationChangingHandlersCopy);
+
+                    var locationChangingTasks = new Task[handlerCount];
+
+                    for (var i = 0; i < handlerCount; i++)
+                    {
+                        locationChangingTasks[i] = locationChangingHandlersCopy[i].Invoke(context);
+
+                        if (cancellationToken.IsCancellationRequested)
+                        {
+                            return false;
+                        }
+                    }
+
+                    await Task.WhenAll(locationChangingTasks).WaitAsync(cancellationToken);
+                }
+                finally
+                {
+                    ArrayPool<LocationChangingHandler>.Shared.Return(locationChangingHandlersCopy);
+                }
+            }
+
+            return !cancellationToken.IsCancellationRequested;
+        }
+        catch (TaskCanceledException ex) when (ex.CancellationToken == cancellationToken)
+        {
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// Sets whether there are active location changing handlers.
+    /// </summary>
+    /// <param name="value">Whether there are active location changing handlers.</param>
+    protected virtual void SetNavigationLockState(bool value)
+        => throw new NotSupportedException($"To support navigation locks, {GetType().Name} must override {nameof(SetNavigationLockState)}");
+
+    /// <summary>
+    /// Adds a handler to process incoming navigation events.
+    /// </summary>
+    /// <param name="locationChangingHandler">The handler to process incoming navigation events.</param>
+    public void AddLocationChangingHandler(LocationChangingHandler locationChangingHandler)
+    {
+        AssertInitialized();
+
+        var isFirstHandler = _locationChangingHandlers.Count == 0;
+
+        _locationChangingHandlers.Add(locationChangingHandler);
+
+        if (isFirstHandler)
+        {
+            SetNavigationLockState(true);
+        }
+    }
+
+    /// <summary>
+    /// Removes a previously-added location changing handler.
+    /// </summary>
+    /// <param name="locationChangingHandler">The handler to remove.</param>
+    /// <returns><see langword="true"/> if the handler was removed, otherwise <see langword="false"/>.</returns>
+    public void RemoveLocationChangingHandler(LocationChangingHandler locationChangingHandler)
+    {
+        AssertInitialized();
+
+        if (_locationChangingHandlers.Remove(locationChangingHandler) && _locationChangingHandlers.Count == 0)
+        {
+            SetNavigationLockState(false);
+        }
+    }
+
     private void AssertInitialized()
     {
         if (!_isInitialized)

src/Components/Components/src/PublicAPI.Unshipped.txt

@@ -1,10 +1,18 @@
 #nullable enable
+Microsoft.AspNetCore.Components.NavigationManager.AddLocationChangingHandler(System.Func<Microsoft.AspNetCore.Components.Routing.LocationChangingContext!, System.Threading.Tasks.Task!>! locationChangingHandler) -> void
 Microsoft.AspNetCore.Components.NavigationManager.HistoryEntryState.get -> string?
 Microsoft.AspNetCore.Components.NavigationManager.HistoryEntryState.set -> void
+Microsoft.AspNetCore.Components.NavigationManager.NotifyLocationChangingAsync(string! uri, bool isNavigationIntercepted) -> System.Threading.Tasks.ValueTask<bool>
+Microsoft.AspNetCore.Components.NavigationManager.RemoveLocationChangingHandler(System.Func<Microsoft.AspNetCore.Components.Routing.LocationChangingContext!, System.Threading.Tasks.Task!>! locationChangingHandler) -> void
 Microsoft.AspNetCore.Components.NavigationOptions.HistoryEntryState.get -> string?
 Microsoft.AspNetCore.Components.NavigationOptions.HistoryEntryState.init -> void
 Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder.AddContent(int sequence, Microsoft.AspNetCore.Components.MarkupString? markupContent) -> void
 Microsoft.AspNetCore.Components.Routing.LocationChangedEventArgs.HistoryEntryState.get -> string?
+Microsoft.AspNetCore.Components.Routing.LocationChangingContext
+Microsoft.AspNetCore.Components.Routing.LocationChangingContext.CancellationToken.get -> System.Threading.CancellationToken
+Microsoft.AspNetCore.Components.Routing.LocationChangingContext.IsNavigationIntercepted.get -> bool
+Microsoft.AspNetCore.Components.Routing.LocationChangingContext.PreventNavigation() -> void
+Microsoft.AspNetCore.Components.Routing.LocationChangingContext.TargetLocation.get -> string!
 static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.CreateInferredEventCallback<T>(object! receiver, Microsoft.AspNetCore.Components.EventCallback<T> callback, T value) -> Microsoft.AspNetCore.Components.EventCallback<T>
 static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.InvokeAsynchronousDelegate(System.Action! callback) -> System.Threading.Tasks.Task!
 static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.InvokeAsynchronousDelegate(System.Func<System.Threading.Tasks.Task!>! callback) -> System.Threading.Tasks.Task!
@@ -41,3 +49,4 @@ static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.Crea
 static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback<short?> setter, short? existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs!>
 static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback<string?> setter, string! existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs!>
 static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder<T>(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback<T> setter, T existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs!>
+virtual Microsoft.AspNetCore.Components.NavigationManager.SetNavigationLockState(bool value) -> void

src/Components/Components/src/Routing/LocationChangingContext.cs

@@ -0,0 +1,43 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components.Routing;
+
+/// <summary>
+/// Contains context for a change to the browser's current location.
+/// </summary>
+public class LocationChangingContext
+{
+    private readonly CancellationTokenSource _cts;
+
+    internal LocationChangingContext(string destinationUrl, bool isNavigationIntercepted, CancellationTokenSource cts)
+    {
+        TargetLocation = destinationUrl;
+        IsNavigationIntercepted = isNavigationIntercepted;
+
+        _cts = cts;
+    }
+
+    /// <summary>
+    /// Gets the target location.
+    /// </summary>
+    public string TargetLocation { get; }
+
+    /// <summary>
+    /// Gets whether this navigation was intercepted from a link.
+    /// </summary>
+    public bool IsNavigationIntercepted { get; }
+
+    /// <summary>
+    /// Gets a <see cref="System.Threading.CancellationToken"/> that can be used to determine if this navigation was canceled.
+    /// </summary>
+    public CancellationToken CancellationToken => _cts.Token;
+
+    /// <summary>
+    /// Prevents this navigation from continuing.
+    /// </summary>
+    public void PreventNavigation()
+    {
+        _cts.Cancel();
+    }
+}

src/Components/Server/src/Circuits/CircuitHost.cs

@@ -536,6 +536,31 @@ await Renderer.Dispatcher.InvokeAsync(() =>
         }
     }
 
+    public async Task OnLocationChangingAsync(int callId, string uri, bool intercepted)
+    {
+        AssertInitialized();
+        AssertNotDisposed();
+
+        try
+        {
+            var shouldContinueNavigation = await Renderer.Dispatcher.InvokeAsync(async () =>
+            {
+                Log.LocationChanging(_logger, uri, CircuitId);
+                var navigationManager = (RemoteNavigationManager)Services.GetRequiredService<NavigationManager>();
+                return await navigationManager.HandleLocationChangingAsync(uri, intercepted);
+            });
+
+            await Client.SendAsync("JS.EndLocationChanging", callId, shouldContinueNavigation);
+        }
+        catch (Exception ex)
+        {
+            // Exceptions thrown by location changing handlers should be treated like unhandled exceptions in user-code.
+            Log.LocationChangeFailedInCircuit(_logger, uri, CircuitId, ex);
+            await TryNotifyClientErrorAsync(Client, GetClientErrorMessage(ex, $"Location changing to '{uri}' failed."));
+            UnhandledException?.Invoke(this, new UnhandledExceptionEventArgs(ex, isTerminating: false));
+        }
+    }
+
     public void SetCircuitUser(ClaimsPrincipal user)
     {
         // This can be called before the circuit is initialized.
@@ -730,6 +755,9 @@ public static void CircuitHandlerFailed(ILogger logger, CircuitHandler handler,
         [LoggerMessage(210, LogLevel.Debug, "Location change to '{URI}' in circuit '{CircuitId}' failed.", EventName = "LocationChangeFailed")]
         public static partial void LocationChangeFailed(ILogger logger, string uri, CircuitId circuitId, Exception exception);
 
+        [LoggerMessage(211, LogLevel.Debug, "Location is about to change to {URI} in ciruit '{CircuitId}'.", EventName = "LocationChanging")]
+        public static partial void LocationChanging(ILogger logger, string uri, CircuitId circuitId);
+
         [LoggerMessage(212, LogLevel.Debug, "Failed to complete render batch '{RenderId}' in circuit host '{CircuitId}'.", EventName = "OnRenderCompletedFailed")]
         public static partial void OnRenderCompletedFailed(ILogger logger, long renderId, CircuitId circuitId, Exception e);
 

src/Components/Server/src/Circuits/RemoteNavigationManager.cs

@@ -16,6 +16,7 @@ internal sealed partial class RemoteNavigationManager : NavigationManager, IHost
 {
     private readonly ILogger<RemoteNavigationManager> _logger;
     private IJSRuntime _jsRuntime;
+    private bool? _pendingNavigationLockState;
 
     /// <summary>
     /// Creates a new <see cref="RemoteNavigationManager"/> instance.
@@ -54,6 +55,12 @@ public void AttachJsRuntime(IJSRuntime jsRuntime)
         }
 
         _jsRuntime = jsRuntime;
+
+        if (_pendingNavigationLockState.HasValue)
+        {
+            SetHasLocationChangingListeners(_pendingNavigationLockState.Value);
+            _pendingNavigationLockState = null;
+        }
     }
 
     public void NotifyLocationChanged(string uri, string state, bool intercepted)
@@ -65,6 +72,11 @@ public void NotifyLocationChanged(string uri, string state, bool intercepted)
         NotifyLocationChanged(intercepted);
     }
 
+    public async ValueTask<bool> HandleLocationChangingAsync(string uri, bool intercepted)
+    {
+        return await NotifyLocationChangingAsync(uri, intercepted);
+    }
+
     /// <inheritdoc />
     [DynamicDependency(DynamicallyAccessedMemberTypes.PublicProperties, typeof(NavigationOptions))]
     protected override void NavigateToCore(string uri, NavigationOptions options)
@@ -77,9 +89,37 @@ protected override void NavigateToCore(string uri, NavigationOptions options)
             throw new NavigationException(absoluteUriString);
         }
 
-        _jsRuntime.InvokeVoidAsync(Interop.NavigateTo, uri, options).Preserve();
+        NotifyLocationChangingAsync(uri, false).AsTask().ContinueWith(t =>
+        {
+            if (t.Exception is { } exception)
+            {
+                Log.NavigationFailed(_logger, uri, exception);
+            }
+            else if (!t.Result)
+            {
+                Log.NavigationCanceled(_logger, uri);
+            }
+            else
+            {
+                _jsRuntime.InvokeVoidAsync(Interop.NavigateTo, uri, options).Preserve();
+            }
+        }, TaskScheduler.Current);
+    }
+
+    protected override void SetNavigationLockState(bool value)
+    {
+        if (_jsRuntime is null)
+        {
+            _pendingNavigationLockState = value;
+            return;
+        }
+
+        SetHasLocationChangingListeners(value);
     }
 
+    private void SetHasLocationChangingListeners(bool value)
+        => _jsRuntime.InvokeVoidAsync(Interop.SetHasLocationChangingListeners, value).Preserve();
+
     private static partial class Log
     {
         [LoggerMessage(1, LogLevel.Debug, "Requesting navigation to URI {Uri} with forceLoad={ForceLoad}, replace={Replace}", EventName = "RequestingNavigation")]
@@ -90,5 +130,11 @@ public static void RequestingNavigation(ILogger logger, string uri, NavigationOp
 
         [LoggerMessage(2, LogLevel.Debug, "Received notification that the URI has changed to {Uri} with isIntercepted={IsIntercepted}", EventName = "ReceivedLocationChangedNotification")]
         public static partial void ReceivedLocationChangedNotification(ILogger logger, string uri, bool isIntercepted);
+
+        [LoggerMessage(3, LogLevel.Debug, "Navigation canceled when changing the location to {Uri}", EventName = "NavigationCanceled")]
+        public static partial void NavigationCanceled(ILogger logger, string uri);
+
+        [LoggerMessage(4, LogLevel.Error, "Navigation failed when changing the location to {Uri}", EventName = "NavigationFailed")]
+        public static partial void NavigationFailed(ILogger logger, string uri, Exception exception);
     }
 }

src/Components/Server/src/ComponentHub.cs

@@ -296,6 +296,17 @@ public async ValueTask OnLocationChanged(string uri, string? state, bool interce
         _ = circuitHost.OnLocationChangedAsync(uri, state, intercepted);
     }
 
+    public async ValueTask OnLocationChanging(int callId, string uri, bool intercepted)
+    {
+        var circuitHost = await GetActiveCircuitAsync();
+        if (circuitHost == null)
+        {
+            return;
+        }
+
+        _ = circuitHost.OnLocationChangingAsync(callId, uri, intercepted);
+    }
+
     // We store the CircuitHost through a *handle* here because Context.Items is tied to the lifetime
     // of the connection. It's possible that a misbehaving client could cause disposal of a CircuitHost
     // but keep a connection open indefinitely, preventing GC of the Circuit and related application state.

src/Components/Shared/src/BrowserNavigationManagerInterop.cs

@@ -15,4 +15,10 @@ internal static class BrowserNavigationManagerInterop
     public const string GetBaseUri = Prefix + "getUnmarshalledBaseURI";
 
     public const string NavigateTo = Prefix + "navigateTo";
+
+    public const string SetHasLocationChangingListeners = Prefix + "setHasLocationChangingListeners";
+
+    public const string EnableNavigationPrompt = Prefix + "enableNavigationPrompt";
+
+    public const string DisableNavigationPrompt = Prefix + "disableNavigationPrompt";
 }

src/Components/Web.JS/src/Boot.Server.ts

@@ -62,6 +62,8 @@ async function boot(userOptions?: Partial<CircuitStartOptions>): Promise<void> {
   // Configure navigation via SignalR
   Blazor._internal.navigationManager.listenForNavigationEvents((uri: string, state: string | undefined, intercepted: boolean): Promise<void> => {
     return connection.send('OnLocationChanged', uri, state, intercepted);
+  }, (callId: number, uri: string, intercepted: boolean): Promise<void> => {
+    return connection.send('OnLocationChanging', callId, uri, intercepted);
   });
 
   Blazor._internal.forceCloseConnection = () => connection.stop();
@@ -130,6 +132,8 @@ async function initializeConnection(options: CircuitStartOptions, logger: Logger
     renderQueue.processBatch(batchId, batchData, newConnection);
   });
 
+  newConnection.on('JS.EndLocationChanging', Blazor._internal.navigationManager.endLocationChanging);
+
   newConnection.onclose(error => !renderingFailed && options.reconnectionHandler!.onConnectionDown(options.reconnectionOptions, error));
   newConnection.on('JS.Error', error => {
     renderingFailed = true;

src/Components/Web.JS/src/Boot.WebAssembly.ts

@@ -87,6 +87,15 @@ async function boot(options?: Partial<WebAssemblyStartOptions>): Promise<void> {
       state,
       intercepted
     );
+  }, async (callId: number, uri: string, intercepted: boolean): Promise<void> => {
+    const shouldContinueNavigation = await DotNet.invokeMethodAsync<boolean>(
+      'Microsoft.AspNetCore.Components.WebAssembly',
+      'NotifyLocationChangingAsync',
+      uri,
+      intercepted
+    );
+
+    Blazor._internal.navigationManager.endLocationChanging(callId, shouldContinueNavigation);
   });
 
   const candidateOptions = options ?? {};