AppSurface Search
Section API Reference
API Reference Language: C# Component: RazorWire Audience: developer

ForgeTrust.RazorWire

Start here for RazorWire registration, endpoint mapping, safe-by-default stream authorization, options, and stream-result entry points.

Source of truth

View source Edit this page

Last updated

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

Type

RazorWireOptions

Source

Represents configuration options for the RazorWire real-time streaming and caching system.

Property

Default

RazorWireOptions Default { get; } Source

Gets a default instance of RazorWireOptions with default configuration settings.

Property

Streams

RazorWireStreamOptions Streams { get; } Source

Gets configuration options for real-time streams, such as the base path for stream connections.

Property

Caching

RazorWireCacheOptions Caching { get; } Source

Gets configuration options for output caching policies used by RazorWire.

Property

Forms

RazorWireFormOptions Forms { get; } Source

Gets configuration options for RazorWire-enhanced form submissions.

Property

Hybrid

RazorWireHybridOptions Hybrid { get; } Source

Gets configuration options for split-origin hybrid deployments.

Property

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.

Type

RazorWireTurboOptions

Source

Represents the policy for sourcing the Turbo browser runtime used by RazorWire.

Property

RuntimeMode

RazorWireTurboRuntimeMode RuntimeMode { get; set; } Source

Gets or sets who supplies the Turbo browser runtime. Defaults to RazorWireTurboRuntimeMode.Bundled .

Property

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.

Type

RazorWireHybridOptions

Source

Represents split-origin hybrid deployment options for RazorWire-managed live interactions.

Property

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.

Property

CredentialsMode

RazorWireHybridCredentialsMode CredentialsMode { get; set; } Source

Gets or sets how RazorWire-managed live calls include browser credentials in hybrid deployments. Defaults to RazorWireHybridCredentialsMode.Auto .

Property

CorsPolicyName

string? CorsPolicyName { get; set; } Source

Gets or sets the optional ASP.NET Core CORS policy applied to RazorWire-owned hybrid endpoints.

Type

RazorWireStreamOptions

Source

Represents configuration options for RazorWire real-time streams.

Property

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.

Property

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.

Property

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.

Property

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.

Property

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.

Property

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.

Type

RazorWireCacheOptions

Source

Represents configuration options for RazorWire output caching.

Property

PagePolicyName

string PagePolicyName { get; set; } Source

Gets or sets the name of the output cache policy for full pages. Defaults to "rw-page" .

Property

IslandPolicyName

string IslandPolicyName { get; set; } Source

Gets or sets the name of the output cache policy for individual islands. Defaults to "rw-island" .

Type

RazorWireFormOptions

Source

Represents configuration options for rw-active form failure handling and loading feedback.

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 failure behavior. Loading feedback is configured independently through Loading ; disabling failure UX does not disable form loading feedback.

Property

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.

Property

Loading

RazorWireFormLoadingOptions Loading { get; } Source

Gets loading-feedback options for enhanced forms.

Remarks

Loading is independent of EnableFailureUx . When loading is enabled, forms can opt out with data-rw-loading="off" , or override the duplicate-submission default with data-rw-loading-lock="true" or data-rw-loading-lock="false" . Invalid lock values use the global RazorWireFormLoadingOptions.PreventDuplicateSubmissions setting.

Property

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.

Property

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 .

Property

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.

Property

Antiforgery

RazorWireFormAntiforgeryOptions Antiforgery { get; } Source

Gets configuration options for RazorWire anti-forgery token refresh behavior.

Type

RazorWireFormLoadingOptions

Source

Represents package-level loading-feedback settings for enhanced form submissions.

Remarks

Loading feedback applies only to enabled rw-active forms. It is independent of failed-form UX and does not provide server-side idempotency; applications must still protect side-effecting endpoints against duplicate requests.

Property

Enabled

bool Enabled { get; set; } Source

Gets or sets a value indicating whether RazorWire loading feedback is enabled globally. Defaults to true .

Remarks

When disabled, RazorWire does not add its form-loading ownership marker and the loading runtime must not show indicators, the fallback bar, or apply the loading-layer duplicate-submission guard. Failed-form behavior is unaffected.

Property

ShowFallbackBar

bool ShowFallbackBar { get; set; } Source

Gets or sets whether the package-owned top bar is shown when no applicable app-authored loading indicator exists. Defaults to true .

Remarks

A selected app indicator takes precedence over the fallback. When this option is false and no app indicator applies, RazorWire intentionally shows no loading visual for that submission.

Property

PreventDuplicateSubmissions

bool PreventDuplicateSubmissions { get; set; } Source

Gets or sets whether RazorWire blocks a second submission of the same form while its first submission is pending. Defaults to true .

Remarks

A form may override this default with data-rw-loading-lock="true" or data-rw-loading-lock="false" ; invalid values fall back to this setting. This browser-side guard is a user experience feature and does not replace server-side idempotency or other protection for side effects.

