Docs

Remarks

This helper centralizes prefix trimming so graph and route-candidate generation do not drift when RoutePrefix is omitted.

Remarks

During post-configuration this method rehydrates null nested option blocks with defaults, trims nullable string settings such as repository roots and contributor URL templates, normalizes AppSurfaceDocsRoutingOptions.RouteRootPath and AppSurfaceDocsRoutingOptions.DocsRootPath through DocsUrlBuilder.NormalizeRouteRootPath(string?, string, bool) and DocsUrlBuilder.NormalizeDocsRootPath(string?, bool) , trims AppSurfaceDocsVersioningOptions.CatalogPath , normalizes AppSurfaceDocsLocalizationOptions.DefaultLocale to en when blank, trims locale AppSurfaceDocsLocaleOptions.Code , AppSurfaceDocsLocaleOptions.Label , AppSurfaceDocsLocaleOptions.Lang , and AppSurfaceDocsLocaleOptions.RoutePrefix values while skipping null locale entries, and removes blank or duplicate sidebar namespace prefixes. Callers that omit AppSurfaceDocsOptions.Routing , AppSurfaceDocsOptions.Versioning , or AppSurfaceDocsOptions.Localization can therefore still rely on a fully populated options object after registration. When AppSurfaceDocsHarvestOptions.FailOnFailure is enabled, the registered startup preflight fails the host only when the aggregate harvest health is failed.

When AppSurfaceDocsRoutingOptions.DocsRootPath is omitted or whitespace, the live docs root is derived from the normalized AppSurfaceDocsRoutingOptions.RouteRootPath through DocsUrlBuilder.ResolveDefaultDocsRootPath(string, bool) . For example, AppSurfaceDocs:Routing:RouteRootPath=/foo/bar with versioning enabled produces /foo/bar/next as the default live root. Callers that set both AppSurfaceDocsRoutingOptions.RouteRootPath and AppSurfaceDocsRoutingOptions.DocsRootPath should keep the pair coherent so stable entry, archive, exact-version, and live preview routes compose predictably after DocsUrlBuilder.NormalizeRouteRootPath(string?, string, bool) and DocsUrlBuilder.NormalizeDocsRootPath(string?, bool) run.

The method also registers DocsUrlBuilder , the internal docs recovery-link builder, AppSurfaceDocsAssetVersioner , and AppSurfaceDocsVersionCatalogService as singleton downstream services alongside the standard harvesters, memo cache, and DocAggregator . AppSurfaceDocsAssetVersioner supplies content-derived cache keys for AppSurface Docs-owned CSS and JavaScript assets rendered by the package views. It also registers RazorWire through RazorWireServiceCollectionExtensions and adds harvest observability services such as AppSurfaceDocsHarvestCoordinator , AppSurfaceDocsHarvestProgressReporter , and AppSurfaceDocsHarvestPathPolicy .

If an IRazorWireStreamAuthorizer is already registered, AppSurface Docs wraps that result-bearing authorizer so hidden harvest routes deny first and AppSurfaceDocs:Diagnostics:OperatorReadPolicy , when configured, authorizes the docs-owned harvest-progress channel before custom authorizers may narrow access. Existing IRazorWireChannelAuthorizer registrations still work through the legacy bool facade when plain allow/deny compatibility is sufficient and no shared read policy is configured. Register a custom authorizer before calling this method to participate in that wrapper. Registering an IRazorWireStreamAuthorizer after this method replaces the AppSurface Docs wrapper for normal stream authorization, but the docs-owned harvest stream still passes through the hidden-route and shared read-policy gate before that replacement authorizer can narrow access. Use AppSurfaceDocsStreamAuthorization.IsHarvestProgressChannel(string?) in host authorizers that need to distinguish the package stream from application streams. Built-in RazorWire allow-all/deny-all authorizers are not considered custom authorization for that docs-owned stream. Call this method once during startup; repeated registration can nest authorizer wrappers and obscure the intended channel policy.

