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

Web

Namespaces

Type

WebApp<TStartup, TModule>

Source

Provides a static entry point for starting a web application with a custom startup class and root module.

Type parameters

  • TStartup
    The type of the custom startup class, inheriting from WebStartup{TModule} .
  • TModule
    The type of the root web module.
Method

RunAsync

Task RunAsync(string[] args, Action<WebOptions>? configureOptions = null)
Source

Asynchronously runs the web application using the specified command-line arguments and optional option configuration.

Parameters

  • args
    The command-line arguments provided at application startup.
  • configureOptions
    An optional delegate to further customize WebOptions during startup.

Returns

A Task representing the asynchronous operation of running the web application.

Type

WebApp<TModule>

Source

Provides a simplified static entry point for starting a web application using a default startup configuration.

Type parameters

  • TModule
    The type of the root web module.
Method

RunAsync

Task RunAsync(string[] args, Action<WebOptions>? configureOptions = null)
Source

Asynchronously runs the web application with a default startup using the specified command-line arguments and optional configuration.

Parameters

  • args
    The command-line arguments provided at application startup.
  • configureOptions
    An optional delegate to customize WebOptions during startup.

Returns

A Task representing the asynchronous operation of running the web application.

Type

MvcOptions

Source

Represents configuration options for ASP.NET Core MVC services and features.

Property

Default

MvcOptions Default { get; } Source

Gets a new default instance of MvcOptions configured with MvcSupport.Controllers .

Property

MvcSupportLevel

MvcSupport MvcSupportLevel { get; init; } Source

Gets the level of MVC support to register (e.g., Controllers only, or Controllers with Views).

Property

ConfigureMvc

Action<IMvcBuilder>? ConfigureMvc { get; init; } Source

Gets an optional delegate for performing advanced configuration of the IMvcBuilder .

Type

PwaHeadMetadataBuilder

Source
Method

Build

string Build(PathString pathBase, PwaOptions options, IFileVersionProvider? fileVersionProvider = null)
Source

Builds the exact encoded PWA head markup shared by the Razor TagHelper and development diagnostics.

Parameters

  • pathBase
    The request path base prepended to app-root-relative values.
  • options
    The validated PWA options.
  • fileVersionProvider
    An optional provider for versioning install icon URLs.

Returns

Encoded head markup, or an empty string when no PWA surface is active.

Type

PwaWorkerPathState

Source

Tracks legacy and current service-worker path assignments without making configuration-provider order observable.

Method

SetLegacyValue

void SetLegacyValue(string value)
Source

Records an explicit assignment through the legacy offline compatibility property.

Parameters

  • value
    The assigned app-root-relative worker path.
Method

SetWorkerValue

void SetWorkerValue(string value)
Source

Records an explicit assignment through the current worker property.

Parameters

  • value
    The assigned app-root-relative worker path.
Property

LegacyWasSet

bool LegacyWasSet { get; set; } Source

Gets a value indicating whether the legacy offline path property was assigned explicitly.

Property

WorkerWasSet

bool WorkerWasSet { get; set; } Source

Gets a value indicating whether the current worker path property was assigned explicitly.

Property

HasConflict

bool HasConflict { get; } Source

Gets a value indicating whether the legacy and current properties were assigned different paths.

Property

EffectiveValue

string EffectiveValue { get; } Source

Gets the current worker path, preferring the current property over the legacy compatibility property.

Type

AppSurfaceCanaryRegistrationOptions

Source

Configures immutable metadata and request-input requirements for a named canary registration.

Remarks

Registration snapshots these values after the callback completes. Retaining and later mutating this options object or its tag set does not change the registered descriptor.

Method

RequireMarker

void RequireMarker()
Source

Makes the marker header required. Repeated calls are idempotent.

Method

RequireFreshSince

void RequireFreshSince()
Source

Makes the freshness header required. Repeated calls are idempotent.

Property

DisplayName

string? DisplayName { get; set; } Source

Gets or sets the nonblank display name. It defaults to the registered name.

Property

Description

string? Description { get; set; } Source

Gets or sets an optional description of at most 512 characters.

Property

Tags

ISet<string> Tags { get; } Source

Gets the mutable registration-time set of lowercase canary metadata tags.

Property

AllowedDetailKeys

ISet<string> AllowedDetailKeys { get; } Source

Gets the mutable registration-time set of detail keys an evaluator may return.

Remarks

Registration snapshots this set. At most sixteen keys may be declared. Keys use the same 1-64 character, lowercase, dot-separated grammar as AppSurfaceCanaryResultOptions.AddDetail . Declaration bounds response shape; it does not classify, sanitize, or redact the values supplied by an application evaluator.

Property

MarkerRequired

bool MarkerRequired { get; set; } Source

Gets a value indicating whether the marker header is required.

Property

FreshSinceRequired

bool FreshSinceRequired { get; set; } Source

Gets a value indicating whether the freshness header is required.

Type

StaticFilesOptions

Source

Represents configuration options for serving static files and web assets.

Property

Default

StaticFilesOptions Default { get; } Source

Gets a default instance of StaticFilesOptions with default configuration settings.

Property

EnableStaticFiles

bool EnableStaticFiles { get; set; } Source

Gets or sets a value indicating whether static files are enabled. This is automatically enabled when MvcSupport.ControllersWithViews or higher is used.

Property

EnableStaticWebAssets

bool EnableStaticWebAssets { get; set; } Source

Gets or sets a value indicating whether static web assets (from RCLs) are enabled. This is automatically enabled in the development environment.

Type

AppSurfaceCanaryEndpointRouteBuilderExtensions

Source

Maps the explicit protected HTTP adapter for registered named canaries.

Method

MapAppSurfaceCanaries

RouteHandlerBuilder MapAppSurfaceCanaries(this IEndpointRouteBuilder endpoints, string authorizationPolicyName, Action<AppSurfaceCanaryEndpointOptions>? configure = null)
Source

Maps the protected named-canary route family: GET /_appsurface/canaries/{name} evaluates one canary and GET /_appsurface/canaries evaluates a bounded aggregate snapshot.

Parameters

  • endpoints
    The endpoint route builder that receives the fixed route family.
  • authorizationPolicyName
    The nonblank host-owned ASP.NET Core authorization policy name.
  • configure
    An optional callback that controls completed-result HTTP status mapping and host-owned snapshot limits. Snapshot concurrency must be 1-64, timeouts must be positive, and the overall timeout must not be shorter than the per-check timeout.

Returns

The handler builder for the fixed detail route GET /_appsurface/canaries/{name} so the host can add ordinary endpoint conventions. The aggregate snapshot route is mapped as part of the same call but is not returned.

Exceptions

  • ArgumentNullException
    endpoints is null.
  • ArgumentException
    The policy name is blank, configured response mode is undefined, or snapshot limits are outside their supported ranges.
  • InvalidOperationException
    Registrations or authorization services are missing, names are duplicated, the route family was already mapped, or mapping through a route group would relocate the fixed route.

Remarks

The default response mode returns 200 for AppSurfaceCanaryStatus.Pass and 503 for every other completed status. Choose AppSurfaceCanaryCompletedResponseMode.AlwaysOk only for authenticated diagnostic consumers that always parse the JSON status. The mapper never configures authentication, authorization, retries, timeouts, triggers, or readiness behavior. Do not append anonymous metadata: the handler detects it and fails closed before name lookup or evaluator invocation. Call this method on the application root; route groups are rejected because they would relocate the fixed route.

Method

TryReadMarker

bool TryReadMarker(HttpContext httpContext, bool required, out string? marker, out IResult? problem)
Source

Reads the optional marker header and enforces the named-canary marker profile.

Parameters

  • httpContext
    The request whose marker header is inspected.
  • required
    Whether a missing or blank marker is invalid.
  • marker
    The single nonblank marker value when one was supplied; otherwise null .
  • problem
    The safe 400 response when validation fails; otherwise null .

Returns

true when the optional value is absent or one valid value of at most 256 UTF-8 bytes is present; otherwise false . Repeated values, malformed Unicode, and control characters are rejected.

Method

TryReadFreshSince

bool TryReadFreshSince(HttpContext httpContext, bool required, out DateTimeOffset? freshSince, out IResult? problem)
Source

Reads the optional freshness header using the strict named-canary RFC 3339 profile.

Parameters

  • httpContext
    The request whose freshness header is inspected.
  • required
    Whether a missing or blank freshness boundary is invalid.
  • freshSince
    The parsed timestamp normalized to UTC when supplied; otherwise null .
  • problem
    The safe 400 response when validation fails; otherwise null .

Returns

true when the optional value is absent or exactly one strict RFC 3339 timestamp with a Z or numeric offset and at most seven fractional digits is present; otherwise false .

Method

ToWireStatus

string ToWireStatus(AppSurfaceCanaryStatus status)
Source

Maps a defined canary status to its stable lowercase wire value.

Parameters

  • status
    The status to map.

Returns

The stable JSON status text.

Exceptions

  • ArgumentOutOfRangeException
    status is undefined.
Type

CanonicalUtcDateTimeOffsetConverter

Source

Reads and writes named-canary timestamps using the canonical UTC wire format.

Type

AppSurfaceCanarySnapshotOptions

Source

Configures bounded execution for GET /_appsurface/canaries .

Remarks

A snapshot is current deploy evidence, not a background job or readiness probe. Cancellation remains cooperative: evaluators that ignore their token can delay the response, but they are never left running after it completes.

Method

Copy

AppSurfaceCanarySnapshotOptions Copy()
Source

Creates an internal immutable-at-mapping copy of these host settings.

Property

MaxSelectedCanaries

int MaxSelectedCanaries { get; set; } Source

Gets or sets the maximum selected canaries. The default is 64 and the supported range is 1-256.

Remarks

MapAppSurfaceCanaries throws ArgumentException when this value is outside its supported range.

Property

MaxConcurrency

int MaxConcurrency { get; set; } Source

Gets or sets the maximum concurrent evaluator invocations. The default is 4 and the supported range is 1-64.

Remarks

MapAppSurfaceCanaries throws ArgumentException when this value is outside its supported range.

Property

PerCheckTimeout

TimeSpan PerCheckTimeout { get; set; } Source

Gets or sets the timeout applied to each started evaluator. The default is 10 seconds; the value must be positive and no greater than OverallTimeout .