Type

RazorWireFormAntiforgeryOptions

Source

Represents lazy anti-forgery token refresh options for RazorWire forms.

Property

TokenEndpointPath

string TokenEndpointPath { get; set; } Source

Gets or sets the anti-forgery token refresh endpoint path. Defaults to "/_rw/antiforgery/token" .

Type

RazorWireWebModule

Source

A web module that integrates RazorWire real-time streaming and output caching into the application.

Method

ConfigureWebOptions

void ConfigureWebOptions(StartupContext context, WebOptions options)
Source

Ensures the application's MVC support level is at least ControllersWithViews.

Parameters

  • context
    The startup context for the web module.
  • options
    Web options to configure; may be modified to raise Mvc.MvcSupportLevel to ControllersWithViews if it is lower.
Method

ConfigureServices

void ConfigureServices(StartupContext context, IServiceCollection services)
Source

Registers RazorWire services, enables output caching, and configures output cache options to include RazorWire policies.

Parameters

  • context
    The startup context for the current module initialization.
  • services
    The service collection to which RazorWire, output caching, and related options are added.
Method

RegisterDependentModules

void RegisterDependentModules(ModuleDependencyBuilder builder)
Source

Registers this module's dependencies with the provided dependency builder.

Parameters

  • builder
    The dependency builder used to declare other modules this module requires.
Method

ConfigureHostBeforeServices

void ConfigureHostBeforeServices(StartupContext context, Microsoft.Extensions.Hosting.IHostBuilder builder)
Source

Executes module-specific host configuration before application services are registered.

Parameters

  • context
    The startup context providing environment and configuration for module initialization.
  • builder
    The host builder to apply pre-service host configuration to.

Remarks

The default implementation does nothing.

Method

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

  • context
    Startup context containing environment and module information.
  • builder
    The Microsoft.Extensions.Hosting.IHostBuilder to configure.
Method

ConfigureWebApplication

void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source

Enables output caching in the application's request pipeline.

Parameters

  • context
    Startup context providing environment and configuration for module initialization.
  • app
    Application builder used to configure the HTTP request pipeline.
Method

ConfigureEndpoints

void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source

Maps RazorWire HTTP endpoints into the application's endpoint route builder.

Parameters

  • context
    The startup context providing environment and configuration for module initialization.
  • endpoints
    The 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, stylesheets, 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.

Property

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.

Type

RazorWireControllerExtensions

Source

Provides extension methods for MVC controllers to interact with RazorWire.

Method

RazorWireStream

RazorWireStreamBuilder RazorWireStream(this Controller controller)
Source

Creates a RazorWireStreamBuilder bound to the specified controller.

Parameters

  • controller
    The controller instance used to initialize the builder.

Returns

A RazorWireStreamBuilder configured to operate with the given controller.

Type

RazorWireServiceCollectionExtensions

Source

Provides extension methods for registering RazorWire services into the IServiceCollection .

Method

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

  • services
    The service collection to register RazorWire services into.
  • configure
    Optional action to configure RazorWireOptions ; if null, default options are used. Stream subscriptions are denied by default because RazorWireStreamAuthorizationMode.DenyAll is the default authorization mode. Configure RazorWireFormOptions.Loading here to change form feedback, fallback-bar, or same-form duplicate-submission defaults. These settings are independent of failed-form UX.

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.

Type

ExampleJsInterop

Source

Provides an example of how JavaScript functionality can be wrapped in a .NET class for easy consumption.

Parameters

  • jsRuntime
    The JS runtime used to invoke JavaScript functions.
Method

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

  • message
    The message to display in the prompt dialog.

Returns

The user's input as a string, or null if the dialog was dismissed.

Method

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.

Type

RazorWireEndpointRouteBuilderExtensions

Source

Provides extension methods for IEndpointRouteBuilder to map RazorWire endpoints.

Method

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

  • endpoints
    The 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.

Type

StringUtils

Source

Provides utility methods for string manipulation, specifically for generating safe identifiers.

Method

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

  • input
    The source string to convert into a safe identifier.
  • appendHash
    If 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.

Method

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

  • input
    The 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.

Type

RazorWireStaticExportRequest

Source

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

Type

RazorWireStaticExportContext

Source

Describes RazorWire static export behavior requested for the current HTTP request.

Method

Resolve

RazorWireStaticExportContext Resolve(HttpContext httpContext)
Source

Resolves static export behavior from the current request headers.

Parameters

  • httpContext
    The current HTTP context.

Returns

The resolved static export context.

Property

IsStaticAuthProjection

bool IsStaticAuthProjection { get; } Source

Gets a value indicating whether auth projection helpers must render static-safe anonymous output.

Enum

RazorWireTurboRuntimeMode

Source

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

Enum

RazorWireHybridCredentialsMode

Source

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

Enum

RazorWireStreamAuthorizationMode

Source

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

Enum

RazorWireFormFailureMode

Source

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

Read next