MvcOptions Mvc { get; set; }
Source
Gets or sets MVC-specific configuration options, such as support levels and custom MVC configuration.
Web
Namespaces
WebOptions
SourceRepresents configuration options for the web application, including MVC, CORS, and static file settings.
Mvc
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.
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 30 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. 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.
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.
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.
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.
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.
ConventionalExceptionPageDefaults
SourceDefines the conventional paths used by AppSurface's built-in browser-friendly production 500 handling.
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.
CorsOptions
SourceRepresents configuration options for Cross-Origin Resource Sharing (CORS) policies.
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.
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.
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.
StaticFilesOptions
SourceRepresents configuration options for serving static files and web assets.
Default
StaticFilesOptions Default { get; }
Source
Gets a default instance of StaticFilesOptions with default configuration settings.
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.
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.
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.
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.
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, except when all origins are explicitly allowed in development.
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.).
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.
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.
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.
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.