Remarks

MapAppSurfaceCanaries throws ArgumentException when this constraint is violated.

Property

OverallTimeout

TimeSpan OverallTimeout { get; set; } Source

Gets or sets the total snapshot admission deadline. The default is 30 seconds; the value must be positive and not shorter than PerCheckTimeout .

Remarks

Reaching this deadline cancels every started evaluator. An evaluator that observes that cancellation reports ASCAN303 ; a separate non-cancellation evaluator failure remains ASCAN301 . MapAppSurfaceCanaries throws ArgumentException when this constraint is violated.

Type

AppSurfaceWebDevelopmentPortDefaults

Source

Resolves a deterministic development port for AppSurface web hosts in development when the caller has not already supplied explicit ASP.NET Core endpoint configuration.

Method

Resolve

AppSurfaceWebDevelopmentPortResolution Resolve(string[] args, string currentDirectory, string applicationBaseDirectory, Func<string, string?> environmentReader, IEnumerable<string>? environmentVariableNames = null)
Source

Applies a deterministic localhost --urls fallback in development when command-line arguments, environment variables, and local appsettings files do not specify where the host should listen.

Parameters

  • args
    The command-line arguments supplied by the caller.
  • currentDirectory
    The current working directory for the process.
  • applicationBaseDirectory
    The application base directory for the host entry assembly.
  • environmentReader
    Reads environment variables needed to detect the environment and explicit endpoint configuration.
  • environmentVariableNames
    The available environment variable names, used to detect named Kestrel endpoint variables.

Returns

A resolution describing the effective arguments. If no fallback was needed, the returned arguments match the supplied args .

Type

AppSurfaceWebDevelopmentPortResolution

Source

Describes the effective command-line arguments after AppSurface web development defaults have been resolved.

Parameters

  • Args
    The effective arguments that should be passed into host startup.
  • AppliedPort
    The fallback port applied by the resolver, if any.
  • SeedPath
    The normalized workspace or project path used to compute the fallback port.
Type

PwaOfflineOptions

Source

Configures AppSurface's explicit starter service-worker strategy.

Remarks

Offline behavior is disabled by default because service workers can create stale or private-content bugs when they cache arbitrary routes. When enabled, the built-in worker caches only OfflineFallbackPath and StaticAssetPaths . It does not cache app navigations, authenticated pages, POST responses, or API data.

Property

Enabled

bool Enabled { get; set; } Source

Gets or sets a value indicating whether AppSurface should map a starter service-worker endpoint.

Property

ServiceWorkerPath

string ServiceWorkerPath { get; set; } Source

Gets or sets the app-root-relative service-worker endpoint path.

Remarks

This compatibility property shares its effective value with PwaOptions.Worker on the instance owned by PwaOptions . New code should configure PwaWorkerOptions.ServiceWorkerPath . Conflicting explicit legacy and current values fail startup.

Property

OfflineFallbackPath

string OfflineFallbackPath { get; set; } Source

Gets or sets the app-root-relative offline fallback page cached by the starter service worker.

Property

StaticAssetPaths

string[] StaticAssetPaths { get; set; } Source

Gets or sets app-root-relative static asset URLs the starter service worker should cache.

Type

AppSurfaceCanaryValidation

Source

Validates named-canary identifiers and snapshots registration options into internal descriptors.

Method

ValidateName

void ValidateName(string name)
Source

Validates a named-canary identifier.

Parameters

  • name
    The identifier to validate.

Exceptions

  • ArgumentNullException
    name is null .
  • ArgumentException
    name violates the grammar or length limit.

Remarks

Names contain 1-128 lowercase ASCII letters or digits in dot-separated segments. Hyphens are allowed only inside a segment, never at an edge. Empty segments and consecutive dots are rejected.

Method

IsValidName

bool IsValidName(string? name)
Source

Determines whether a query name has the same grammar as a registration name.

Method

IsValidTag

bool IsValidTag(string? tag)
Source

Determines whether a query tag has the same grammar as a registration tag.

Method

CreateDescriptor

AppSurfaceCanaryDescriptor CreateDescriptor(string name, Type evaluatorType, AppSurfaceCanaryRegistrationOptions options)
Source

Validates configured metadata and creates an immutable descriptor snapshot.

Parameters

  • name
    The previously validated exact registration name.
  • evaluatorType
    The concrete registered service type expected to implement IAppSurfaceCanaryEvaluator .
  • options
    The non-null completed registration options.

Returns

A descriptor whose tags are deduplicated and stored in ordinal order and whose required-input flags are frozen.

Exceptions

  • ArgumentException
    The display name is blank, the description exceeds 512 characters, a tag violates its 1-64 character lowercase letter/digit/internal-hyphen grammar, more than 16 allowed detail keys are declared, or an allowed detail key is null or violates its 1-64 character lowercase dot-separated grammar. These failures use diagnostic ASCAN101 .
Type

ErrorPagesOptions

Source

Represents configuration options for AppSurface's conventional browser error pages.

Remarks

The default configuration keeps BrowserStatusPageMode at BrowserStatusPageMode.Auto , which enables conventional 401, 403, and 404 browser pages only when MVC support already includes Razor views. Apps that need the HTML status-page experience regardless of their starting MVC mode can opt into BrowserStatusPageMode.Enabled , while API-only or custom status-code handling stacks should use BrowserStatusPageMode.Disabled . Conventional production 500 pages are separate and always require an explicit call to UseConventionalExceptionPage .

Method

UseConventionalBrowserStatusPages

void UseConventionalBrowserStatusPages()
Source

Explicitly enables AppSurface's conventional browser status pages.

Remarks

Use this when an app must always render the conventional HTML 401, 403, and 404 pages. AppSurface may effectively require controllers with views at startup so the configured Razor pages can execute.

Method

DisableBrowserStatusPages

void DisableBrowserStatusPages()
Source

Explicitly disables AppSurface's conventional browser status pages.

Remarks

Use this for APIs, custom status-code middleware, or any app that wants to keep conventional browser status routes and handling out of the pipeline even when MVC view support is available.

Method

UseConventionalExceptionPage

void UseConventionalExceptionPage()
Source

Explicitly enables AppSurface's conventional production exception page.

Remarks

Use this for browser-facing apps that want AppSurface to own the production 500 page through ASP.NET Core exception handling. The page renders only safe generic copy plus a request id, and AppSurface leaves Development behavior alone so developer exception diagnostics can remain active during local work. API-only apps or applications with custom exception middleware should leave this disabled and register their own handling before application endpoints.

Method

DisableConventionalExceptionPage

void DisableConventionalExceptionPage()
Source

Explicitly disables AppSurface's conventional production exception page.

Remarks

Use this when a module enables the conventional exception page but the application host needs to supply a different exception-handling policy, such as JSON problem details, tenant-specific pages, or telemetry-first middleware.

Method

AreConventionalBrowserStatusPagesEnabled

bool AreConventionalBrowserStatusPagesEnabled(MvcSupport mvcSupportLevel)
Source

Determines whether AppSurface should enable conventional browser status pages for the supplied MVC support level.

Parameters

  • mvcSupportLevel
    The MVC capability currently configured for the app.

Returns

true when the conventional page should be active; otherwise, false .

Remarks

This helper is used by AppSurface startup after module and app options are applied. In BrowserStatusPageMode.Auto , the feature only turns on when MVC already includes views. In BrowserStatusPageMode.Enabled , the feature is active regardless of the incoming MVC level because startup may upgrade the app to support Razor views.

Property

Default

ErrorPagesOptions Default { get; } Source

Gets a default instance of ErrorPagesOptions with BrowserStatusPageMode.Auto .

Property

BrowserStatusPageMode

BrowserStatusPageMode BrowserStatusPageMode { get; set; } Source

Gets or sets the conventional browser status page behavior for the application.

Remarks

BrowserStatusPageMode.Auto is the default and turns the feature on only when the app's MVC support reaches MvcSupport.ControllersWithViews . Choosing BrowserStatusPageMode.Enabled can cause AppSurface startup to upgrade MVC support so the conventional Razor views can render. Choosing BrowserStatusPageMode.Disabled prevents the reserved framework routes and browser-oriented status handling from activating.

Property

ConventionalExceptionPageEnabled

bool ConventionalExceptionPageEnabled { get; set; } Source

Gets or sets a value indicating whether AppSurface should render the conventional production exception page.

Remarks

The default is false so apps do not accidentally replace an existing exception-handling policy. Set this through UseConventionalExceptionPage when browser users should see a safe, generic HTML 500 page for unhandled exceptions in non-development environments. AppSurface uses ASP.NET Core's exception-handler middleware for this feature; status-code pages cannot catch thrown exceptions.

Type

PwaWorkerOptions

Source

Configures the shared AppSurface service-worker and registration-helper endpoints.

Remarks

The worker is mapped when either PwaOfflineOptions.Enabled or PwaPushOptions.Enabled is enabled. Worker activation is independent from install-manifest metadata.

Property

ServiceWorkerPath

string ServiceWorkerPath { get; set; } Source

Gets or sets the app-root-relative generated service-worker endpoint path.

Remarks

The default is /service-worker.js . On the instance owned by PwaOptions , this setting is compatible with PwaOfflineOptions.ServiceWorkerPath . Configuring both properties with different values fails startup instead of depending on configuration-provider assignment order. Percent escapes are rejected because this value owns a generated endpoint.

Property

RegistrationHelperPath

string RegistrationHelperPath { get; set; } Source

Gets or sets the app-root-relative endpoint for the inert registration helper.

Remarks

The default is /_appsurface/pwa/register.js . The helper is mapped only when push is enabled. Percent escapes are rejected because this value owns a generated endpoint.

Property

HasServiceWorkerPathConflict

bool HasServiceWorkerPathConflict { get; } Source

Gets a value indicating whether legacy and current worker path properties were assigned conflicting values.

Type

AppSurfaceCanaryServiceCollectionExtensions

Source

Registers application-owned named canary evaluators and immutable metadata.

Method

AddAppSurfaceCanary

IServiceCollection AddAppSurfaceCanary<TEvaluator>(this IServiceCollection services, string name, Action<AppSurfaceCanaryRegistrationOptions>? configure = null)
Source

Registers one typed evaluator under an exact lowercase, dot-separated canary name.

Type parameters

  • TEvaluator
    The concrete application-owned evaluator type.

