RazorWireOptions Default { get; }
Source
Gets a default instance of RazorWireOptions with default configuration settings.
ForgeTrust.RazorWire
Start here for RazorWire registration, endpoint mapping, safe-by-default stream authorization, options, and stream-result entry points.
Source of truth
Namespaces
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.
Common entry points
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.
StringUtils
SourceProvides utility methods for string manipulation, specifically for generating safe identifiers.
ToSafeId
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.
Parameters
inputThe source string to convert into a safe identifier.appendHashIf true, appends a short deterministic 4-character lowercase hex hash (prefixed with a hyphen).
Returns
The sanitized identifier; if appendHash is true the value is suffixed with "-" and a 4-character lowercase hex hash.
GetDeterministicHash
string GetDeterministicHash(string input)
Source
Produces a short deterministic 4-character lowercase hexadecimal string derived from the SHA-256 hash of the input.
Parameters
inputThe string to hash.
Returns
A 4-character lowercase hexadecimal string.
Remarks
Returns only the first 4 hex characters (16 bits) of the SHA-256 digest; collisions are possible.
RazorWireOptions
SourceRepresents configuration options for the RazorWire real-time streaming and caching system.
Default
Streams
RazorWireStreamOptions Streams { get; }
Source
Gets configuration options for real-time streams, such as the base path for stream connections.
Caching
RazorWireCacheOptions Caching { get; }
Source
Gets configuration options for output caching policies used by RazorWire.
Forms
RazorWireFormOptions Forms { get; }
Source
Gets configuration options for RazorWire-enhanced form submissions.
Hybrid
RazorWireHybridOptions Hybrid { get; }
Source
Gets configuration options for split-origin hybrid deployments.
Turbo
RazorWireTurboOptions Turbo { get; }
Source
Gets the policy that controls how the Turbo browser runtime is sourced.
Remarks
RazorWire emits its package-owned Turbo runtime by default. Configure this policy when the app publishes a compatible same-origin copy or when the host must own the complete Turbo script tag and its loading order.
RazorWireTurboOptions
SourceRepresents the policy for sourcing the Turbo browser runtime used by RazorWire.
RuntimeMode
RazorWireTurboRuntimeMode RuntimeMode { get; set; }
Source
Gets or sets who supplies the Turbo browser runtime. Defaults to RazorWireTurboRuntimeMode.Bundled.
CustomPath
string? CustomPath { get; set; }
Source
Gets or sets the same-origin, app-absolute Turbo script path used in RazorWireTurboRuntimeMode.Custom mode.
Remarks
The path must be non-root, begin with exactly one /, contain at least one non-empty path segment, and cannot contain empty or dot segments, a query string, fragment, percent encoding, whitespace, or HTML-sensitive characters. RazorWire passes the path through ASP.NET Core static-asset versioning. Leave this value null in bundled and host-managed modes. Use RazorWireTurboRuntimeMode.HostManaged when the host needs a cross-origin URL, integrity metadata, or custom script attributes.
RazorWireHybridOptions
SourceRepresents split-origin hybrid deployment options for RazorWire-managed live interactions.
LiveOrigin
string? LiveOrigin { get; set; }
Source
Gets or sets the absolute live origin used by exported static pages for RazorWire-managed dynamic calls.
Remarks
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.
CredentialsMode
RazorWireHybridCredentialsMode CredentialsMode { get; set; }
Source
Gets or sets how RazorWire-managed live calls include browser credentials in hybrid deployments. Defaults to RazorWireHybridCredentialsMode.Auto.
CorsPolicyName
string? CorsPolicyName { get; set; }
Source
Gets or sets the optional ASP.NET Core CORS policy applied to RazorWire-owned hybrid endpoints.
RazorWireStreamOptions
SourceRepresents configuration options for RazorWire real-time streams.
BasePath
string BasePath { get; set; }
Source
Gets or sets the base path used for establishing stream connections. Defaults to "/_rw/streams".
Remarks
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.
AuthorizationMode
RazorWireStreamAuthorizationMode AuthorizationMode { get; set; }
Source
Gets or sets the built-in authorization behavior for stream subscriptions. Defaults to RazorWireStreamAuthorizationMode.DenyAll.
Remarks
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.
MaxChannelNameLength
int MaxChannelNameLength { get; set; }
Source
Gets or sets the maximum channel name length accepted by the stream endpoint. Defaults to DefaultMaxChannelNameLength.
Remarks
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.
MaxLiveChannels
int MaxLiveChannels { get; set; }
Source
Gets or sets the maximum number of live channel names admitted by one application process. Defaults to DefaultMaxLiveChannels.
Remarks
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.
MaxLiveSubscriptions
int MaxLiveSubscriptions { get; set; }
Source
Gets or sets the maximum number of live stream subscriptions admitted by one application process. Defaults to DefaultMaxLiveSubscriptions.
Remarks
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.
MaxLiveSubscriptionsPerChannel
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.
Remarks
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.
RazorWireCacheOptions
SourceRepresents configuration options for RazorWire output caching.
PagePolicyName
string PagePolicyName { get; set; }
Source
Gets or sets the name of the output cache policy for full pages. Defaults to "rw-page".
IslandPolicyName
string IslandPolicyName { get; set; }
Source
Gets or sets the name of the output cache policy for individual islands. Defaults to "rw-island".
RazorWireFormOptions
SourceRepresents configuration options for failed rw-active form submissions.
Remarks
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.
EnableFailureUx
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.
Remarks
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.
FailureMode
RazorWireFormFailureMode FailureMode { get; set; }
Source
Gets or sets the package-level failed-form behavior. Defaults to RazorWireFormFailureMode.Auto.
Remarks
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.
EnableDevelopmentDiagnostics
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.
Remarks
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.
DefaultFailureMessage
string DefaultFailureMessage { get; set; }
Source
Gets or sets the safe default message used for generic failed form submissions.
Remarks
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.
Antiforgery
RazorWireFormAntiforgeryOptions Antiforgery { get; }
Source
Gets configuration options for RazorWire anti-forgery token refresh behavior.
RazorWireFormAntiforgeryOptions
SourceRepresents lazy anti-forgery token refresh options for RazorWire forms.
TokenEndpointPath
string TokenEndpointPath { get; set; }
Source
Gets or sets the anti-forgery token refresh endpoint path. Defaults to "/_rw/antiforgery/token".
RazorWireTurboRuntimeMode
SourceDefines who supplies the Turbo browser runtime used by RazorWire.
Remarks
The numeric values are explicit because this public enum may be bound from configuration. New values should be appended without changing the values documented here.
RazorWireHybridCredentialsMode
SourceDefines credential behavior for RazorWire-managed live calls from exported hybrid pages.
Remarks
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.
RazorWireStreamAuthorizationMode
SourceDefines RazorWire's built-in stream subscription authorization behavior.
Remarks
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.
RazorWireFormFailureMode
SourceDefines the package-level failed-form behavior for rw-active forms.
Remarks
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.
RazorWireServiceCollectionExtensions
SourceProvides extension methods for registering RazorWire services into the IServiceCollection.
AddRazorWire
IServiceCollection AddRazorWire(this IServiceCollection services, Action<RazorWireOptions>? configure = null)
Source
Registers RazorWire options and default RazorWire services, including IRazorPartialRenderer, into the provided IServiceCollection.
Parameters
servicesThe service collection to register RazorWire services into.configureOptional action to configureRazorWireOptions; if null, default options are used. Stream subscriptions are denied by default becauseRazorWireStreamAuthorizationMode.DenyAllis the default authorization mode.
Returns
The same IServiceCollection instance with RazorWire registrations added.
Remarks
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.
RazorWireWebModule
SourceA web module that integrates RazorWire real-time streaming and output caching into the application.
ConfigureWebOptions
void ConfigureWebOptions(StartupContext context, WebOptions options)
Source
Ensures the application's MVC support level is at least ControllersWithViews.
Parameters
contextThe startup context for the web module.optionsWeb options to configure; may be modified to raise Mvc.MvcSupportLevel to ControllersWithViews if it is lower.
ConfigureServices
void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Registers RazorWire services, enables output caching, and configures output cache options to include RazorWire policies.
Parameters
contextThe startup context for the current module initialization.servicesThe service collection to which RazorWire, output caching, and related options are added.
RegisterDependentModules
void RegisterDependentModules(ModuleDependencyBuilder builder)
Source
Registers this module's dependencies with the provided dependency builder.
Parameters
builderThe dependency builder used to declare other modules this module requires.
ConfigureHostBeforeServices
void ConfigureHostBeforeServices(StartupContext context, Microsoft.Extensions.Hosting.IHostBuilder builder)
Source
Executes module-specific host configuration before application services are registered.
Parameters
contextThe startup context providing environment and configuration for module initialization.builderThe host builder to apply pre-service host configuration to.
Remarks
The default implementation does nothing.
ConfigureHostAfterServices
void ConfigureHostAfterServices(StartupContext context, Microsoft.Extensions.Hosting.IHostBuilder builder)
Source
Provides a hook to modify the host builder after services have been registered.
Parameters
contextStartup context containing environment and module information.builderTheMicrosoft.Extensions.Hosting.IHostBuilderto configure.
ConfigureWebApplication
void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source
Enables output caching in the application's request pipeline.
Parameters
contextStartup context providing environment and configuration for module initialization.appApplication builder used to configure the HTTP request pipeline.
ConfigureEndpoints
void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source
Maps RazorWire HTTP endpoints into the application's endpoint route builder.
Parameters
contextThe startup context providing environment and configuration for module initialization.endpointsThe endpoint route builder to which RazorWire routes will be added.
Remarks
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.
IncludeAsApplicationPart
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.
ExampleJsInterop
SourceProvides an example of how JavaScript functionality can be wrapped in a .NET class for easy consumption.
Parameters
jsRuntimeThe JS runtime used to invoke JavaScript functions.
Prompt
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.
Parameters
messageThe message to display in the prompt dialog.
Returns
The user's input as a string, or null if the dialog was dismissed.
DisposeAsync
ValueTask DisposeAsync()
Source
Disposes the loaded JavaScript module and releases associated JS resources.
Remarks
If the module was never loaded, this method completes without action.
RazorWireStaticExportRequest
SourceDefines the RazorWire-owned request marker used by static exporters to request safe auth projection.
Remarks
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.
RazorWireStaticExportContext
SourceDescribes RazorWire static export behavior requested for the current HTTP request.
Resolve
RazorWireStaticExportContext Resolve(HttpContext httpContext)
Source
Resolves static export behavior from the current request headers.
Parameters
httpContextThe current HTTP context.
Returns
The resolved static export context.
IsStaticAuthProjection
bool IsStaticAuthProjection { get; }
Source
Gets a value indicating whether auth projection helpers must render static-safe anonymous output.
RazorWireControllerExtensions
SourceProvides extension methods for MVC controllers to interact with RazorWire.
RazorWireStream
RazorWireStreamBuilder RazorWireStream(this Controller controller)
Source
Creates a RazorWireStreamBuilder bound to the specified controller.
Parameters
controllerThe controller instance used to initialize the builder.
Returns
A RazorWireStreamBuilder configured to operate with the given controller.
RazorWireEndpointRouteBuilderExtensions
SourceProvides extension methods for IEndpointRouteBuilder to map RazorWire endpoints.
MapRazorWire
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.
Parameters
endpointsThe endpoint route builder to configure.
Returns
The original IEndpointRouteBuilder instance.
Remarks
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.