Orchardcore Diagnostics

Orchard Core Diagnostics

OrchardCore.Diagnostics wires tenant-aware error handling into the Orchard Core pipeline. Its startup filter uses /Error for unhandled exceptions outside development and re-executes status code responses at /Error/{status}. The module maps the Error/{status?} route to DiagnosticsController.Error.

Guidelines

• Enable the exact OrchardCore.Diagnostics feature before relying on its error route and shapes.
• In non-development environments it calls UseExceptionHandler("/Error").
• It calls UseStatusCodePagesWithReExecute("/Error/{0}") for status responses.
• Do not expose exception details in theme templates or production error pages.
• Static-file paths are excluded from status page rendering when their extension maps to a content type.
• Override error rendering through theme shapes rather than changing the module controller.
• Use IConfigureOptions for your own options registration, not to replace the diagnostic middleware order.
• Error templates must tolerate an absent status code because /Error also handles exceptions.
• All C# classes in examples are sealed except View Models.

Enable Diagnostics

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "OrchardCore.Diagnostics"
      ],
      "disable": []
    }
  ]
}

Pipeline Behavior

The module registers DiagnosticsStartupFilter as an IStartupFilter. This ensures the error handling runs in the correct tenant pipeline without an application manually adding duplicate middleware.

Avoid calling UseExceptionHandler or UseStatusCodePagesWithReExecute again for the same tenant unless you deliberately replace this behavior and have verified pipeline order.

Override Error Shapes

The controller produces an HttpError shape. It supplies alternates in this order:

1. HttpError__{numericStatus} such as HttpError__404
2. HttpError__{HttpStatusCodeName} such as HttpError__NotFound

Add a default fallback in the active theme:

@* Views/HttpError.cshtml *@
@model OrchardCore.Diagnostics.ViewModels.HttpErrorShapeViewModel

<main class="error-page">
    <h1>Something went wrong</h1>
    <p>Please return to the home page or try again later.</p>
</main>

Add a more specific 404 template:

@* Views/HttpError-404.cshtml *@
@model OrchardCore.Diagnostics.ViewModels.HttpErrorShapeViewModel

<main class="error-page">
    <h1>Page not found</h1>
    <p>The requested address is unavailable.</p>
</main>

The physical file naming convention is normalized by display management. Use the documented HttpError__404 alternate when reasoning about selection and the conventional HttpError-404.cshtml theme file when creating Razor views.

Add Application-Specific Error Options

Diagnostics itself has no public settings class. If a module needs a feature flag or support link for its own error display, model it with options:

using Microsoft.Extensions.Options;

namespace MyModule;

public sealed class ErrorDisplayOptions
{
    public string SupportUrl { get; set; }
}

public sealed class ErrorDisplayOptionsConfiguration
    : IConfigureOptions<ErrorDisplayOptions>
{
    public void Configure(ErrorDisplayOptions options)
    {
        options.SupportUrl = "/contact";
    }
}

Register the configuration in your module startup and consume it only from your own shape or view model. Do not insert exception details into the options or render them to public users.

Test Error Pages

Test an unknown route, a forbidden route, and a controlled exception in an environment matching production. Verify the intended HttpError alternate renders and that requests for missing CSS, JavaScript, and images do not receive HTML error documents.

Keep Error Responses Safe

An error page is part of the public attack surface. Show a stable support message, preserve correlation identifiers supplied by the host when available, and log exception details only on the server. Do not display stack traces, connection strings, authentication claims, or route values that could contain personal data.

The diagnostics module deliberately separates exception handling from status code rendering. A 404 is a normal request outcome and should normally have a helpful, cache-aware themed response. An exception is an operational failure and should lead users to a generic page while server telemetry retains the diagnostic context.

Route Considerations

The built-in area route is Error/{status?}. Avoid defining an application endpoint that shadows /Error in a tenant using this module. If a site needs a different public support URL, link to it from the HttpError shape rather than changing the error handler path.