Parameters

  • services
    The service collection to update after validation succeeds.
  • name
    The unique 1-128 character canary name.
  • configure
    An optional callback that configures registration metadata, required inputs, and allowed result-detail keys.

Returns

The original service collection.

Exceptions

  • ArgumentNullException
    services or name is null.
  • ArgumentException
    The name, configured registration metadata, or allowed detail-key declaration is invalid.

Remarks

Registration does not expose an HTTP endpoint. Call AppSurfaceCanaryEndpointRouteBuilderExtensions.MapAppSurfaceCanaries explicitly with a host-owned authorization policy. The evaluator is added as transient only when the host has not already registered the concrete type, so singleton, scoped, and transient overrides are supported.

Type

BrowserStatusPageDefaults

Source

Defines the conventional paths used by AppSurface's built-in browser-friendly status page handling.

Remarks

AppSurface owns browser status pages for 401, 403, and 404 responses in this release. Production exception pages, including conventional 500 handling, are intentionally separate because ASP.NET Core routes exceptions through exception-handling middleware instead of status-code pages.

Method

GetAppViewPath

string GetAppViewPath(int statusCode)
Source

Formats the conventional app override view path for the supplied HTTP status code.

Parameters

  • statusCode
    The integer HTTP status code used for the view filename. AppSurface currently renders 401, 403, and 404.

Returns

The app/shared Razor view path produced from AppViewPathFormat .

Remarks

This helper does not validate support. Callers that accept arbitrary status codes should use BrowserStatusPageDescriptor.TryGet(int, out BrowserStatusPageDescriptor) before rendering.

Method

GetReservedRoute

string GetReservedRoute(int statusCode)
Source

Formats the framework-reserved preview route for the supplied HTTP status code.

Parameters

  • statusCode
    The integer HTTP status code used for the reserved route segment. AppSurface currently renders 401, 403, and 404.

Returns

The reserved route produced from ReservedRouteFormat .

Remarks

The returned path is for framework middleware, direct preview, and tooling such as static export. It should not be exposed as an application-owned route.

Type

AppSurfaceHealthEndpointDefaults

Source

Provides the default AppSurface Web platform probe endpoint paths.

Type

PwaIcon

Source

Declares one icon entry emitted into the generated PWA manifest and optional page head metadata.

Remarks

Source must be an app-root-relative path such as /icons/app-192.png . AppSurface validates the declared Sizes token values and exposes them in diagnostics, but it does not decode image dimensions at runtime. Use appsurface pwa verify to prove icon URLs are reachable and decode PNG dimensions from a running app.

Property

Source

string Source { get; set; } Source

Gets or sets the app-root-relative icon URL.

Property

Sizes

string Sizes { get; set; } Source

Gets or sets the manifest size token list, for example 192x192 or 192x192 512x512 .

Property

Type

string Type { get; set; } Source

Gets or sets the icon content type. Defaults to image/png .

Property

Purpose

string? Purpose { get; set; } Source

Gets or sets the optional manifest purpose, for example any or maskable .

Type

PwaScriptAssets

Source
Method

Read

string Read(Assembly assembly, string fileName)
Source

Reads a named PWA resource from an assembly.

Parameters

  • assembly
    The assembly that owns the embedded PWA resource.
  • fileName
    The final file name beneath the embedded Assets.Pwa namespace.

Returns

The UTF-8 resource contents.

Exceptions

  • InvalidOperationException
    The named resource cannot be found or opened.
Property

WorkerShared

string WorkerShared { get; } Source

Gets the shared service-worker lifecycle source.

Property

WorkerOffline

string WorkerOffline { get; } Source

Gets the optional offline capability source.

Property

WorkerPush

string WorkerPush { get; } Source

Gets the default version-1 push and notification-click source.

Property

WorkerCustomHandler

string WorkerCustomHandler { get; } Source

Gets the contained custom push-handler import source.

Property

RegistrationHelper

string RegistrationHelper { get; } Source

Gets the inert browser registration-helper source.

Property

BadgingFactory

string BadgingFactory { get; } Source

Gets the canonical badging installer factory shared by page and worker wrappers.

Property

BadgingHelper

string BadgingHelper { get; } Source

Gets the inert browser badging-helper source.

Property

WorkerBadging

string WorkerBadging { get; } Source

Gets the generated-worker badging adapter source.

Property

PathValidationVectors

string PathValidationVectors { get; } Source

Gets the shared C# and JavaScript path-validation vectors.

Property

RegistrationHelperVersion

string RegistrationHelperVersion { get; } Source

Gets the content-derived cache version for the registration helper.

Property

BadgingHelperVersion

string BadgingHelperVersion { get; } Source

Gets the content-derived cache version for the badging page helper.

Type

AppSurfaceCanaryRouteMetadata

Source

Marks the single framework-owned endpoint in the reserved named-canary namespace.

Property

Instance

AppSurfaceCanaryRouteMetadata Instance { get; } Source

Gets the shared marker instance attached to the package-owned endpoint.

Type

AppSurfaceCanaryEvaluationRunner

Source

Runs one transport-neutral named-canary lookup and evaluation in the current service scope.

Method

EvaluateAsync

2 overloads
ValueTask<AppSurfaceCanaryEvaluationOutcome> EvaluateAsync(string name, string? marker, DateTimeOffset? freshSince, CancellationToken cancellationToken)
Source

Looks up and evaluates one registered name without applying HTTP status mapping.

Parameters

  • name
    The exact canary name to find.
  • marker
    The optional opaque marker.
  • freshSince
    The optional freshness boundary.
  • cancellationToken
    The evaluation cancellation token.

Returns

A not-found outcome or the evaluator result wrapped as a completed outcome.

ValueTask<AppSurfaceCanaryResult> EvaluateAsync(AppSurfaceCanaryDescriptor descriptor, string? marker, DateTimeOffset? freshSince, CancellationToken cancellationToken)
Source

Resolves and invokes the evaluator represented by a known descriptor in the current service scope.

Parameters

  • descriptor
    The non-null registered descriptor.
  • marker
    The optional opaque marker.
  • freshSince
    The optional freshness boundary.
  • cancellationToken
    The evaluation cancellation token.

Returns

The non-null evaluator result, including any validated optional evidence.

Exceptions

  • ArgumentNullException
    descriptor is null .
  • InvalidOperationException
    The evaluator returns null or includes a detail key absent from the descriptor's declared allowed keys.
Method

TryGetDescriptor

bool TryGetDescriptor(string name, out AppSurfaceCanaryDescriptor descriptor)
Source

Attempts exact ordinal lookup without resolving an evaluator.

Parameters

  • name
    The exact registered name.
  • descriptor
    The descriptor when found.

Returns

true when the name is registered; otherwise false .

Type

AppSurfaceCanaryEvaluationOutcome

Source

Represents either an exact-name miss or a completed transport-neutral evaluation.

Method

Completed

AppSurfaceCanaryEvaluationOutcome Completed(AppSurfaceCanaryResult result)
Source

Creates an outcome for a non-null completed evaluator result.

Parameters

  • result
    The completed evaluator result.

Returns

A found outcome containing result .

Property

NotFound

AppSurfaceCanaryEvaluationOutcome NotFound { get; } Source

Gets the shared exact-name miss outcome.

Property

Found

bool Found { get; } Source

Gets a value indicating whether a registered descriptor was found.

Property

Result

AppSurfaceCanaryResult? Result { get; } Source

Gets the completed result, or null for NotFound .

Type

PwaBadgingOptions

Source

Configures the opt-in AppSurface browser adapter for the Progressive Web App Badging API.

Remarks

Badging is a write-only progressive enhancement. AppSurface validates calls and normalizes value-free outcomes, but it does not own the badge count, request permission, persist state, or prove that an operating system displayed a badge. Applications must keep an accessible in-app representation of the same attention state.

Property

Enabled

bool Enabled { get; set; } Source

Gets or sets a value indicating whether AppSurface should expose the page badging helper and compose the same adapter into an already-enabled AppSurface worker.

Remarks

Enabling badging alone does not create a service worker or enable static-file middleware.

Property

HelperPath

string HelperPath { get; set; } Source

Gets or sets the app-root-relative generated page-helper endpoint path.

Remarks

The generated endpoint is served only when Enabled is enabled. Paths reject percent escapes and other ambiguous URL forms so routing, emitted head markup, and diagnostics use one representation.

Type

AppSurfaceCanaryDescriptor

Source

Stores an immutable named-canary registration without resolving its evaluator.

Property

Name

string Name { get; } Source

Gets the validated exact registration name.

Property

DisplayName

string DisplayName { get; } Source

Gets the nonblank adopter-facing display name.

Property

Description

string? Description { get; } Source

Gets the optional description.

Property

Tags

IReadOnlySet<string> Tags { get; } Source

Gets the immutable ordinal-sorted tag snapshot.

Property

MarkerRequired

bool MarkerRequired { get; } Source

Gets a value indicating whether the marker input is required.

Property

FreshSinceRequired

bool FreshSinceRequired { get; } Source

Gets a value indicating whether the freshness boundary is required.

Property

AllowedDetailKeys

IReadOnlySet<string> AllowedDetailKeys { get; } Source

Gets the immutable ordinal set of detail keys this evaluator may return.

Property

EvaluatorType

Type EvaluatorType { get; } Source

Gets the concrete evaluator service type resolved for each evaluation.

Type

PwaOptions

Source

Configures independent AppSurface Progressive Web App install, offline, push-worker, and badging capabilities.

Remarks

Set Enabled to true when AppSurface should emit and serve install metadata for a web app. Required metadata mirrors the browser-facing manifest fields that make install posture understandable: names, start URL, scope, display mode, theme/background colors, and 192x192 plus 512x512 icons. AppSurface maps diagnostics separately from install metadata so production apps can hide diagnostics while still serving the manifest. Offline and push capabilities activate one shared worker without requiring install metadata. Badging exposes a page helper independently and joins that worker only when another capability already activates it.

Property

Default

PwaOptions Default { get; } Source

Gets a default disabled PWA options instance.

Property

Enabled

bool Enabled { get; set; } Source

Gets or sets a value indicating whether AppSurface should map PWA install-manifest metadata endpoints.

Remarks

This setting does not suppress Offline or Push when either capability is enabled.

Property

ManifestPath

