Navigation Exception: Introduce Clear Message

src/Components/Components/src/NavigationException.cs

@@ -16,6 +16,14 @@ public NavigationException(string uri)
         Location = uri;
     }
 
+    /// <summary>
+    /// Initializes a new <see cref="NavigationException"/> instance with a custom message.
+    /// </summary>
+    public NavigationException(string uri, string message) : base(message)
+    {
+        Location = uri;
+    }
+
     /// <summary>
     /// Gets the uri to which navigation was attempted.
     /// </summary>

src/Components/Components/src/NavigationRedirectHelper.cs

@@ -0,0 +1,28 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Helper class to throw a <see cref="NavigationException"/>.
+/// </summary>
+public static class NavigationRedirectHelper
+{
+    private const string RedirectExceptionMessage =
+        "A navigation was initiated during static rendering. " +
+        "This exception is not an error, but instead signals to the framework that a redirect should occur. " +
+        "It should not be caught by application code.";
+
+    /// <summary>
+    /// Creates an absolute URI and throws a new <see cref="NavigationException"/>.
+    /// </summary>
+
+    [DoesNotReturn]
+    public static void ThrowNavigationExceptionForRedirect(NavigationManager navigationManager, string uri)
+    {
+        var absoluteUriString = navigationManager.ToAbsoluteUri(uri).AbsoluteUri;
+        throw new NavigationException(absoluteUriString, RedirectExceptionMessage);
+    }
+}

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

@@ -4,6 +4,8 @@ Microsoft.AspNetCore.Components.ComponentBase.AssignedRenderMode.get -> Microsof
 Microsoft.AspNetCore.Components.ComponentBase.RendererInfo.get -> Microsoft.AspNetCore.Components.RendererInfo!
 Microsoft.AspNetCore.Components.ExcludeFromInteractiveRoutingAttribute
 Microsoft.AspNetCore.Components.ExcludeFromInteractiveRoutingAttribute.ExcludeFromInteractiveRoutingAttribute() -> void
+Microsoft.AspNetCore.Components.NavigationException.NavigationException(string! uri, string! message) -> void
+Microsoft.AspNetCore.Components.NavigationRedirectHelper
 Microsoft.AspNetCore.Components.RendererInfo
 Microsoft.AspNetCore.Components.RendererInfo.IsInteractive.get -> bool
 Microsoft.AspNetCore.Components.RendererInfo.Name.get -> string!
@@ -23,6 +25,7 @@ Microsoft.AspNetCore.Components.ResourceAssetProperty
 Microsoft.AspNetCore.Components.ResourceAssetProperty.Name.get -> string!
 Microsoft.AspNetCore.Components.ResourceAssetProperty.ResourceAssetProperty(string! name, string! value) -> void
 Microsoft.AspNetCore.Components.ResourceAssetProperty.Value.get -> string!
+static Microsoft.AspNetCore.Components.NavigationRedirectHelper.ThrowNavigationExceptionForRedirect(Microsoft.AspNetCore.Components.NavigationManager! navigationManager, string! uri) -> void
 static readonly Microsoft.AspNetCore.Components.ResourceAssetCollection.Empty -> Microsoft.AspNetCore.Components.ResourceAssetCollection!
 virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.Assets.get -> Microsoft.AspNetCore.Components.ResourceAssetCollection!
 virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.RendererInfo.get -> Microsoft.AspNetCore.Components.RendererInfo!

src/Components/Endpoints/src/DependencyInjection/HttpNavigationManager.cs

@@ -11,7 +11,6 @@ internal sealed class HttpNavigationManager : NavigationManager, IHostEnvironmen
 
     protected override void NavigateToCore(string uri, NavigationOptions options)
     {
-        var absoluteUriString = ToAbsoluteUri(uri).AbsoluteUri;
-        throw new NavigationException(absoluteUriString);
+        NavigationRedirectHelper.ThrowNavigationExceptionForRedirect(this, uri);
     }
 }

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

@@ -87,8 +87,7 @@ protected override void NavigateToCore(string uri, NavigationOptions options)
 
         if (_jsRuntime == null)
         {
-            var absoluteUriString = ToAbsoluteUri(uri).AbsoluteUri;
-            throw new NavigationException(absoluteUriString);
+            NavigationRedirectHelper.ThrowNavigationExceptionForRedirect(this, uri);
         }
 
         _ = PerformNavigationAsync();
@@ -128,8 +127,7 @@ public override void Refresh(bool forceReload = false)
     {
         if (_jsRuntime == null)
         {
-            var absoluteUriString = ToAbsoluteUri(Uri).AbsoluteUri;
-            throw new NavigationException(absoluteUriString);
+            NavigationRedirectHelper.ThrowNavigationExceptionForRedirect(this, Uri);
         }
 
         _ = RefreshAsync();