API proposal for `Router.NotFoundPage`

[ilonatommy]

Background and Motivation

Blazor’s Router component determines which page to display based on the current route. Previously, customizing the content shown for unmatched routes (i.e., 404 “not found” pages) required using the NotFound render fragment, which could be limiting in scenarios where you want to display a dedicated component or page type or unify the not-found experience for non-blazor pages re-execution.

This proposal introduces a new NotFoundPage property on Microsoft.AspNetCore.Components.Routing.Router, allowing developers to specify a component type to render when no route matches. This provides a more flexible and reusable way to handle “not found” scenarios in Blazor applications.

Proposed API

namespace Microsoft.AspNetCore.Components.Routing
{
    public class Router : IComponent
    {
+       public Type? NotFoundPage { get; set; }
    }
}

Usage Examples

<Router AppAssembly="@typeof(Program).Assembly"
        NotFoundPage="@typeof(MyCustomNotFoundComponent)">
</Router>

Where MyCustomNotFoundComponent is a Blazor component with a route that you define, for example:

@path "/my-not-found"
<h1>Page Not Found</h1>
<p>The page you are looking for does not exist.</p>

Alternative Designs

• The existing NotFound render fragment allows inline markup for unmatched routes, but does not support specifying a reusable component type and does not render for corner cases, like started response in streaming rendering.
• Other frameworks often allow specifying a “not found” page by type or path, which this proposal aligns with.
• An alternative could have been to enhance the NotFound fragment to accept a component type, but a dedicated property is more explicit and discoverable.

Risks

• If both NotFound and NotFoundPage are set, there may be ambiguity about which takes precedence. NotFoundPage does. Documentation should clarify the behavior.
• If the specified NotFoundPage type is not a valid Blazor component or is a component without RouteAttribute, a runtime error will occur.

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

[javiercn]

Consider making it nullable

[halter73]

API Review Notes:

• Is NotFoundPage nullable?
  • Yes.
• Should it be an error if both NotFoundPage and the NotFound child content are defined?
  • Maybe we should make it a warning instead if we're concerned about breaking.
• Should we deprecate the NotFound render fragment?
  • Possibly
• Could we make it possible to specify the NotFoundPage inside the NotFound render fragment?
  • This would be a non-trivial change.

API Approved!

namespace Microsoft.AspNetCore.Components.Routing
{
    public class Router : IComponent
    {
+       public Type? NotFoundPage { get; set; }
    }
}

[javiercn]

Make an error having render fragment and page at the same time