string ManifestPath { get; set; } Source

Gets or sets the app-root-relative generated manifest endpoint path.

Remarks

Generated endpoint paths reject percent escapes so routing and emitted metadata use one representation. This path remains validated and appears PathBase-adjusted in diagnostics whenever any PWA surface is active, although the manifest endpoint is mapped only when Enabled is enabled.

Property

DiagnosticsExposure

PwaDiagnosticEndpointExposure DiagnosticsExposure { get; set; } Source

Gets or sets when the PWA diagnostics endpoint should be mapped.

Property

DiagnosticsPath

string DiagnosticsPath { get; set; } Source

Gets or sets the app-root-relative diagnostics endpoint path.

Remarks

Generated endpoint paths reject percent escapes so routing and emitted metadata use one representation.

Property

Name

string Name { get; set; } Source

Gets or sets the full application name emitted into the manifest.

Property

ShortName

string ShortName { get; set; } Source

Gets or sets the short application name emitted into the manifest.

Property

StartUrl

string StartUrl { get; set; } Source

Gets or sets the app-root-relative start URL emitted into the manifest.

Property

Scope

string Scope { get; set; } Source

Gets or sets the app-root-relative manifest and service-worker scope.

Remarks

The default is / . The scope is validated whenever install metadata or a worker capability is active. Browsers use raw URL-prefix matching, so /app also covers /application ; use /app/ when a path-segment boundary is intended.

Property

Display

PwaDisplayMode Display { get; set; } Source

Gets or sets the display mode emitted into the manifest.

Property

ThemeColor

string ThemeColor { get; set; } Source

Gets or sets the manifest and browser theme color as a CSS hex color.

Property

BackgroundColor

string BackgroundColor { get; set; } Source

Gets or sets the manifest background color as a CSS hex color.

Property

Icons

IList<PwaIcon> Icons { get; } Source

Gets or sets the icon entries emitted into the generated manifest.

Property

Worker

PwaWorkerOptions Worker { get; } Source

Gets shared service-worker and registration-helper endpoint settings.

Property

Offline

PwaOfflineOptions Offline { get; } Source

Gets explicit offline strategy settings.

Property

Push

PwaPushOptions Push { get; } Source

Gets opt-in Web Push worker settings.

Property

Badging

PwaBadgingOptions Badging { get; } Source

Gets opt-in application-icon badging settings.

Property

IsWorkerEnabled

bool IsWorkerEnabled { get; } Source

Gets whether at least one capability requires the shared service worker.

Property

HasAnySurfaceEnabled

bool HasAnySurfaceEnabled { get; } Source

Gets whether AppSurface should validate and map any PWA surface.

Property

HasAnyGeneratedScriptRoute

bool HasAnyGeneratedScriptRoute { get; } Source

Gets whether at least one active capability maps a generated JavaScript route.

Property

RequiresStaticFileMiddleware

bool RequiresStaticFileMiddleware { get; } Source

Gets whether the configured PWA surfaces require AppSurface to enable static-file middleware.

Remarks

Install metadata preserves the existing static-icon behavior, offline support may reference static fallback assets, and a custom push handler may be deployed from the web root. The generated default push worker and registration helper are endpoints and do not require static-file middleware.

Type

ExceptionPageModel

Source

Represents the model passed to AppSurface's conventional production exception view.

Parameters

  • StatusCode
    The HTTP status code being rendered.
  • RequestId
    The request identifier that app logs can use to correlate the failure.

Remarks

This model intentionally excludes exception details, request headers, cookies, route values, and form fields. Production error pages should help users recover and help operators correlate logs without disclosing request internals or implementation details.

Type

IAppSurfaceWebModule

Source

Defines a module that exposes web-specific configuration, endpoints, and middleware.

Method

ConfigureWebOptions

void ConfigureWebOptions(StartupContext context, WebOptions options)
Source

Configures WebOptions for the application, such as MVC, CORS, and static files.

Parameters

  • context
    The startup context for the application.
  • options
    The options to be configured.
Method

ConfigureEndpoints

void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source

Allows the module to configure endpoint routes for the application.

Parameters

  • context
    Startup context providing environment and configuration for the module.
  • endpoints
    Endpoint route builder used to map endpoints (routes, hubs, etc.).
Method

ConfigureWebApplication

void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source

Configure the ASP.NET Core request pipeline for this module.

Parameters

  • context
    Startup information and services available to the module during application initialization.
  • app
    The application's request pipeline builder used to register middleware, routing, and other pipeline components.
Method

ConfigureEndpointAwareMiddleware

void ConfigureEndpointAwareMiddleware(StartupContext context, IApplicationBuilder app)
Source

Configures middleware that can inspect endpoint routing metadata before endpoints execute.

Parameters

  • context
    Startup information and services available to the module during application initialization.
  • app
    The application's request pipeline builder used to register endpoint-aware middleware.

Remarks

AppSurface invokes this hook after UseRouting and AppSurface-managed CORS middleware, and before UseEndpoints . Middleware registered here can inspect HttpContext.GetEndpoint() at request time, but unmatched requests can still have no selected endpoint. Root or host integration modules should register global authentication and authorization middleware here before feature modules add endpoint-aware middleware they own. Do not call UseRouting , UseCors , UseEndpoints , or map endpoints from this hook; use ConfigureEndpoints for endpoint mapping.

Property

IncludeAsApplicationPart

bool IncludeAsApplicationPart { get; } Source

Gets a value indicating whether this module's assembly should be searched for MVC application parts (controllers, views, etc.). Defaults to false.

Type

AppSurfaceCanaryMappingState

Source

Coordinates the process-wide single mapping claim and startup validator activation.

Method

TryClaim

bool TryClaim(ICollection<Microsoft.AspNetCore.Routing.EndpointDataSource> dataSources)
Source

Atomically claims named-canary mapping for one endpoint data-source collection.

Parameters

  • dataSources
    The application-root data sources inspected by the startup validator.

Returns

true for the first claim; otherwise false without replacing the collection captured by the first caller.

Exceptions

  • ArgumentNullException
    dataSources is null .
Property

DataSources

ICollection<Microsoft.AspNetCore.Routing.EndpointDataSource>? DataSources { get; } Source

Gets the endpoint data-source collection captured by the first successful mapping claim, or null before named canaries are mapped.

Type

AppSurfaceCanaryEvaluationFailurePolicy

Source

Classifies evaluator failures that package-owned HTTP and snapshot adapters can convert into safe failures.

Method

IsNonFatal

bool IsNonFatal(Exception exception)
Source

Determines whether an evaluator failure can be converted into a safe package-owned failure response.

Parameters

  • exception
    The exception raised during evaluator activation or execution.

Returns

false for fatal process/runtime exceptions; otherwise true .

Type

AppSurfaceCanaryEvaluationContext

Source

Contains the validated inputs for one named canary evaluation.

Property

Name

string Name { get; } Source

Gets the exact registered canary name.

Property

Marker

string? Marker { get; } Source

Gets the optional opaque deploy marker exactly as supplied to this context. The HTTP adapter preserves the value delivered by ASP.NET Core; HTTP servers and clients may normalize leading or trailing field-value whitespace.

Property

FreshSince

DateTimeOffset? FreshSince { get; } Source

Gets the optional freshness boundary normalized by the HTTP adapter to UTC.

Type

AppSurfaceCanaryStartupValidator

Source

Validates the final endpoint pipeline before server startup, rejecting a relocated framework route or host-owned routes that could shadow or overlap the reserved named-canary namespace.

Method

Configure

Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
Source

Appends reserved-route validation after the host finishes composing its pipeline.

Parameters

  • next
    The remaining startup-filter pipeline.

Returns

A pipeline action that invokes next before validating final endpoints.

Exceptions

  • ArgumentNullException
    next is null .
Method

Validate

void Validate()
Source

Validates that the framework route retained its fixed location and that no host route overlaps the reserved named-canary namespace. The method is inactive before mapping captures endpoint data sources.

Exceptions

  • InvalidOperationException
    The framework route was relocated or another route overlaps the reserved namespace.
Method

Normalize

string Normalize(string? route)
Source

Normalizes a defensive route value for ordinal reserved-namespace comparison.

Parameters

  • route
    The possibly blank route text.

Returns

A leading-slash route with trailing slashes removed, or / for a blank value.

Type

IAppSurfaceCanaryEvaluator

Source

Evaluates application-owned proof for one registered named canary.

Remarks

Evaluators inspect existing proof exactly once per request. They should not trigger synthetic work, retry, poll, or change application readiness. The caller owns those orchestration decisions.

Method

EvaluateAsync

ValueTask<AppSurfaceCanaryResult> EvaluateAsync(AppSurfaceCanaryEvaluationContext context, CancellationToken cancellationToken)
Source

Evaluates current proof for a named canary.

Parameters

  • context
    The validated canary name and optional deploy-proof inputs.
  • cancellationToken
    The request cancellation token.

Returns

The current canary status plus any optional validated, bounded evidence.

Type

PwaPathBase

Source

Resolves app-root-relative PWA paths beneath the current request path base.

Method

Add

string Add(PathString pathBase, string path)
Source

Prepends pathBase to the app-root-relative path .

Parameters

  • pathBase
    The current request path base.
  • path
    The app-root-relative path to resolve.

Returns

The path resolved beneath pathBase .

Type

PwaStaticFileShadowValidator

Source
Method

ThrowIfInvalid

void ThrowIfInvalid(PwaOptions options, IFileProvider webRootFileProvider)
Source

Rejects generated worker/helper routes that static-file middleware would serve first.

Parameters

  • options
    The validated PWA options.
  • webRootFileProvider
    The effective web-root file provider.
Type

PwaPushOptions

Source

Configures opt-in Web Push event handling in the shared AppSurface service worker.

Remarks

Enabling push maps worker plumbing and the explicit registration helper. It does not request notification permission, create a push subscription, store subscriber identity, or send notifications.

Property

Enabled

bool Enabled { get; set; } Source

Gets or sets a value indicating whether the generated worker should support push events.

Property

HandlerScriptPath

string? HandlerScriptPath { get; set; } Source

Gets or sets an optional app-root-relative classic worker script that owns push and notification-click events.

Remarks

