StaticFilesOptions Default { get; }
Source
Gets a default instance of StaticFilesOptions with default configuration settings.
Web
Namespaces
WebStartup<TModule>
SourceProvides a base implementation for a web-based AppSurfaceStartup{TModule} that handles MVC, CORS, and static file configuration based on registered IAppSurfaceWebModule instances.
Type Parameters
TModuleThe rootIAppSurfaceWebModulefor the application.
WithOptions
WebStartup<TModule> WithOptions(Action<WebOptions>? configureOptions = null)
Source
Registers an optional callback to customize WebOptions and enables fluent chaining.
Parameters
configureOptionsAn optional action invoked later when WebOptions are built to modify configuration.
Returns
The same WebStartup{TModule} instance to support fluent configuration.
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
argsThe command-line arguments supplied by the caller.
Returns
A task that completes when the web host run exits.
ResolveDevelopmentPortDefaults
AppSurfaceWebDevelopmentPortResolution ResolveDevelopmentPortDefaults(string[] args)
Source
Resolves the effective command-line arguments before the web host starts.
Parameters
argsThe command-line arguments supplied by the caller.
Returns
The resolved startup arguments and any deterministic development-port metadata.
RunResolvedAsync
Task RunResolvedAsync(string[] args)
Source
Runs the base host startup path with arguments after AppSurface Web development defaults have been resolved.
Parameters
argsThe effective command-line arguments to pass into the host.
Returns
A task that completes when the web host run exits.
BuildModules
void BuildModules(StartupContext context)
Source
Collects and caches all IAppSurfaceWebModule instances found in the provided startup context. This method is idempotent.
Parameters
contextThe 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.
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
contextThe startup context used when invoking module and custom option configuration.
Remarks
This method is idempotent; subsequent calls have no effect once options are built.
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
contextStartup context providing environment information and the entry-point assembly.servicesThe service collection to register MVC and CORS services into.
Exceptions
InvalidOperationExceptionThrown 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*.
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
contextThe startup context used to collect modules and build web options.builderThe host builder to configure.
Returns
The same IHostBuilder configured with web host defaults and the application's initialization pipeline.
InitializeWebApplication
void InitializeWebApplication(StartupContext context, IApplicationBuilder app)
Source
Configures the application's middleware pipeline and endpoint routing for the web application.
Parameters
contextThe startup context containing environment, entry point, and discovered modules used during configuration.appThe application builder to configure (middleware, routing, CORS, endpoints, etc.).
WebApp<TStartup, TModule>
SourceProvides a static entry point for starting a web application with a custom startup class and root module.
Type Parameters
TStartupThe type of the custom startup class, inheriting fromWebStartup{TModule}.TModuleThe type of the root web module.
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
argsThe command-line arguments provided at application startup.configureOptionsAn optional delegate to further customizeWebOptionsduring startup.
Returns
A Task representing the asynchronous operation of running the web application.
WebApp<TModule>
SourceProvides a simplified static entry point for starting a web application using a default startup configuration.
Type Parameters
TModuleThe type of the root web module.
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
argsThe command-line arguments provided at application startup.configureOptionsAn optional delegate to customizeWebOptionsduring startup.
Returns
A Task representing the asynchronous operation of running the web application.
StaticFilesOptions
SourceRepresents configuration options for serving static files and web assets.
Default
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.
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.
AppSurfaceConfigAuditDiagnosticsDefaults
SourceProvides 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.
AppSurfaceWebStartupTimeoutDiagnostic
SourceBuilds 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.
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
startupTimeoutConfigured startup watchdog timeout.startupPhaseStartup phase observed when the watchdog fired.currentDirectoryCurrent working directory used by the host.baseDirectoryApplication base directory used for dependency and asset resolution.staticWebAssetsEnabledWhether AppSurface static web asset loading was enabled.startupArgsEffective startup arguments after AppSurface development-port resolution.environmentReaderEnvironment reader used to detect sandbox markers.
Returns
A diagnostic object suitable for structured logging and tests.
SandboxDetected
bool SandboxDetected { get; }
Source
Gets a value indicating whether the process environment contains a known sandbox marker.
SandboxSummary
string SandboxSummary { get; }
Source
Gets a display-safe summary of detected sandbox markers.
RecommendedAction
string RecommendedAction { get; }
Source
Gets the concrete next step operators should try first.
StartupArgsSummary
string StartupArgsSummary { get; }
Source
Gets endpoint-related command-line arguments rendered for diagnostics.
ErrorPagesOptions
SourceRepresents 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.
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.
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.
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.
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.
AreConventionalBrowserStatusPagesEnabled
bool AreConventionalBrowserStatusPagesEnabled(MvcSupport mvcSupportLevel)
Source
Determines whether AppSurface should enable conventional browser status pages for the supplied MVC support level.
Parameters
mvcSupportLevelThe 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.
Default
ErrorPagesOptions Default { get; }
Source
Gets a default instance of ErrorPagesOptions with BrowserStatusPageMode.Auto.
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.
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.
BrowserStatusPageModel
SourceRepresents the model passed to AppSurface's conventional browser status page view.
Parameters
StatusCodeThe HTTP status code being rendered. AppSurface currently produces 401, 403, or 404.OriginalPathThe nullable original request path that produced the status response, when middleware can provide it.OriginalQueryStringThe 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.
BrowserStatusPageDescriptor
SourceDescribes one built-in browser status page that AppSurface can preview, re-execute, and render.
Parameters
StatusCodeThe supported HTTP status code for this descriptor.AppViewPathThe conventional status-specific app or shared-library override view path.ReservedRouteThe framework-owned preview and re-execute route for this status code.TitleThe document title used by the framework fallback view.EyebrowThe short label rendered above the fallback heading.HeadingThe main fallback heading shown to browser users.DescriptionThe fallback explanation of what happened and how to recover.PrimaryActionTextThe 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.
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
statusCodeThe HTTP status code to resolve.descriptorWhen this method returnstrue, the descriptor forstatusCode; otherwisenull.
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.
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.
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.
PwaOfflineOptions
SourceConfigures 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.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether AppSurface should map a starter service-worker endpoint.
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.
OfflineFallbackPath
string OfflineFallbackPath { get; set; }
Source
Gets or sets the app-root-relative offline fallback page cached by the starter service worker.
StaticAssetPaths
string[] StaticAssetPaths { get; set; }
Source
Gets or sets app-root-relative static asset URLs the starter service worker should cache.
PwaEndpointMapper
SourceBuildServiceWorkerScript
string BuildServiceWorkerScript(HttpContext httpContext, PwaOptions options)
Source
Composes the exact generated worker from a JSON configuration and capability-specific embedded sources.
Parameters
httpContextThe request providing the effective path base.optionsThe validated PWA options.
Returns
The complete classic service-worker source.
PwaDiagnosticsDocument
SourceRepresents privacy-safe, server-known PWA posture for diagnostics and CLI compatibility.
Parameters
EnabledWhether install metadata is enabled.ManifestPathThe configured manifest path after PathBase application.OfflineEnabledWhether the offline capability is enabled.ConfiguredServiceWorkerPathThe 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.ServiceWorkerPathThe legacy active offline worker path, populated only when offline support is enabled.OfflineFallbackPathThe active offline fallback path.WorkerEnabledWhether any worker capability is enabled.WorkerPathThe active shared worker path.PushEnabledWhether push handlers are enabled.WorkerScopeThe effective worker scope.RegistrationHelperPathThe active registration-helper path.DiagnosticsStable startup diagnostics.
PwaWorkerScriptConfiguration
SourceDefines the JSON-safe configuration consumed by embedded worker fragments.
Parameters
OfflineEnabledWhether offline behavior is included.CachePrefixThe worker-path-specific owned cache prefix.CacheNameThe active offline cache name.LegacyCacheNamesLegacy AppSurface cache names eligible for retirement.StaticAssetsPathBase-adjusted assets to precache.OfflineFallbackThe PathBase-adjusted fallback path.PathBaseThe effective application path base.ScopeThe effective worker scope.HandlerScriptPathThe PathBase-adjusted custom push-handler path.
PwaScriptAssets
SourceRead
string Read(Assembly assembly, string fileName)
Source
Reads a named PWA resource from an assembly.
Parameters
assemblyThe assembly that owns the embedded PWA resource.fileNameThe final file name beneath the embedded Assets.Pwa namespace.
Returns
The UTF-8 resource contents.
Exceptions
InvalidOperationExceptionThe named resource cannot be found or opened.
WorkerOffline
string WorkerOffline { get; }
Source
Gets the optional offline capability source.
WorkerPush
string WorkerPush { get; }
Source
Gets the default version-1 push and notification-click source.
WorkerCustomHandler
string WorkerCustomHandler { get; }
Source
Gets the contained custom push-handler import source.
RegistrationHelper
string RegistrationHelper { get; }
Source
Gets the inert browser registration-helper source.
PathValidationVectors
string PathValidationVectors { get; }
Source
Gets the shared C# and JavaScript path-validation vectors.
RegistrationHelperVersion
string RegistrationHelperVersion { get; }
Source
Gets the content-derived cache version for the registration helper.
PwaPathBase
SourceResolves app-root-relative PWA paths beneath the current request path base.
Add
string Add(PathString pathBase, string path)
Source
Prepends pathBase to the app-root-relative path.
Parameters
pathBaseThe current request path base.pathThe app-root-relative path to resolve.
Returns
The path resolved beneath pathBase.
IAppSurfaceWebModule
SourceDefines a module that exposes web-specific configuration, endpoints, and middleware.
ConfigureWebOptions
void ConfigureWebOptions(StartupContext context, WebOptions options)
Source
Configures WebOptions for the application, such as MVC, CORS, and static files.
Parameters
contextThe startup context for the application.optionsThe options to be configured.
ConfigureEndpoints
void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source
Allows the module to configure endpoint routes for the application.
Parameters
contextStartup context providing environment and configuration for the module.endpointsEndpoint route builder used to map endpoints (routes, hubs, etc.).
ConfigureWebApplication
void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source
Configure the ASP.NET Core request pipeline for this module.
Parameters
contextStartup information and services available to the module during application initialization.appThe application's request pipeline builder used to register middleware, routing, and other pipeline components.
ConfigureEndpointAwareMiddleware
void ConfigureEndpointAwareMiddleware(StartupContext context, IApplicationBuilder app)
Source
Configures middleware that can inspect endpoint routing metadata before endpoints execute.
Parameters
contextStartup information and services available to the module during application initialization.appThe 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.
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.
HealthOptions
SourceConfigures AppSurface Web platform health and readiness probe endpoints.
Remarks
AppSurface maps public, minimal health endpoints by default so container platforms can probe a service without application-specific endpoint wiring. 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.
Default
HealthOptions Default { get; }
Source
Gets a default enabled health options instance.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether AppSurface should map platform health and readiness endpoints.
HealthPath
string HealthPath { get; set; }
Source
Gets or sets the app-root-relative endpoint path that runs all registered ASP.NET Core health checks.
ReadyPath
string ReadyPath { get; set; }
Source
Gets or sets the app-root-relative endpoint path that runs readiness-tagged ASP.NET Core health checks.
ReadyTag
string ReadyTag { get; set; }
Source
Gets or sets the health-check tag used to select checks for the readiness endpoint.
PwaIcon
SourceDeclares 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.
Source
string Source { get; set; }
Source
Gets or sets the app-root-relative icon URL.
Sizes
string Sizes { get; set; }
Source
Gets or sets the manifest size token list, for example 192x192 or 192x192 512x512.
Type
string Type { get; set; }
Source
Gets or sets the icon content type. Defaults to image/png.
Purpose
string? Purpose { get; set; }
Source
Gets or sets the optional manifest purpose, for example any or maskable.
MvcOptions
SourceRepresents configuration options for ASP.NET Core MVC services and features.
Default
MvcOptions Default { get; }
Source
Gets a new default instance of MvcOptions configured with MvcSupport.Controllers.
MvcSupportLevel
MvcSupport MvcSupportLevel { get; init; }
Source
Gets the level of MVC support to register (e.g., Controllers only, or Controllers with Views).
ConfigureMvc
Action<IMvcBuilder>? ConfigureMvc { get; init; }
Source
Gets an optional delegate for performing advanced configuration of the IMvcBuilder.
MvcSupport
SourceSpecifies 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.
PwaWorkerPathState
SourceTracks legacy and current service-worker path assignments without making configuration-provider order observable.
SetLegacyValue
void SetLegacyValue(string value)
Source
Records an explicit assignment through the legacy offline compatibility property.
Parameters
valueThe assigned app-root-relative worker path.
SetWorkerValue
void SetWorkerValue(string value)
Source
Records an explicit assignment through the current worker property.
Parameters
valueThe assigned app-root-relative worker path.
LegacyWasSet
bool LegacyWasSet { get; set; }
Source
Gets a value indicating whether the legacy offline path property was assigned explicitly.
WorkerWasSet
bool WorkerWasSet { get; set; }
Source
Gets a value indicating whether the current worker path property was assigned explicitly.
HasConflict
bool HasConflict { get; }
Source
Gets a value indicating whether the legacy and current properties were assigned different paths.
EffectiveValue
string EffectiveValue { get; }
Source
Gets the current worker path, preferring the current property over the legacy compatibility property.
WebOptions
SourceRepresents configuration options for the web application, including MVC, CORS, and static file settings.
Mvc
MvcOptions Mvc { get; set; }
Source
Gets or sets MVC-specific configuration options, such as support levels and custom MVC configuration.
Cors
CorsOptions Cors { get; set; }
Source
Gets or sets CORS configuration options for defining cross-origin resource sharing policies.
StaticFiles
StaticFilesOptions StaticFiles { get; set; }
Source
Gets or sets configuration options for serving static files within the web application.
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.
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.
Health
HealthOptions Health { get; set; }
Source
Gets or sets platform health and readiness probe endpoint configuration.
Remarks
Health endpoints are enabled by default. AppSurface maps public, minimal /health and /ready endpoints for container and service-platform probes. Set HealthOptions.Enabled to false when a host owns probe endpoints directly.
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.
MapEndpoints
Action<IEndpointRouteBuilder>? MapEndpoints { get; set; }
Source
Gets or sets an optional delegate to configure endpoint routing for the application.
AppSurfaceConfigAuditDiagnosticsEndpointRouteBuilderExtensions
SourceMaps opt-in AppSurface configuration-audit HTTP diagnostics endpoints.
MapAppSurfaceConfigAuditDiagnostics
2 overloads
RouteHandlerBuilder MapAppSurfaceConfigAuditDiagnostics(this IEndpointRouteBuilder endpoints, string authorizationPolicyName)
Source
Maps the AppSurface configuration-audit diagnostics endpoint at the default route.
Parameters
endpointsThe endpoint route builder that receives the diagnostics endpoint.authorizationPolicyNameThe 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
endpointsThe endpoint route builder that receives the diagnostics endpoint.patternThe non-blank route pattern for the endpoint.authorizationPolicyNameThe 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.
CreateReportResult
IResult CreateReportResult(HttpContext httpContext, Func<ConfigAuditReport, string> serializeReport)
Source
Creates the diagnostics response for the current request.
Parameters
httpContextThe current request context, including a request service provider and writable response.serializeReportThe serializer used to render the sanitizedConfigAuditReport.
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.
PwaDiagnosticEndpointExposure
SourceControls 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.
BrowserStatusPageRenderer
SourceResolves 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.
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.
RenderAsync
Task RenderAsync(HttpContext httpContext)
Source
Renders the resolved conventional browser status page view into the current HTTP response.
Parameters
httpContextThe 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.
PwaOptions
SourceConfigures independent AppSurface Progressive Web App install, offline, and push-worker 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.
Default
PwaOptions Default { get; }
Source
Gets a default disabled PWA options instance.
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.
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.
DiagnosticsExposure
PwaDiagnosticEndpointExposure DiagnosticsExposure { get; set; }
Source
Gets or sets when the PWA diagnostics endpoint should be mapped.
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.
Name
string Name { get; set; }
Source
Gets or sets the full application name emitted into the manifest.
ShortName
string ShortName { get; set; }
Source
Gets or sets the short application name emitted into the manifest.
StartUrl
string StartUrl { get; set; }
Source
Gets or sets the app-root-relative start URL emitted into the manifest.
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.
Display
PwaDisplayMode Display { get; set; }
Source
Gets or sets the display mode emitted into the manifest.
ThemeColor
string ThemeColor { get; set; }
Source
Gets or sets the manifest and browser theme color as a CSS hex color.
BackgroundColor
string BackgroundColor { get; set; }
Source
Gets or sets the manifest background color as a CSS hex color.
Icons
IList<PwaIcon> Icons { get; }
Source
Gets or sets the icon entries emitted into the generated manifest.
Worker
PwaWorkerOptions Worker { get; }
Source
Gets shared service-worker and registration-helper endpoint settings.
Offline
PwaOfflineOptions Offline { get; }
Source
Gets explicit offline strategy settings.
Push
PwaPushOptions Push { get; }
Source
Gets opt-in Web Push worker settings.
IsWorkerEnabled
bool IsWorkerEnabled { get; }
Source
Gets whether at least one capability requires the shared service worker.
HasAnySurfaceEnabled
bool HasAnySurfaceEnabled { get; }
Source
Gets whether AppSurface should validate and map any PWA surface.
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.
PwaScopePathMatcher
SourceEvaluates 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 /.
IsPathWithinScope
bool IsPathWithinScope(string path, string scope)
Source
Returns a value indicating whether path is within scope.
Parameters
pathThe resolved app-root-relative path portion of the PWA start URL.scopeThe resolved app-root-relative path portion of the PWA manifest scope.
Returns
true when path is covered by scope.
PwaPushOptions
SourceConfigures 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.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether the generated worker should support push events.
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.
BrowserStatusPageMode
SourceControls 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.
PwaStaticFileShadowValidator
SourceThrowIfInvalid
void ThrowIfInvalid(PwaOptions options, IFileProvider webRootFileProvider)
Source
Rejects generated worker/helper routes that static-file middleware would serve first.
Parameters
optionsThe validated PWA options.webRootFileProviderThe effective web-root file provider.
CorsOptions
SourceRepresents 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.
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.
EnableCors
bool EnableCors { get; set; }
Source
Gets or sets a value indicating whether CORS is enabled for the application. Defaults to false.
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 *.
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.
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.
PolicyName
string PolicyName { get; set; }
Source
Gets or sets the name of the CORS policy to register. Defaults to "DefaultCorsPolicy".
Default
CorsOptions Default { get; }
Source
Gets a default instance of CorsOptions with default configuration settings.
BrowserStatusPageDefaults
SourceDefines 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.
GetAppViewPath
string GetAppViewPath(int statusCode)
Source
Formats the conventional app override view path for the supplied HTTP status code.
Parameters
statusCodeThe 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.
GetReservedRoute
string GetReservedRoute(int statusCode)
Source
Formats the framework-reserved preview route for the supplied HTTP status code.
Parameters
statusCodeThe 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.
AppSurfaceHealthCheckTags
SourceProvides health-check tags understood by AppSurface Web's platform probe endpoints.
ExceptionPageModel
SourceRepresents the model passed to AppSurface's conventional production exception view.
Parameters
StatusCodeThe HTTP status code being rendered.RequestIdThe 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.
PwaDisplayMode
SourceDisplay 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.
ConventionalExceptionPageRenderer
SourceResolves 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.
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.
RenderAsync
Task RenderAsync(HttpContext httpContext)
Source
Renders the resolved conventional 500 view into the current HTTP response.
Parameters
httpContextThe 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.
AppSurfaceHealthEndpointDefaults
SourceProvides the default AppSurface Web platform probe endpoint paths.
PwaWorkerOptions
SourceConfigures 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.
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.
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.
HasServiceWorkerPathConflict
bool HasServiceWorkerPathConflict { get; }
Source
Gets a value indicating whether legacy and current worker path properties were assigned conflicting values.
AppSurfaceWebDevelopmentPortDefaults
SourceResolves a deterministic development port for AppSurface web hosts in development when the caller has not already supplied explicit ASP.NET Core endpoint configuration.
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
argsThe command-line arguments supplied by the caller.currentDirectoryThe current working directory for the process.applicationBaseDirectoryThe application base directory for the host entry assembly.environmentReaderReads environment variables needed to detect the environment and explicit endpoint configuration.environmentVariableNamesThe 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.
AppSurfaceWebDevelopmentPortResolution
SourceDescribes the effective command-line arguments after AppSurface web development defaults have been resolved.
Parameters
ArgsThe effective arguments that should be passed into host startup.AppliedPortThe fallback port applied by the resolver, if any.SeedPathThe normalized workspace or project path used to compute the fallback port.
PwaHeadMetadataBuilder
SourceBuild
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
pathBaseThe request path base prepended to app-root-relative values.optionsThe validated PWA options.fileVersionProviderAn optional provider for versioning install icon URLs.
Returns
Encoded head markup, or an empty string when no PWA surface is active.
ConventionalExceptionPageDefaults
SourceDefines the conventional paths used by AppSurface's built-in browser-friendly production 500 handling.