API proposal for NotFound

[javiercn]

Overview and Motivation

In Blazor, handling missing pages for SEO purposes is problematic because the default workaround neither sets the proper HTTP 404 header for servers nor simplifies client-side NotFound handling. This proposal outlines a refined API to standardize the 404 response behavior across SSR and interactive environments.

Proposed API

namespace Microsoft.AspNetCore.Components
{
    public partial class NavigationManager
    {
        /// <summary>
        /// Instructs the application to treat the current request as a 404 Not Found.
        /// In Server-Side Rendering, it sets HttpContext.Response.StatusCode to 404.
        /// In interactive environments, it triggers the NotFoundEvent.
        /// </summary>
        public virtual void NotFound()
        {
            // ...existing logic to set response status and raise NotFoundEvent...
        }

        /// <summary>
        /// Event that is raised when a NotFound action is invoked in interactive scenarios.
        /// </summary>
        public event EventHandler<EventArgs> NotFoundEvent;
    }
}

Usage Examples

For SSR, calling NotFound() stops further content rendering and sets the response status:

@inject NavigationManager NavigationManager
// ...existing code...
@code {
    protected override void OnInitialized()
    {
        NavigationManager.NotFound();
    }
}

In WebAssembly and interactive server scenarios, NotFound() triggers the NotFoundEvent, allowing a router to render a dedicated "Not Found" page.

Alternative Designs

Risk Considerations

If the SSR response has already been initiated, invoking NotFound() cannot alter the response header, resulting in an InvalidOperationException. Developers must ensure the method is called at the correct stage of the request lifecycle.

[halter73]

API Review Notes:

• Should the NotFoundEvent be fired during static rendering and render the NotFound fragment be rendered during static rendering?
  • The current design is to use standard middleware to write the 404 page. (e.g. UseStatusCodeWithReexecute)
    • This seems better for advanced use cases, but might be harder for Blazor-only apps
    • The project template should set up a standard not found
  • We could add a parameter to the NotFound() method to control this.
• Should we create a NotFoundEventArgs just in case we want to add something in the future.
  • Yes, for future proofing.
• We could copy the pattern from RegisterLocationChangingHandler()
  • No, because unlike the location changing handler, the event does not need to be async.
  • Or maybe yes, because it's harder/impossible to control order with EventHandler.
• What about the name NotFoundEvent?
  • We don't like it.
  • NotFoundInvoked?
  • NavigateNotFound?
  • NotifyNotFound()/NotFound?
    • We want users to be able to call NotFound() rather than NotifyNotFound()
  • NotifyNotFinding 😆
  • NotFoundInvoked
  • OnNotFound?
    • It's not super common to prefix events with On in Blazor
    • But we still prefer it.
• Should NotFound() be virtual?
  • Doesn't need to be. We could add a virtual "Core" method later if we care.

API Approved!

namespace Microsoft.AspNetCore.Components;

public partial class NavigationManager
{
+    public void NotFound();
+    public event EventHandler<NotFoundEventArgs> OnNotFound { add; remove; }
}

namespace Microsoft.AspNetCore.Components.Routing;

+ public sealed NotFoundEventArgs : EventArgs
+ {
+    public NotFoundEventArgs();
+ }