When no IAppSurfaceThemeResolver is registered, this method adds the built-in AppSurface pair with the legacy AppSurfaceThemeMode.Dark default. It always registers the Web theme-document services so the package layout can emit the root and head theme integration. Register a host-selected pair and resolver before this method to use System, Light, or a different Dark pair.

AppSurfaceDocs:Diagnostics:OperatorReadPolicy names an optional host-owned ASP.NET Core authorization policy for exposed diagnostics read routes such as {DocsRootPath}/_harvest , {DocsRootPath}/_routes , and {DocsRootPath}/_routes.json . It also protects {DocsRootPath}/_health and {DocsRootPath}/_health.json when AppSurfaceDocs:Harvest:Health:AuthorizationPolicy is absent. The health policy remains a health-only compatibility policy and wins for health routes when both are configured. Hosts that configure either policy must register authentication before authorization in the endpoint-aware middleware phase. Consumers that resolve AppSurfaceDocsOptions directly should expect the normalized values rather than raw configuration text, and applications that need custom routing or catalog paths should provide those values before this method runs so the normalized singleton graph stays consistent.

Remarks

Named composition is for hosts with independently governed Docs products, such as public documentation at /docs and contributor documentation at /internal/docs . It creates no unkeyed default Docs graph; callers must retain the returned handle, call AppSurfaceDocsInstance.MapEndpoints once per handle, attach any host authorization conventions, and call AppSurfaceDocsEndpointRouteBuilderExtensions.FinalizeAppSurfaceDocsInstances once. Do not combine this overload with AddAppSurfaceDocs(IServiceCollection) or AppSurfaceDocsWebModule .

Remarks

This rehydrates absent nested option blocks, trims nullable string settings, normalizes route and public-origin values, normalizes glob and locale collections, and removes duplicate sidebar namespace prefixes. Callers must invoke this before validation so legacy post-configuration and named-runtime construction share the same route, source, and origin contract.

Remarks

Both legacy and named Docs composition use this helper so a host receives the same event capture behavior without coupling named products to the legacy unkeyed Docs options graph.

Remarks

The standalone executable uses a tiny root module from its own assembly so MVC can discover app-owned Razor views. The assembly metadata marker lets that executable keep the same root-host asset and redirect behavior without requiring the reusable Docs package to reference the standalone assembly.

Remarks

Call after PathBase/forwarded-path setup and before UseRouting, authentication, authorization and any response writer. Map named handles and finalize them on this builder after installing this hook. The hook selects the actual convention-bearing endpoint; the host's normal middleware evaluates authorization before its delegate. Repeated calls on this builder are idempotent. Alias-free catalogs require no hook. Default module hosts install it automatically. See the Docs consumer guide's named-host alias example and README alias diagnostics.

Remarks

Adds the AppSurface Docs harvesting, aggregation, and sanitization services via services.AddAppSurfaceDocs() . AppSurface Docs styling is compiled into the package during the AppSurface Docs build and the layout resolves the correct static asset path for root-module versus embedded consumer hosts, so hosts do not register services.AddTailwind() just to light up the embedded docs UI.

Remarks

This hook only mutates the pipeline when versioning is enabled and the resolved AppSurfaceDocsVersionCatalogService yields an available published tree or an active alias declaration. The module mounts exact-version exports and the independently selected recommended tree, shares those resources with healthy named aliases, and installs received-path ownership before host routing and auth. Owned alias requests execute their actual mapped endpoint after the host's authorization middleware.

Remarks

Public exact-version mounts always preserve the authored catalog order. When the recommended release points at a public exact tree, this helper adds the configured route-family root alias as an extra mount root that reuses the same PhysicalFileProvider instance instead of duplicating file watchers for the same export path. Frozen route manifest caches follow the same reuse rule: exact tree paths are resolved to full paths, trimmed of trailing directory separators, and compared with the platform-aware physical path comparer so canonical and recommended mounts that point at the same tree share one AppSurfaceDocsFrozenRouteManifestCache when they have the same verification model. If a later mount for the same tree has a verified release archive and the existing cache is still an unverified lazy filesystem cache, the helper replaces that cache entry with a verified snapshot built from AppSurfaceDocsVerifiedReleaseArchive.FrozenRouteManifest . Consumers should treat the returned cache instances as immutable mount dependencies: recommended aliases and public version mounts observe the verified snapshot when one exists, otherwise they share the same lazy filesystem-backed read model.