Leave this value null to use AppSurface's strict version-1 notification adapter. When set, AppSurface imports the script with importScripts() and does not emit its default push or click listeners. AppSurface contains a load or top-level evaluation failure with ASPWAJS030 so shared lifecycle and offline behavior remain available. The application should still deploy this asset atomically. Browser script evaluation is not transactional, so a handler must finish validation and initialization before registering listeners that would otherwise survive a later top-level exception.

Type

AppSurfaceConfigAuditDiagnosticsDefaults

Source

Provides defaults for AppSurface configuration-audit HTTP diagnostics endpoints.

Remarks

Use DefaultRoute when a host wants the standard opt-in AppSurface diagnostics path. Prefer a custom route with AppSurfaceConfigAuditDiagnosticsEndpointRouteBuilderExtensions.MapAppSurfaceConfigAuditDiagnostics(Microsoft.AspNetCore.Routing.IEndpointRouteBuilder, string, string) when the deployment already reserves this prefix or needs diagnostics to live under a host-owned operations path. Configuration audit output is support-sensitive even after value redaction, and the mapper hides the endpoint from API Explorer/OpenAPI by default instead of treating it as a public discovery surface.

Type

HealthOptions

Source

Configures AppSurface Web platform health and readiness probe endpoints.

Remarks

Enable this surface when container or service-platform probes will consume it. The endpoints use ASP.NET Core health checks. HealthPath runs all checks; ReadyPath runs checks tagged with ReadyTag . If no checks are tagged for readiness, the readiness endpoint reports healthy once the app has started. When disabled, AppSurface does not register health-check services or map probe endpoints.

Property

Default

HealthOptions Default { get; } Source

Gets a default disabled health options instance.

Property

Enabled

bool Enabled { get; set; } Source

Gets or sets a value indicating whether AppSurface should map platform health and readiness endpoints.

Remarks

The default is false . Enable probes only when deployment or monitoring infrastructure consumes them; enabling registers ASP.NET Core health-check services and maps both configured endpoints.

Property

HealthPath

string HealthPath { get; set; } Source

Gets or sets the app-root-relative endpoint path that runs all registered ASP.NET Core health checks.

Property

ReadyPath

string ReadyPath { get; set; } Source

Gets or sets the app-root-relative endpoint path that runs readiness-tagged ASP.NET Core health checks.

Property

ReadyTag

string ReadyTag { get; set; } Source

Gets or sets the health-check tag used to select checks for the readiness endpoint.

Type

BrowserStatusPageRenderer

Source

Resolves and renders AppSurface's conventional browser status page views.

Remarks

View resolution prefers the status-specific app/shared Razor Class Library path first, for example ~/Views/Shared/403.cshtml . If that view is missing, the renderer falls back to AppSurface's shared framework view. Resolved paths are cached per status code so a 401 override cannot accidentally satisfy a later 403 or 404 render.

Method

ValidateConfiguredViews

void ValidateConfiguredViews()
Source

Performs eager validation of all configured conventional browser status page views.

Remarks

Call this during startup to fail fast if neither the conventional app/shared view nor the framework fallback view can be resolved for any supported status. Runtime rendering also resolves lazily, but this method turns a missing view into a predictable startup error instead of a request-time failure. Validation also warms and pins the runtime view-path cache by resolving every BrowserStatusPageDescriptor.Supported entry. If an app adds or removes status page views after this method runs, the startup-selected app or framework fallback path remains in use for the process lifetime.

Method

RenderAsync

Task RenderAsync(HttpContext httpContext)
Source

Renders the resolved conventional browser status page view into the current HTTP response.

Parameters

  • httpContext
    The current request context used to build the model and execute the Razor view.

Remarks

The rendered model is always a BrowserStatusPageModel . Its status defaults to 404 when the request is a direct render without a re-execute feature or reserved-route status code. This method does not change HttpResponse.StatusCode itself, which lets direct previews keep their existing 200 response and re-executed status requests preserve their original HTTP status. CreateModel(HttpContext) can receive an explicit status from re-execution metadata or the reserved route. That status must be supported by BrowserStatusPageDescriptor ; otherwise this method throws instead of rendering a mismatched page for the existing HttpResponse.StatusCode .

Type

ConventionalExceptionPageRenderer

Source

Resolves and renders AppSurface's conventional production exception page view.

Remarks

View resolution prefers ConventionalExceptionPageDefaults.AppViewPath first so apps and shared Razor Class Libraries can override the page conventionally. If that view is missing, the renderer falls back to ConventionalExceptionPageDefaults.FrameworkFallbackViewPath . The rendered model is deliberately small and safe: status code plus request id only.

Method

ValidateConfiguredViews

void ValidateConfiguredViews()
Source

Performs eager validation of the configured conventional 500 view.

Remarks

Call this during startup to fail fast in production-like environments if neither the conventional app/shared view nor the framework fallback view can be resolved. Runtime rendering also resolves lazily, but this method turns a missing view into a predictable startup error instead of a request-time failure.

Method

RenderAsync

Task RenderAsync(HttpContext httpContext)
Source

Renders the resolved conventional 500 view into the current HTTP response.

Parameters

  • httpContext
    The current request context used to build the model and execute the Razor view.

Remarks

This method sets the response status to 500 and passes only ExceptionPageModel to the view. It intentionally does not inspect IExceptionHandlerFeature or request data, so exception messages, stack traces, headers, cookies, route values, and form values cannot be disclosed through the default model.

Type

AppSurfaceCanaryResult

Source

Represents the immutable result of one named canary evaluation.

Property

Status

AppSurfaceCanaryStatus Status { get; } Source

Gets the current canary status.

Property

ObservedAt

DateTimeOffset? ObservedAt { get; } Source

Gets the optional proof-observation time normalized to UTC.

Property

MatchedCount

int? MatchedCount { get; } Source

Gets the optional non-negative count of matching proofs.

Property

ReasonCode

string? ReasonCode { get; } Source

Gets the optional stable machine-readable response reason: 1-64 lowercase ASCII letters or digits separated by internal hyphens, with an alphanumeric first and last character.

Property

Summary

string? Summary { get; } Source

Gets optional response-only operator-safe explanatory text that is nonblank, at most 256 UTF-8 bytes, well-formed Unicode, and free of Unicode control ( Cc ) scalars.

Property

CorrelationId

string? CorrelationId { get; } Source

Gets the optional response-only non-secret correlation identifier: 1-128 ASCII letters, digits, periods, underscores, colons, or hyphens, with an alphanumeric first and last character.

Property

Details

IReadOnlyDictionary<string, string> Details { get; } Source

Gets up to 16 immutable, ordinal-sorted response-only details. Keys use 1-64 character lowercase dot-separated segments; values are nonblank, at most 128 UTF-8 bytes, well-formed Unicode, and free of Unicode control ( Cc ) scalars.

Type

AppSurfaceCanaryEndpointOptions

Source

Configures the HTTP adapter for named canary evaluations.

Property

CompletedResponseMode

AppSurfaceCanaryCompletedResponseMode CompletedResponseMode { get; set; } Source

Gets or sets completed-result HTTP mapping. The default is AppSurfaceCanaryCompletedResponseMode.StatusCode .

Property

Snapshot

AppSurfaceCanarySnapshotOptions Snapshot { get; } Source

Gets the bounded aggregate snapshot settings. Defaults are safe for deploy-operator requests.

Type

WebStartup<TModule>

Source

Provides a base implementation for a web-based AppSurfaceStartup{TModule} that handles MVC, CORS, and static file configuration based on registered IAppSurfaceWebModule instances.

Type parameters

  • TModule
    The root IAppSurfaceWebModule for the application.
Method

WithOptions

WebStartup<TModule> WithOptions(Action<WebOptions>? configureOptions = null)
Source

Registers an optional callback to customize WebOptions and enables fluent chaining.

Parameters

  • configureOptions
    An optional action invoked later when WebOptions are built to modify configuration.

Returns

The same WebStartup{TModule} instance to support fluent configuration.

Method

RunAsync

Task RunAsync(string[] args)
Source

Starts the web host with AppSurface Web's deterministic development-port fallback when the caller has not explicitly configured an endpoint through command-line arguments, environment variables, or appsettings.

Parameters

  • args
    The command-line arguments supplied by the caller.

Returns

A task that completes when the web host run exits.

Method

ResolveDevelopmentPortDefaults

AppSurfaceWebDevelopmentPortResolution ResolveDevelopmentPortDefaults(string[] args)
Source

Resolves the effective command-line arguments before the web host starts.

Parameters

  • args
    The command-line arguments supplied by the caller.

Returns

The resolved startup arguments and any deterministic development-port metadata.

Method

RunResolvedAsync

Task RunResolvedAsync(string[] args)
Source

Runs the base host startup path with arguments after AppSurface Web development defaults have been resolved.

Parameters

  • args
    The effective command-line arguments to pass into the host.

Returns

A task that completes when the web host run exits.

Method

BuildModules

void BuildModules(StartupContext context)
Source

Collects and caches all IAppSurfaceWebModule instances found in the provided startup context. This method is idempotent.

Parameters

  • context
    The startup context whose dependencies and root module are inspected for web modules.

Remarks

This method is idempotent; subsequent calls have no effect once modules are built.

Method

BuildWebOptions

void BuildWebOptions(StartupContext context)
Source

Initializes and caches WebOptions by applying configuration from discovered modules and the optional custom callback; enables static file support when MVC is configured for controllers with views.

Parameters

  • context
    The startup context used when invoking module and custom option configuration.

Remarks

This method is idempotent; subsequent calls have no effect once options are built.

Method

ConfigureServicesForAppType

void ConfigureServicesForAppType(StartupContext context, IServiceCollection services)
Source

Configures services required for the web application: registers MVC application parts from the entry assembly and enabled web modules, and adds a CORS policy when CORS is enabled.

Parameters

  • context
    Startup context providing environment information and the entry-point assembly.
  • services
    The service collection to register MVC and CORS services into.

Exceptions

  • InvalidOperationException
    Thrown when CORS is enabled but no allowed origins are specified outside the development all-origins path, or when non-development configuration includes the literal wildcard origin * .
Method

ConfigureBuilderForAppType

IHostBuilder ConfigureBuilderForAppType(StartupContext context, IHostBuilder builder)
Source

Configures the provided host builder with web host defaults and registers the application's web initialization pipeline.

Parameters

  • context
    The startup context used to collect modules and build web options.
  • builder
    The host builder to configure.

