Start here for RazorWire registration, endpoint mapping, safe-by-default stream authorization, options, and stream-result entry points.
Source of truth
RazorWire is the AppSurface package for server-rendered interaction loops: register the package services, map the stream endpoint, configure package options, and return stream updates from MVC controllers without replacing the rest of ASP.NET Core.
Use this namespace page as the API starting point when you already know you are integrating RazorWire and need the public registration, endpoint, and options types in one place.
Use RazorWireStreamBuilder.Visit(...) when an active RazorWire stream should trigger a same-origin Turbo Drive navigation. It emits the rw-visit stream command and supports RazorWireVisitAction.Advance or RazorWireVisitAction.Replace. Keep visit commands out of retained replay channels; replay is for idempotent state snapshots, while navigation is a one-shot browser command.
AddRazorWire(...)Register RazorWire options, stream hub services, safe default stream authorization, form handling, and partial rendering.MapRazorWire(...)Map the configured Server-Sent Events stream endpoint for authorized channel subscriptions.RazorWireOptionsConfigure stream paths, stream authorization mode, output-cache policy names, and enhanced form behavior.IRazorWireStreamAuthorizerReturn passive AppSurface auth results for stream subscriptions before RazorWire opens SSE.IRazorWireStreamAuthorizationFilterAdd package-owned pre-authorization gates for reserved stream channels before the active stream authorizer runs.RazorWireWebModuleUse the AppSurface module when you want package registration and endpoint mapping through module conventions.Provides utility methods for string manipulation, specifically for generating safe identifiers.
string ToSafeId(string? input, bool appendHash = false)
Source
Produces a safe identifier by replacing disallowed characters with hyphens, collapsing consecutive hyphens, trimming edge hyphens, and defaulting to "id" for null, whitespace, or empty results. Optionally appends a short deterministic 4-character lowercase hex hash (prefixed with a hyphen) derived from the original input to ensure uniqueness.
inputThe source string to convert into a safe identifier.appendHashIf true, appends a short deterministic 4-character lowercase hex hash (prefixed with a hyphen).The sanitized identifier; if appendHash is true the value is suffixed with "-" and a 4-character lowercase hex hash.
string GetDeterministicHash(string input)
Source
Produces a short deterministic 4-character lowercase hexadecimal string derived from the SHA-256 hash of the input.
inputThe string to hash.A 4-character lowercase hexadecimal string.
Returns only the first 4 hex characters (16 bits) of the SHA-256 digest; collisions are possible.
Provides an example of how JavaScript functionality can be wrapped in a .NET class for easy consumption.
jsRuntimeThe JS runtime used to invoke JavaScript functions.ValueTask<string?> Prompt(string message)
Source
Shows a browser prompt dialog with the specified message and returns the user's input as a string, or null if the dialog was dismissed.
messageThe message to display in the prompt dialog.The user's input as a string, or null if the dialog was dismissed.
ValueTask DisposeAsync()
Source
Disposes the loaded JavaScript module and releases associated JS resources.
If the module was never loaded, this method completes without action.
Provides extension methods for IEndpointRouteBuilder to map RazorWire endpoints.
IEndpointRouteBuilder MapRazorWire(this IEndpointRouteBuilder endpoints)
Source
Registers a Server-Sent Events (SSE) GET endpoint at the configured streams base path that streams messages for a named channel.
endpointsThe endpoint route builder to configure.The original IEndpointRouteBuilder instance.
The endpoint maps both RazorWire live transport surfaces: a stream endpoint at RazorWireStreamOptions.BasePath plus a form anti-forgery token endpoint at RazorWireFormAntiforgeryOptions.TokenEndpointPath. The stream endpoint enforces channel subscription authorization, streams hub messages as SSE (each line emitted as a data: event), sends a 20-second heartbeat comment when idle, and unsubscribes on client disconnect. A replay query value of 1 or true maps to RazorWireStreamSubscribeOptions.Replay and asks the hub to deliver retained messages before live messages. Replay is disabled when the query is absent or has any other value. The helper that parses this input is intentionally narrow so live delivery remains the default and replay stays a one-time historical catch-up before ongoing stream delivery. The anti-forgery endpoint returns JSON for the runtime's lazy form-token refresh flow, sets no-store cache headers, and applies the configured hybrid CORS policy when one is set. Call RazorWireServiceCollectionExtensions.AddRazorWire before mapping this endpoint so the hub, authorizer, options, and ASP.NET Core anti-forgery services are registered.
Provides extension methods for registering RazorWire services into the IServiceCollection.
IServiceCollection AddRazorWire(this IServiceCollection services, Action<RazorWireOptions>? configure = null)
Source
Registers RazorWire options and default RazorWire services, including IRazorPartialRenderer, into the provided IServiceCollection.
servicesThe service collection to register RazorWire services into.configureOptional action to configure RazorWireOptions; if null, default options are used. Stream subscriptions are denied by default because RazorWireStreamAuthorizationMode.DenyAll is the default authorization mode.The same IServiceCollection instance with RazorWire registrations added.
This method also calls LoggingServiceCollectionExtensions.AddLogging(IServiceCollection) and AntiforgeryServiceCollectionExtensions.AddAntiforgery(IServiceCollection) because RazorWire live streams log denied subscriptions and RazorWire forms use ASP.NET Core anti-forgery services for lazy token refresh. If the host has already configured logging or anti-forgery, the normal ASP.NET Core options pipeline composes with those registrations. If no custom IRazorWireChannelAuthorizer is registered, RazorWire resolves a built-in authorizer from RazorWireOptions.Streams.RazorWireStreamOptions.AuthorizationMode. RazorWireStreamAuthorizationMode.DenyAll selects DenyAllRazorWireChannelAuthorizer, while RazorWireStreamAuthorizationMode.AllowAll selects AllowAllRazorWireChannelAuthorizer. Register a custom IRazorWireChannelAuthorizer before or after this method when stream access depends on the current request, user, tenant, or workflow. Unknown authorization-mode values throw InvalidOperationException during authorizer resolution instead of falling back to an unsafe allow path. New stream authorization code should prefer IRazorWireStreamAuthorizer when it needs unauthenticated, forbidden, stale-session, unsafe-navigation, or setup-failure outcomes. Existing IRazorWireChannelAuthorizer registrations continue to work through a compatibility adapter when no custom result authorizer is registered. A result authorizer registered before this method suppresses the adapter; a result authorizer registered after this method wins through normal Microsoft DI last-registration behavior.
Provides extension methods for MVC controllers to interact with RazorWire.
RazorWireStreamBuilder RazorWireStream(this Controller controller)
Source
Creates a RazorWireStreamBuilder bound to the specified controller.
controllerThe controller instance used to initialize the builder.A RazorWireStreamBuilder configured to operate with the given controller.
A web module that integrates RazorWire real-time streaming and output caching into the application.
void ConfigureWebOptions(StartupContext context, WebOptions options)
Source
Ensures the application's MVC support level is at least ControllersWithViews.
contextThe startup context for the web module.optionsWeb options to configure; may be modified to raise Mvc.MvcSupportLevel to ControllersWithViews if it is lower.void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Registers RazorWire services, enables output caching, and configures output cache options to include RazorWire policies.
contextThe startup context for the current module initialization.servicesThe service collection to which RazorWire, output caching, and related options are added.void RegisterDependentModules(ModuleDependencyBuilder builder)
Source
Registers this module's dependencies with the provided dependency builder.
builderThe dependency builder used to declare other modules this module requires.void ConfigureHostBeforeServices(StartupContext context, Microsoft.Extensions.Hosting.IHostBuilder builder)
Source
Executes module-specific host configuration before application services are registered.
contextThe startup context providing environment and configuration for module initialization.builderThe host builder to apply pre-service host configuration to.The default implementation does nothing.
void ConfigureHostAfterServices(StartupContext context, Microsoft.Extensions.Hosting.IHostBuilder builder)
Source
Provides a hook to modify the host builder after services have been registered.
contextStartup context containing environment and module information.builderThe Microsoft.Extensions.Hosting.IHostBuilder to configure.void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source
Enables output caching in the application's request pipeline.
contextStartup context providing environment and configuration for module initialization.appApplication builder used to configure the HTTP request pipeline.void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source
Maps RazorWire HTTP endpoints into the application's endpoint route builder.
contextThe startup context providing environment and configuration for module initialization.endpointsThe endpoint route builder to which RazorWire routes will be added.In addition to the streaming endpoints, this maps assembly-embedded fallbacks for RazorWire's runtime scripts and package demo assets. Normal ASP.NET Core static web assets still serve these files first when their manifest is available; the endpoint fallback keeps package-hosted tools working when only compiled assemblies are present.
bool IncludeAsApplicationPart { get; }
Source
Gets a value indicating whether this module's assembly should be searched for MVC application parts. Returns true for RazorWire to enable its tag helpers and other components.
Represents configuration options for the RazorWire real-time streaming and caching system.
RazorWireOptions Default { get; }
Source
Gets a default instance of RazorWireOptions with default configuration settings.
RazorWireStreamOptions Streams { get; }
Source
Gets configuration options for real-time streams, such as the base path for stream connections.
RazorWireCacheOptions Caching { get; }
Source
Gets configuration options for output caching policies used by RazorWire.
RazorWireFormOptions Forms { get; }
Source
Gets configuration options for RazorWire-enhanced form submissions.
RazorWireHybridOptions Hybrid { get; }
Source
Gets configuration options for split-origin hybrid deployments.
Represents split-origin hybrid deployment options for RazorWire-managed live interactions.
string? LiveOrigin { get; set; }
Source
Gets or sets the absolute live origin used by exported static pages for RazorWire-managed dynamic calls.
The value must be an origin only, such as https://api.example.com, without a path, query string, fragment, or user information. When unset, RazorWire preserves same-origin runtime behavior.
RazorWireHybridCredentialsMode CredentialsMode { get; set; }
Source
Gets or sets how RazorWire-managed live calls include browser credentials in hybrid deployments. Defaults to RazorWireHybridCredentialsMode.Auto.
string? CorsPolicyName { get; set; }
Source
Gets or sets the optional ASP.NET Core CORS policy applied to RazorWire-owned hybrid endpoints.
Represents configuration options for RazorWire real-time streams.
string BasePath { get; set; }
Source
Gets or sets the base path used for establishing stream connections. Defaults to "/_rw/streams".
The path must start with /, must not end with /, and must not contain route tokens, query strings, fragments, whitespace, or ASCII control characters. RazorWire appends a single validated channel segment to this path when mapping the stream endpoint.
RazorWireStreamAuthorizationMode AuthorizationMode { get; set; }
Source
Gets or sets the built-in authorization behavior for stream subscriptions. Defaults to RazorWireStreamAuthorizationMode.DenyAll.
RazorWire streams are safe by default because channel names frequently encode user, tenant, or workflow context. Use RazorWireStreamAuthorizationMode.AllowAll only for public, demo, or otherwise non-sensitive channels. Register Streams.IRazorWireStreamAuthorizer when subscription decisions must inspect the current HttpContext, user, claims, route data, or tenant state and need result-aware denial semantics. Existing Streams.IRazorWireChannelAuthorizer registrations remain supported for simple legacy allow/deny compatibility.
int MaxChannelNameLength { get; set; }
Source
Gets or sets the maximum channel name length accepted by the stream endpoint. Defaults to DefaultMaxChannelNameLength.
The limit is measured on the decoded route value using .NET string length. Channel names are validated before authorization and admission, and v1 channel names may contain only ASCII letters, ASCII digits, ., _, -, and :. Raise this value only for intentionally finite, namespaced channel schemes.
int MaxLiveChannels { get; set; }
Source
Gets or sets the maximum number of live channel names admitted by one application process. Defaults to DefaultMaxLiveChannels.
This is a per-process guardrail, not a cluster-wide, tenant-wide, user-wide, or load-balancer-wide limit. A live channel is counted only while it has at least one admitted subscription in the current process.
int MaxLiveSubscriptions { get; set; }
Source
Gets or sets the maximum number of live stream subscriptions admitted by one application process. Defaults to DefaultMaxLiveSubscriptions.
A subscription is one admitted SSE request/browser connection. One person can consume multiple subscriptions by opening multiple tabs or pages. This is not a distributed or user-aware quota.
int MaxLiveSubscriptionsPerChannel { get; set; }
Source
Gets or sets the maximum number of live stream subscriptions admitted for one channel by one application process. Defaults to DefaultMaxLiveSubscriptionsPerChannel.
A subscription is one admitted SSE request/browser connection. Use this per-process limit to keep one public channel from consuming all live subscription capacity in the current process.
Represents configuration options for RazorWire output caching.
string PagePolicyName { get; set; }
Source
Gets or sets the name of the output cache policy for full pages. Defaults to "rw-page".
string IslandPolicyName { get; set; }
Source
Gets or sets the name of the output cache policy for individual islands. Defaults to "rw-island".
Represents configuration options for failed rw-active form submissions.
These options control the package convention for server failures from enhanced forms. The global EnableFailureUx switch has highest precedence: when it is false, RazorWire skips request markers, runtime lifecycle events, default fallback rendering, and development anti-forgery diagnostics even if FailureMode or a form-level attribute asks for them. Leave the global switch enabled and use FailureMode or per-form data-rw-form-failure values when an app wants more targeted behavior.
bool EnableFailureUx { get; set; }
Source
Gets or sets a value indicating whether RazorWire emits failed-form request markers, lifecycle hooks, and default failure behavior. Defaults to true.
Set this to false only when the host app owns all failed-form UX. It is a hard kill switch and overrides FailureMode plus any per-form data-rw-form-failure setting.
RazorWireFormFailureMode FailureMode { get; set; }
Source
Gets or sets the package-level failed-form behavior. Defaults to RazorWireFormFailureMode.Auto.
Use RazorWireFormFailureMode.Auto for convention-over-configuration fallback UI, RazorWireFormFailureMode.Manual when the app listens to events and renders its own UI, and RazorWireFormFailureMode.Off when forms should opt into failure handling one at a time.
bool EnableDevelopmentDiagnostics { get; set; }
Source
Gets or sets a value indicating whether development-only diagnostics may be shown. Defaults to true; diagnostics are still emitted only when the host is running in Development.
Diagnostics appear only when failed-form UX is enabled, the app runs in Development, and the failure path can be identified as a RazorWire form request. Production responses stay generic even when this property is true.
string DefaultFailureMessage { get; set; }
Source
Gets or sets the safe default message used for generic failed form submissions.
Null, empty, and whitespace-only assignments are normalized back to RazorWire's safe fallback copy. Use a non-empty value for product-specific recovery language.
RazorWireFormAntiforgeryOptions Antiforgery { get; }
Source
Gets configuration options for RazorWire anti-forgery token refresh behavior.
Represents lazy anti-forgery token refresh options for RazorWire forms.
string TokenEndpointPath { get; set; }
Source
Gets or sets the anti-forgery token refresh endpoint path. Defaults to "/_rw/antiforgery/token".
Defines credential behavior for RazorWire-managed live calls from exported hybrid pages.
The numeric values are explicit because this public enum may be bound from configuration or serialized in export manifests. New values should be appended without changing existing values.
Defines RazorWire's built-in stream subscription authorization behavior.
The numeric values are explicit because this public enum may be persisted, serialized, or bound by applications. New values should be appended without changing the values documented here.
Defines the package-level failed-form behavior for rw-active forms.
This enum only applies when RazorWireFormOptions.EnableFailureUx is enabled. Per-form data-rw-form-failure values may narrow behavior for a specific form, but the global kill switch always wins. The numeric values are explicit because this public enum may be persisted, serialized, or bound by applications. New values should be appended without changing the values documented here.
Defines the RazorWire-owned request marker used by static exporters to request safe auth projection.
The marker is non-secret and only downgrades RazorWire auth projection helpers into static-safe output. It must not be interpreted as authorization, authentication, or permission to render protected content.
Describes RazorWire static export behavior requested for the current HTTP request.
RazorWireStaticExportContext Resolve(HttpContext httpContext)
Source
Resolves static export behavior from the current request headers.
httpContextThe current HTTP context.The resolved static export context.
bool IsStaticAuthProjection { get; }
Source
Gets a value indicating whether auth projection helpers must render static-safe anonymous output.