Remarks

When AppSurface Docs is the root module assembly, standalone and static-export hosts preserve the historical /css/site.gen.css URL by redirecting it to the packaged Razor Class Library stylesheet at /_content/ForgeTrust.AppSurface.Docs/css/site.gen.css . Embedded hosts do not register that redirect because they already link to the packaged asset directly. Redirects preserve the request HttpRequest.PathBase and query string so legacy links continue to work behind a virtual path, but the path base and configured package target must remain single-slash app-relative path components.

When versioning is enabled, this hook also reserves the stable version entry route at the configured route-family root, adds the archive surface below that route root, and serves preview-surface assets from either the live web root or the packaged Razor Class Library depending on whether published-tree mounts can shadow the stable docs root. Asset routes are built with DocsUrlBuilder.BuildAssetUrl(string) for search.css , minisearch.min.js , search-client.js , and the page-local outline-client.js and rich-authoring-client.js . The packaged AppSurface brand icon is also served from an embedded fallback so static exports that disable static-web-assets can still validate the layout image. Consumer-owned branding assets can be served from a configured filesystem directory, including directories outside AppSurface Docs packaged static web assets, under a dedicated request prefix. Preview hosts can serve those files directly from the web root; otherwise the current-surface URLs redirect through ResolveLegacySearchAssetBasePath to the packaged AppSurface Docs assets. Legacy asset redirects preserve only the request query string, while the redirect path itself is constrained to an app-relative URL so cache-busting parameters cannot turn the redirect into an external hop. Route ordering matters: index, search, search-index, section, and catch-all routes are registered from most to least specific so the live preview root continues to behave correctly even when the current docs root is root-mounted or overlaps published exact-version aliases.

When AppSurface Docs is the root module, the bare application root redirects to the configured docs home and /favicon.ico serves the packaged AppSurface Docs document-layers SVG mark unless the host configures AppSurfaceDocsFaviconOptions.SvgPath . In that case /favicon.ico redirects to the configured SVG path so standalone docs hosts can keep the conventional browser favicon probe aligned with rendered <link rel="icon"> metadata. Embedded hosts do not get these root routes; their owning app should decide what / and /favicon.ico mean.

The operator-facing diagnostics route patterns are always registered before the catch-all docs route so {DocsRootPath}/_harvest , {DocsRootPath}/_harvest/rebuild , {DocsRootPath}/_health , {DocsRootPath}/_health.json , {DocsRootPath}/_routes , and {DocsRootPath}/_routes.json remain reserved operator paths rather than falling through to document lookup. The route named appsurfacedocs_harvest maps the current docs root harvest observatory pattern from DocsUrlBuilder.BuildHarvestUrl to DocsController.Harvest . The route named appsurfacedocs_harvest_rebuild maps DocsUrlBuilder.BuildHarvestRebuildUrl to DocsController.RebuildHarvest . The route named appsurfacedocs_harvest_health maps the current docs root health pattern from DocsUrlBuilder.BuildHealthUrl to DocsController.HarvestHealth , and appsurfacedocs_harvest_health_json maps DocsUrlBuilder.BuildHealthJsonUrl to DocsController.HarvestHealthJson . Route inspector routes map DocsUrlBuilder.BuildRouteInspectorUrl and DocsUrlBuilder.BuildRouteInspectorJsonUrl to DocsController.RouteInspector and DocsController.RouteInspectorJson . The controller actions still gate responses with their exposure options: harvest health uses AppSurfaceDocsHarvestHealthVisibility.AreRoutesExposed(AppSurfaceDocsOptions, IHostEnvironment) : by default they return health only in Development, while production hosts must opt in with AppSurfaceDocsHarvestHealthOptions.ExposeRoutes ; route inspector uses AppSurfaceDocsDiagnosticsOptions.ExposeRouteInspector . These routes are intended for local and operator verification, not as unauthenticated public reader navigation.