Returns

The same IHostBuilder configured with web host defaults and the application's initialization pipeline.

Method

InitializeWebApplication

void InitializeWebApplication(StartupContext context, IApplicationBuilder app)
Source

Configures the application's middleware pipeline and endpoint routing for the web application.

Parameters

  • context
    The startup context containing environment, entry point, and discovered modules used during configuration.
  • app
    The application builder to configure (middleware, routing, CORS, endpoints, etc.).
Type

BrowserStatusPageModel

Source

Represents the model passed to AppSurface's conventional browser status page view.

Parameters

  • StatusCode
    The HTTP status code being rendered. AppSurface currently produces 401, 403, or 404.
  • OriginalPath
    The nullable original request path that produced the status response, when middleware can provide it.
  • OriginalQueryString
    The nullable original request query string that produced the status response, when middleware can provide it.

Remarks

The framework renderer normalizes missing or malformed route status values to 404 before creating the default model, but explicit status values must be supported by the built-in browser status page descriptors. Custom producers should pass only status codes their view understands. OriginalPath and OriginalQueryString are null for direct preview requests and can also be absent when upstream middleware strips or replaces status-code re-execution metadata. Status-page views should prefer this model for user-facing recovery copy because it captures the original failed request after AppSurface re-executes the framework route. Read HttpContext.Request only for current-request concerns such as URL generation; during re-execution it points at the reserved framework route. Treat the query string as display-only metadata, not as authorization or security input, and do not assume the path has a trailing slash or app-specific normalization.

Type

AppSurfaceCanaryRegistry

Source

Provides immutable ordinal lookup for registered named canaries.

Method

TryGet

bool TryGet(string name, out AppSurfaceCanaryDescriptor descriptor)
Source

Attempts exact ordinal lookup of a registered descriptor.

Parameters

  • name
    The exact name to find.
  • descriptor
    The registered descriptor when found.

Returns

true when the name is registered; otherwise false .

Method

ContainsAllNames

bool ContainsAllNames(IReadOnlyCollection<string> names)
Source

Determines whether every exact selector name is registered without resolving evaluators.

Property

OrderedDescriptors

IReadOnlyList<AppSurfaceCanaryDescriptor> OrderedDescriptors { get; } Source

Gets the ordinal descriptor snapshot without resolving evaluators.

Type

IPwaPushReadinessProvider

Source

Provides optional, privacy-safe server-known evidence about the configured AppSurface Web Push rail.

Remarks

Implementations must return only the fixed PwaPushReadiness evidence. They must not expose key material, routes, callback values, subscription values, or provider exception details.

Method

GetReadiness

PwaPushReadiness? GetReadiness()
Source

Gets the current privacy-safe Web Push readiness evidence, or null when unavailable.

Returns

The fixed safe evidence record, or null .

Type

PwaPushReadiness

Source

Contains the fixed privacy-safe facts that Web may publish in PWA diagnostics.

Parameters

  • ActiveVapidKeyId
    The safe identifier of the active VAPID key.
  • PublicKeyFingerprint
    The SHA-256 fingerprint of the decoded canonical public key.
  • RouteMapped
    Whether the package-owned Web Push route has been mapped.
Type

AppSurfaceCanarySnapshotCoordinator

Source

Runs a selected named-canary snapshot with bounded concurrent, cooperative evaluation.

Method

TrySelect

bool TrySelect(IReadOnlyCollection<string> names, IReadOnlyCollection<string> tags, int maximum, out IReadOnlyList<AppSurfaceCanaryDescriptor> selected)
Source

Selects registered descriptors by exact name or tag and reports whether the selected set fits the supplied limit.

Parameters

  • names
    The distinct exact names requested by the caller.
  • tags
    The distinct durable tags requested by the caller.
  • maximum
    The maximum number of selected descriptors permitted for the snapshot.
  • selected
    The ordinally ordered selected descriptors. This value is assigned even when the method returns false because the selection exceeded maximum .

Returns

true when selected contains no more than maximum descriptors; otherwise false . Empty names and tags select every registered canary.

Method

ContainsAllNames

bool ContainsAllNames(IReadOnlyCollection<string> names)
Source

Determines whether every exact name selector is registered without resolving evaluators.

Parameters

  • names
    The exact names to check.

Returns

true when every name is registered; otherwise false .

Method

EvaluateAsync

Task<AppSurfaceCanarySnapshotOutcome> EvaluateAsync(IReadOnlyList<AppSurfaceCanaryDescriptor> descriptors, string? marker, DateTimeOffset? freshSince, AppSurfaceCanarySnapshotOptions options, CancellationToken requestAborted)
Source

Evaluates the supplied ordinal descriptor selection with the configured bounded snapshot policy.

Parameters

  • descriptors
    The already selected descriptors, in their required output order.
  • marker
    The validated optional marker forwarded to every selected evaluator.
  • freshSince
    The validated optional freshness boundary forwarded to every selected evaluator.
  • options
    The immutable-at-mapping host snapshot policy.
  • requestAborted
    The request cancellation token that must be propagated without conversion.

Returns

A settled aggregate containing one privacy-safe item for every supplied descriptor.

Exceptions

  • OperationCanceledException
    requestAborted was canceled.

Remarks

The method waits for every started evaluator to settle. An evaluator that ignores cooperative cancellation delays the response but cannot contribute a successful result after either deadline expires.

Type

AppSurfaceCanarySnapshotOutcome

Source

Represents the settled, ordered result of one bounded snapshot request.

Property

Items

IReadOnlyList<AppSurfaceCanarySnapshotItem> Items { get; } Source

Gets one settled privacy-safe item for each selected descriptor, in ordinal order.

Property

OverallTimedOut

bool OverallTimedOut { get; } Source

Gets whether the overall deadline timed out a started or queued evaluator.

Property

Ready

bool Ready { get; } Source

Gets whether every selected item completed successfully before the overall deadline.

Type

AppSurfaceCanarySnapshotItem

Source

Represents one privacy-safe aggregate item outcome.

Method

Completed

AppSurfaceCanarySnapshotItem Completed(string name, AppSurfaceCanaryResult result, double elapsedMilliseconds)
Source

Creates a completed item containing the evaluator result.

Method

Failed

AppSurfaceCanarySnapshotItem Failed(string name)
Source

Creates a redacted evaluator-failure item.

Method

PerCheckTimedOut

AppSurfaceCanarySnapshotItem PerCheckTimedOut(string name)
Source

Creates an item that exceeded its per-check deadline.

Method

OverallTimedOut

AppSurfaceCanarySnapshotItem OverallTimedOut(string name)
Source

Creates a started item that was canceled by the overall deadline.

Method

NotStarted

AppSurfaceCanarySnapshotItem NotStarted(string name)
Source

Creates an item that was never admitted before the overall deadline.

Property

Name

string Name { get; } Source

Gets the exact registered canary name.

Property

State

AppSurfaceCanarySnapshotItemState State { get; } Source

Gets the typed settlement state used for internal aggregation.

Property

Outcome

string Outcome { get; } Source

Gets the stable response-envelope outcome projected from State .

Property

ReasonCode

string? ReasonCode { get; } Source

Gets the safe non-completed diagnostic projected from State , when applicable.

Property

Result

AppSurfaceCanaryResult? Result { get; } Source

Gets the completed evaluator result; otherwise null .

Property

ElapsedMilliseconds

double? ElapsedMilliseconds { get; } Source

Gets the completed evaluator elapsed time in milliseconds; otherwise null .

Property

BoundedByOverallDeadline

bool BoundedByOverallDeadline { get; } Source

Gets whether the overall deadline settled this item before it completed.

Property

Ready

bool Ready { get; } Source

Gets whether the item completed with a passing evaluator result.

Type

AppSurfaceCanaryEndpointDefaults

Source

Provides the conventional named-canary route contract.

Type

AppSurfaceHealthCheckTags

Source

Provides health-check tags understood by AppSurface Web's platform probe endpoints.

Type

AppSurfaceWebStartupTimeoutDiagnostic

Source

Builds operator-facing details for AppSurface Web startup watchdog failures.

Remarks

The diagnostic intentionally keeps to process and host-shape facts that are safe to log: sandbox markers, startup phase, directories, static-asset mode, and endpoint-shaped command-line arguments. It avoids inspecting arbitrary app configuration values, which may contain secrets.

Method

Create

AppSurfaceWebStartupTimeoutDiagnostic Create(TimeSpan startupTimeout, string startupPhase, string currentDirectory, string baseDirectory, bool staticWebAssetsEnabled, IReadOnlyList<string> startupArgs, Func<string, string?> environmentReader)
Source

Creates a startup-timeout diagnostic from the current process environment.

Parameters

  • startupTimeout
    Configured startup watchdog timeout.
  • startupPhase
    Startup phase observed when the watchdog fired.
  • currentDirectory
    Current working directory used by the host.
  • baseDirectory
    Application base directory used for dependency and asset resolution.
  • staticWebAssetsEnabled
    Whether AppSurface static web asset loading was enabled.
  • startupArgs
    Effective startup arguments after AppSurface development-port resolution.
  • environmentReader
    Environment reader used to detect sandbox markers.

Returns

A diagnostic object suitable for structured logging and tests.

Property

SandboxDetected

bool SandboxDetected { get; } Source

Gets a value indicating whether the process environment contains a known sandbox marker.

Property

SandboxSummary

string SandboxSummary { get; } Source

Gets a display-safe summary of detected sandbox markers.

Property

RecommendedAction

string RecommendedAction { get; } Source

Gets the concrete next step operators should try first.

Property

StartupArgsSummary

string StartupArgsSummary { get; } Source

Gets endpoint-related command-line arguments rendered for diagnostics.

Type

PwaEndpointMapper

Source
Method

BuildServiceWorkerScript

string BuildServiceWorkerScript(HttpContext httpContext, PwaOptions options)
Source

Composes the exact generated worker from a JSON configuration and capability-specific embedded sources.

Parameters

  • httpContext
    The request providing the effective path base.
  • options
    The validated PWA options.

Returns

The complete classic service-worker source.

Type

PwaDiagnosticsDocument

Source

Represents privacy-safe, server-known PWA posture for diagnostics and CLI compatibility.

Parameters

  • Enabled
    Whether install metadata is enabled.
  • ManifestPath
    The configured manifest path after PathBase application.
  • OfflineEnabled
    Whether the offline capability is enabled.
  • ConfiguredServiceWorkerPath
    The legacy configured worker path. It remains populated for offline mode and when both worker capabilities are disabled so older CLI versions can prove that the configured endpoint is absent; it is omitted for push-only mode.
  • ServiceWorkerPath
    The legacy active offline worker path, populated only when offline support is enabled.
  • OfflineFallbackPath
    The active offline fallback path.
  • WorkerEnabled
    Whether any worker capability is enabled.
  • WorkerPath
    The active shared worker path.
  • PushEnabled
    Whether push handlers are enabled.
  • WorkerScope
    The effective worker scope.
  • RegistrationHelperPath
    The active registration-helper path.
  • BadgingEnabled
    Whether the application-icon badging helper is enabled.
  • BadgingHelperPath
    The active PathBase-adjusted badging-helper path, or an explicit null when disabled.
  • PushReadiness
    Versioned, privacy-safe server-known Web Push readiness evidence.
  • Diagnostics
    Stable startup diagnostics.
Type

PwaWorkerScriptConfiguration

Source

Defines the JSON-safe configuration consumed by embedded worker fragments.

Parameters

  • OfflineEnabled
    Whether offline behavior is included.
  • CachePrefix
    The worker-path-specific owned cache prefix.
  • CacheName
    The active offline cache name.
  • LegacyCacheNames
    Legacy AppSurface cache names eligible for retirement.
  • StaticAssets
    PathBase-adjusted assets to precache.
  • OfflineFallback
    The PathBase-adjusted fallback path.
  • PathBase
    The effective application path base.
  • Scope
    The effective worker scope.
  • HandlerScriptPath
    The PathBase-adjusted custom push-handler path.
Type

BrowserStatusPageDescriptor

Source

Describes one built-in browser status page that AppSurface can preview, re-execute, and render.

Parameters

  • StatusCode
    The supported HTTP status code for this descriptor.
  • AppViewPath
    The conventional status-specific app or shared-library override view path.
  • ReservedRoute
    The framework-owned preview and re-execute route for this status code.
  • Title
    The document title used by the framework fallback view.
  • Eyebrow
    The short label rendered above the fallback heading.
  • Heading
    The main fallback heading shown to browser users.
  • Description
    The fallback explanation of what happened and how to recover.
  • PrimaryActionText
    The fallback primary recovery action label.

Remarks

Descriptors are internal framework metadata for the current built-in status set: 401, 403, and 404. Use TryGet(int, out BrowserStatusPageDescriptor) before routing or rendering arbitrary status codes; unsupported codes should not be re-executed through the browser status page pipeline.

Method

TryGet

bool TryGet(int statusCode, out BrowserStatusPageDescriptor? descriptor)
Source

Attempts to resolve a built-in browser status page descriptor for an HTTP status code.

Parameters

  • statusCode
    The HTTP status code to resolve.
  • descriptor
    When this method returns true , the descriptor for statusCode ; otherwise null .

Returns

true for supported status codes 401, 403, and 404; otherwise false .

Remarks

Unknown status codes are intentionally rejected so production exception pages and future status families can be designed separately instead of accidentally using the 401/403/404 browser-page contract.

Property

FrameworkFallbackViewPath

string FrameworkFallbackViewPath { get; } Source

Gets the shared framework fallback view path used when AppViewPath cannot be resolved.

Remarks

The fallback is shared across all supported statuses. App and shared Razor Class Library overrides remain status-specific through AppViewPath .

Property

Supported

IReadOnlyList<BrowserStatusPageDescriptor> Supported { get; } Source

Gets all built-in browser status page descriptors in the order AppSurface validates them.

Remarks

This list is the built-in set for the current release, not a promise that every browser-relevant status is supported. Callers should use TryGet(int, out BrowserStatusPageDescriptor) for lookup instead of assuming a status code is present.

Type

PwaScopePathMatcher

Source

Evaluates whether a resolved PWA start URL path falls within a resolved manifest scope path.

Remarks

The matcher centralizes the browser-style prefix contract used by both AppSurface Web startup validation and the AppSurface CLI verifier. Browser service-worker and manifest scopes use raw URL-path prefix matching. Applications that require a segment boundary should end a non-root scope in / .

Method

IsPathWithinScope

bool IsPathWithinScope(string path, string scope)
Source

Returns a value indicating whether path is within scope .

Parameters

  • path
    The resolved app-root-relative path portion of the PWA start URL.
  • scope
    The resolved app-root-relative path portion of the PWA manifest scope.

Returns

true when path is covered by scope .

Type

AppSurfaceCanaryResultOptions

Source

Configures bounded operator evidence for one named-canary result.

Remarks

The result snapshots these values after the callback completes. Text supplied here is returned only from the protected named-canary endpoint; AppSurface bounds and validates its shape but does not classify or redact it. Never include secrets, personal data, provider payloads, URLs, prompts, source text, or private generated content.

Method

AddDetail

void AddDetail(string key, string value)
Source

Adds one declared, response-only detail value.

Parameters

  • key
    A lowercase dot-separated key of at most 64 ASCII characters.
  • value
    A nonblank operator-safe value of at most 128 UTF-8 bytes.

Exceptions

  • ArgumentNullException
    key or value is null.
  • ArgumentException
    The key or value violates its grammar, byte bound, or scalar rules.
  • InvalidOperationException
    The key is duplicated or a seventeenth unique detail is added.

Remarks

The key must also appear in AppSurfaceCanaryRegistrationOptions.AllowedDetailKeys for the same canary. That registration-specific check occurs after evaluation and fails closed as ASCAN301 .

Property

ObservedAt

DateTimeOffset? ObservedAt { get; set; } Source

Gets or sets the optional time at which the evaluator observed its proof.

Remarks

The value is normalized to UTC when the result is created. No default is inferred.

Property

MatchedCount

int? MatchedCount { get; set; } Source

Gets or sets an optional non-negative count of matching proofs.

Property

ReasonCode

string? ReasonCode { get; set; } Source

Gets or sets an optional stable machine-readable reason code.

Remarks

A reason code is 1-64 lowercase ASCII letters, digits, or internal hyphens and must start and end with a letter or digit. It is response-only and is intended for machine branching.

Property

Summary

string? Summary { get; set; } Source

Gets or sets optional operator-safe explanatory text of at most 256 UTF-8 bytes.

Remarks

Blank text, malformed Unicode, and Unicode control scalars are rejected.

Property

CorrelationId

string? CorrelationId { get; set; } Source

Gets or sets an optional non-secret correlation identifier.

Remarks

The identifier is 1-128 ASCII characters from letters, digits, period, underscore, colon, and hyphen, and it must start and end with a letter or digit. It is not added to completion logs.

Type

AppSurfaceCanaryResultValidation

Source

Validates intrinsic named-canary result evidence.

Type

AppSurfaceCanaryHeaderNames

Source

Provides the fixed request-header names used by named canary endpoints.

Type

ConventionalExceptionPageDefaults

Source

Defines the conventional paths used by AppSurface's built-in browser-friendly production 500 handling.

Type

WebOptions

Source

Represents configuration options for the web application, including MVC, CORS, and static file settings.

Property

Mvc

MvcOptions Mvc { get; set; } Source

Gets or sets MVC-specific configuration options, such as support levels and custom MVC configuration.

Property

Cors

CorsOptions Cors { get; set; } Source

Gets or sets CORS configuration options for defining cross-origin resource sharing policies.

Property

StaticFiles

StaticFilesOptions StaticFiles { get; set; } Source

Gets or sets configuration options for serving static files within the web application.

Property

Errors

ErrorPagesOptions Errors { get; set; } Source

Gets or sets configuration options for conventional framework browser status pages.

Remarks

The default value is ErrorPagesOptions.Default , which leaves browser status pages in BrowserStatusPageMode.Auto . In that mode, AppSurface only enables the conventional browser 401, 403, and 404 experience when MVC support already includes views. Use explicit modes when an app must always force or always suppress the conventional pages. When enabled, AppSurface reserves /_appsurface/errors/401 , /_appsurface/errors/403 , and /_appsurface/errors/404 for direct rendering, and ignores that path prefix when deciding whether to apply browser-oriented status-page middleware. Static export tooling still consumes only the 404 route and writes only 404.html ; when CDN mode is active, that emitted page is validated and rewritten with the rest of the static graph.

Property

Pwa

PwaOptions Pwa { get; set; } Source

Gets or sets Progressive Web App install metadata, diagnostics, and explicit offline behavior.

Remarks

PWA support is disabled by default. When enabled, AppSurface maps a web app manifest endpoint, optional development diagnostics, and a service-worker endpoint only when an explicit offline strategy is configured. AppSurface does not cache app routes, authenticated pages, POST responses, or user-specific data by default.

Property

Health

HealthOptions Health { get; set; } Source

Gets or sets platform health and readiness probe endpoint configuration.

Remarks

Health endpoints are disabled by default. Set HealthOptions.Enabled to true when deployment or monitoring infrastructure consumes the public, minimal /health and /ready endpoints. Leave the option disabled when the host owns probes directly or does not consume them.

Property

StartupTimeout

TimeSpan? StartupTimeout { get; set; } Source

Gets or sets the amount of time AppSurface waits for the web host to complete startup before failing fast.

Remarks

The default is 10 seconds. Set this to null only for hosts that intentionally perform long-running startup work before Kestrel binds. The watchdog covers pre-bind stalls caused by package layout, sandboxing, static asset discovery, hosted-service startup, and similar issues; it does not limit normal request processing after the host has started. Timeout diagnostics include safe process context, the observed startup phase, and known Codex sandbox markers when present so operators can rerun outside the sandbox before chasing package or host-layout causes. StartupTimeout must be null or greater than TimeSpan.Zero . Use null to disable the watchdog instead of TimeSpan.Zero .

Property

MapEndpoints

Action<IEndpointRouteBuilder>? MapEndpoints { get; set; } Source

Gets or sets an optional delegate to configure endpoint routing for the application.

Type

CorsOptions

Source

Represents configuration options for Cross-Origin Resource Sharing (CORS) policies.

Remarks