The route named appsurfacedocs_search_index_refresh maps the pattern produced by DocsUrlBuilder.BuildSearchIndexRefreshUrl to DocsController.RefreshSearchIndex . That operator route is browser-form-shaped and accepts only POST ; the companion unsupported-method endpoint rejects common non-POST verbs with HTTP 405 and an Allow: POST response header instead of letting the request fall through to reader document lookup or status-code-page rendering.

The route named appsurfacedocs_markdown_download maps the reserved {DocsRootPath}/_markdown/{**path} pattern to DocsController.DownloadMarkdown . It accepts only GET and HEAD ; other methods receive HTTP 405 with Allow: GET, HEAD . When MarkdownDownload.Enabled is true, the route requires the named host-owned authorization policy; when it is false, the route permits anonymous routing but the action returns 404. It is registered before the document catch-all so reserved _markdown paths cannot fall through to document lookup.

Remarks

The caller supplies a route group already carrying AppSurfaceDocsEndpointMetadata and any host-owned authorization conventions. Every route in this method therefore resolves one runtime through endpoint metadata rather than an ambient default Docs service. Named published-tree handlers reserve only exact-version routes, so host authorization conventions protect archive reads without preventing unmatched live Docs routes from reaching their controller endpoints.

Remarks

These fallback routes intentionally map on the common finalized route builder rather than an individual product group. A single package asset URL must not inherit one product's endpoint metadata or authorization convention.

Remarks

Returns null when no health or shared read policy should be applied, when no IWebHostEnvironment is available, or when the health routes are not exposed for the current environment. ApplyHealthAuthorizationPolicy depends on this ordering so hidden health routes keep returning 404 before authorization metadata is added. The legacy health policy takes precedence when it is configured; otherwise the shared diagnostics read policy protects exposed health routes.

Remarks

This helper intentionally treats query text as data appended after the validated path. It validates the unescaped path base so unsafe separators are not hidden by URI formatting, then emits the escaped path base used for redirect headers. A root path base ( / ) is normalized to empty so the redirect stays single-slash local. It does not allow the path base or target path to be absolute, protocol-relative, backslash-prefixed, or control-character-bearing because those shapes can be interpreted by clients as redirects away from the current host.

Remarks

This method accepts only relative browser paths that decode cleanly, do not contain rooted paths, backslashes, control characters, or traversal segments, and end with an allowed branding image extension. It rejects .svg unless allowSvgAssets is true .

Callers should pass the raw route value before filesystem joining or other path normalization. Do not pass already-normalized absolute paths, rely on the filename alone, or treat a successful result as content-level sanitization. Enabling SVG serving expands the attack surface because SVG is active document content; this helper only enforces path and extension safety and does not optimize or sanitize SVG bytes.

Remarks

This method does not publish endpoints immediately. That lets finalization validate every declaration and build every runtime before publishing the first Docs route. Call AppSurfaceDocsEndpointRouteBuilderExtensions.FinalizeAppSurfaceDocsInstances after mapping every declared handle. A handle can be mapped exactly once. If endpoint publication later fails, the registry becomes terminal so the current route table cannot accidentally receive a duplicate partial mapping; recreate the host after correcting the failure.

Remarks

All returned AppSurfaceDocsInstance handles must be mapped exactly once before this call. The registry snapshots named configuration and constructs each isolated runtime before it maps any product routes. Calling this method twice, retrying it after an endpoint-publication failure, mapping after this call, or leaving a declared handle unmapped throws an actionable startup error instead of selecting a legacy/default runtime implicitly. A failed finalization is terminal because ASP.NET Core endpoint route builders do not support atomically removing a partially published endpoint family; correct the startup configuration or convention and recreate the host.