Use CorsOptions when an AppSurface web application should register and apply the framework-managed CORS policy. EnableCors controls whether that policy is active outside development, while EnableAllOriginsInDevelopment keeps local browser workflows convenient without opening production defaults. Empty AllowedHeaders or AllowedMethods collections do not opt into permissive preflight behavior in production; configure the exact browser contract an application supports. Pitfall: enabling CORS in non-development environments still requires at least one allowed origin unless development-only all-origin behavior applies, and the literal wildcard origin * is rejected outside development for AppSurface-managed CORS. Use explicit origins, wildcard subdomains such as https://*.example.com , or host-owned ASP.NET Core CORS policy registration for intentionally public wildcard APIs.

Property

EnableAllOriginsInDevelopment

bool EnableAllOriginsInDevelopment { get; set; } Source

Gets or sets a value indicating whether all origins are allowed when running in the development environment. Defaults to true .

Property

EnableCors

bool EnableCors { get; set; } Source

Gets or sets a value indicating whether CORS is enabled for the application. Defaults to false .

Property

AllowedOrigins

string[] AllowedOrigins { get; set; } Source

Gets or sets the collection of origins permitted to make cross-origin requests. Defaults to an empty array.

Remarks

Use exact origins such as https://app.example.com . AppSurface also preserves ASP.NET Core wildcard subdomain support for origins such as https://*.example.com . The exact literal * is allowed only for the existing development compatibility path; non-development startup fails before registering the AppSurface-managed CORS policy when this collection contains * .

Property

AllowedHeaders

string[] AllowedHeaders { get; set; } Source

Gets or sets the request headers advertised by the CORS policy during browser preflight requests. Defaults to an empty array, which advertises no custom preflight request headers in production.

Remarks

Configure explicit header names, such as Content-Type or X-Request-Id , when preflighted cross-origin callers need them. Use * only when the application intentionally accepts any request header from allowed origins. Non-preflight CORS responses are still governed by origin policy and browser safelisted request behavior; this collection defines the Access-Control-Allow-Headers preflight response contract. When EnableAllOriginsInDevelopment applies, AppSurface still allows any header for local development convenience unless this collection contains one or more configured values.

Property

AllowedMethods

string[] AllowedMethods { get; set; } Source

Gets or sets the HTTP methods advertised by the CORS policy during browser preflight requests. Defaults to an empty array, which advertises no preflight-only HTTP methods in production.

Remarks

Configure explicit method names, such as GET or POST , when preflighted cross-origin callers need them. Use * only when the application intentionally accepts any method from allowed origins. Non-preflight CORS responses are still governed by origin policy and browser method safelisting; this collection defines the Access-Control-Allow-Methods preflight response contract. When EnableAllOriginsInDevelopment applies, AppSurface still allows any method for local development convenience unless this collection contains one or more configured values.

Property

PolicyName

string PolicyName { get; set; } Source

Gets or sets the name of the CORS policy to register. Defaults to "DefaultCorsPolicy" .

Property

Default

CorsOptions Default { get; } Source

Gets a default instance of CorsOptions with default configuration settings.

Type

AppSurfaceConfigAuditDiagnosticsEndpointRouteBuilderExtensions

Source

Maps opt-in AppSurface configuration-audit HTTP diagnostics endpoints.

Method

MapAppSurfaceConfigAuditDiagnostics

2 overloads
RouteHandlerBuilder MapAppSurfaceConfigAuditDiagnostics(this IEndpointRouteBuilder endpoints, string authorizationPolicyName)
Source

Maps the AppSurface configuration-audit diagnostics endpoint at the default route.

Parameters

  • endpoints
    The endpoint route builder that receives the diagnostics endpoint.
  • authorizationPolicyName
    The non-blank host-owned ASP.NET Core authorization policy required for the endpoint.

Returns

The route handler builder so hosts can add their own endpoint metadata.

Remarks

The endpoint is never mapped automatically. Hosts must call this method deliberately, register AppSurface Config services, configure authentication and authorization middleware, and supply an authorization policy that is safe for support-sensitive deployment diagnostics.

RouteHandlerBuilder MapAppSurfaceConfigAuditDiagnostics(this IEndpointRouteBuilder endpoints, string pattern, string authorizationPolicyName)
Source

Maps the AppSurface configuration-audit diagnostics endpoint at a custom route.

Parameters

  • endpoints
    The endpoint route builder that receives the diagnostics endpoint.
  • pattern
    The non-blank route pattern for the endpoint.
  • authorizationPolicyName
    The non-blank host-owned ASP.NET Core authorization policy required for the endpoint.

Returns

The route handler builder so hosts can add their own endpoint metadata.

Remarks

The endpoint returns the active host's sanitized ConfigAuditReport as JSON and sets no-store response headers. It is excluded from API description by default because redacted audit reports can still expose support-sensitive provider names, paths, configuration keys, and deployment structure.

Method

CreateReportResult

IResult CreateReportResult(HttpContext httpContext, Func<ConfigAuditReport, string> serializeReport)
Source

Creates the diagnostics response for the current request.

Parameters

  • httpContext
    The current request context, including a request service provider and writable response.
  • serializeReport
    The serializer used to render the sanitized ConfigAuditReport .

Returns

An IResult containing either the report JSON or a safe problem response.

Remarks

This internal overload exists as a test seam for serialization and failure-path verification. Production code should expose the endpoint through MapAppSurfaceConfigAuditDiagnostics(Microsoft.AspNetCore.Routing.IEndpointRouteBuilder, string, string) instead of calling this helper directly.

Type

AppSurfaceWebThemingServiceCollectionExtensions

Source

Registers the opt-in Web rendering adapter for neutral AppSurface theming.

Method

AddAppSurfaceWebTheming

IServiceCollection AddAppSurfaceWebTheming(this IServiceCollection services)
Source

Registers the Web theme document provider used by the AppSurface theme TagHelpers.

Parameters

  • services
    Service collection receiving the provider.

Returns

The original services instance.

Remarks

Call AddAppSurfaceTheming from the neutral theming package first, then call this method to opt the Web host into the TagHelpers.AppSurfaceThemeRootTagHelper and TagHelpers.AppSurfaceThemeHeadTagHelper integration. This method intentionally does not create a default theme pair or silently enable theme rendering.

Method

AddAppSurfaceWebThemePreferences

IServiceCollection AddAppSurfaceWebThemePreferences(this IServiceCollection services, Action<AppSurfaceThemePreferenceOptions>? configure = null)
Source

Registers browser-local System/Light/Dark preference support for the configured Web theme pair.

Parameters

  • services
    The service collection receiving the preference adapter.
  • configure
    Optional configuration for the origin-scoped browser storage key. The key is not rendered into the bootstrap script, so changing it does not change the published CSP script hash.

Returns

The original services instance.

Exceptions

  • ArgumentNullException
    services is null .
  • ArgumentException
    The configured storage key is blank, unsafe for HTML data attributes, or longer than 64 characters.
  • InvalidOperationException
    An ForgeTrust.AppSurface.Theming.IAppSurfaceThemeResolver has not been registered before this call. AddAppSurfaceTheming is one supported registration path; hosts may instead register a compatible custom resolver for the selected pair.

Remarks

This opt-in establishes the base Web integration and replaces its document provider with a System-first preference document for the same neutral theme pair. It never reads HTTP state, writes a cookie, changes a URL, adds a cache key, or alters the neutral theming package. Existing hosts that use only AddAppSurfaceWebTheming(IServiceCollection) retain their configured startup mode and emit no preference script.

The browser may persist only explicit light or dark values in local storage. Missing, blocked, malformed, and explicit system values use the operating-system preference through the server-rendered System stylesheet. Calling this method again replaces the previous preference configuration; the latest valid storage key is the one rendered by the head TagHelper.

Method

AddAppSurfaceWebThemeSelection

IServiceCollection AddAppSurfaceWebThemeSelection(this IServiceCollection services)
Source

Registers a scoped host-policy adapter that selects one registered theme pair before Web rendering.

Parameters

  • services
    The service collection receiving the selection adapter.

Returns

The original services instance.

Exceptions

  • ArgumentNullException
    services is null .
  • InvalidOperationException
    Singleton neutral theme services, a scoped IAppSurfaceWebThemeSelectionPolicy , or the built-in ordinary Web document provider are missing; a conflicting adapter is registered; or selection is registered twice.

Remarks

Register AddAppSurfaceTheming , a scoped host implementation of IAppSurfaceWebThemeSelectionPolicy , then this opt-in. The policy consumes only already-authorized application context and returns either one registered AppSurfaceThemeId or false for the configured default. Both neutral services must be singletons because the adapter prevalidates and caches package-owned documents once for the application. The adapter validates selected ids and the resolver's configured default identifier and role snapshots against the sealed registry and never serializes a caller-supplied theme pair.

This adapter intentionally cannot compose with browser-local preferences or a consumer-owned IAppSurfaceThemeDocumentProvider . It caches package-owned documents by immutable pair id, but it never configures HTTP caching, response variation, tenant resolution, authorization, or invalidation. A pair id is not a safe host response-cache key; the host must partition or disable tenant-sensitive response caches.

Enum

MvcSupport

Source

Specifies the level of MVC feature support to enable in the web application.

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

AppSurfaceCanaryCompletedResponseMode

Source

Controls HTTP status mapping for completed named-canary evaluations.

Enum

AppSurfaceCanaryStatus

Source

Describes the current application-owned proof state for a named canary.

Enum

PwaDisplayMode

Source

Display modes AppSurface can emit into the generated web app manifest.

Remarks

Values match the standard web app manifest display modes. AppSurface serializes MinimalUi as minimal-ui . 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

PwaDiagnosticEndpointExposure

Source

Controls when AppSurface maps browser-facing PWA diagnostics.

Remarks

Diagnostics can expose deploy and browser-install posture. Keep the default DevelopmentOnly unless a host intentionally wants the diagnostics available behind its own controls. 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

AppSurfaceCanarySnapshotItemState

Source

Defines the typed internal settlement states for a snapshot item.

Enum

BrowserStatusPageMode

Source

Controls how AppSurface applies its conventional browser-friendly status pages.

Remarks

Auto is the default and is the safest choice for most applications because it only enables the conventional pages when MVC view support is already available. Switch to Enabled when an app must always expose the conventional HTML 401, 403, and 404 experience, even if AppSurface needs to upgrade MVC support to controllers with views during startup. Use Disabled for API-first applications or when another status-code handling strategy should remain fully in control. 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.