Represents the AppSurface CLI root module used to bootstrap command execution.
The module is intentionally empty today: the CLI owns command registration in AppSurfaceCliApp and delegates web-host behavior to RazorDocs-specific runners. Add dependencies here only when every AppSurface CLI command needs the same module-level dependency graph or host lifecycle hook. Prefer command-local services or custom test registrations for isolated behavior, and do not place runtime command logic in this module.
void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Configures shared CLI services after the default command runtime registrations have been added.
contextStartup context for the CLI run.servicesService collection that will back command construction.The default implementation is a no-op. Keep it empty unless a service truly applies to the whole CLI surface.
void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Source
Configures a Generic Host builder before services are registered.
contextStartup context for the CLI run.builderHost builder that would be configured by host-based startup paths.The command runtime does not currently build a Generic Host through this module, so this hook is intentionally a no-op and exists to satisfy the shared AppSurface host-module contract.
void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Source
Configures a Generic Host builder after services are registered.
contextStartup context for the CLI run.builderHost builder that would be configured by host-based startup paths.Keep this empty until the CLI adopts a host-backed lifecycle. Command behavior should stay in command classes.
void RegisterDependentModules(ModuleDependencyBuilder builder)
Source
Registers root-module dependencies for the AppSurface CLI module graph.
builderDependency builder used by AppSurface startup composition.The CLI has no module dependencies by default. Add dependencies here only for cross-command infrastructure that must participate in AppSurface module ordering.
Internal CLI entry point that adds a scoped test seam around AppSurfaceCliApp.
Production code uses RunAsync directly. Tests can use PushConfigureOptionsOverrideForTests to add temporary console or DI overrides without changing the top-level statement in Program.cs.
Task RunAsync(string[] args, Action<ConsoleOptions>? configureOptions = null)
Source
Runs the AppSurface CLI with the specified arguments and optional console configuration.
argsCommand-line arguments to parse and execute.configureOptionsOptional primary console-options callback for the current invocation.A task that represents the CLI execution.
IDisposable PushConfigureOptionsOverrideForTests(Action<ConsoleOptions> configureOptions)
Source
Pushes a test-only console-options override for the current async context.
configureOptionsOverride callback to apply after any direct invocation callback.A disposable scope that restores the previous override when disposed.
Always dispose the returned scope, typically with using var. Overrides compose with RunAsync callbacks in direct-then-override order so tests can replace services after production defaults are configured.
Restores the previously active test override when disposed.
previousOverride that was active before the current scope was pushed.Previews RazorDocs for a local repository through the public appsurface docs command.
This command starts the RazorDocs standalone host with CLI-friendly defaults and delegates option validation and argument construction to RazorDocsPreviewCommand.
Previews RazorDocs for a local repository through the appsurface docs preview alias.
Use this alias when a command hierarchy reads better in scripts. It has the same options and behavior as DocsCommand.
Shared implementation for RazorDocs preview commands.
The base command translates CLI options into RazorDocs standalone host arguments. It keeps command parsing separate from process hosting so tests can verify validation and argument forwarding without starting Kestrel.
ValueTask ExecuteAsync(IConsole console)
Source
Executes the command through the CliFx console integration.
consoleConsole abstraction used to register cancellation handling.A value task that completes when the preview host exits or command validation fails.
ValueTask ExecuteAsync(CancellationToken cancellationToken)
Source
Executes the command using an explicit cancellation token.
cancellationTokenToken observed before the host runner starts.A value task that completes when the preview host exits.
This overload exists for tests and shared command execution paths that already own cancellation registration.
RazorDocsHostArgs BuildHostArgs()
Source
Translates CLI options into standalone RazorDocs host arguments.
The repository root, forwarded host arguments, and startup timeout for the preview run.
This method performs command-level validation so users receive CommandException errors before the web host starts. It is internal so tests can verify the translation contract without opening a listener.
string RepositoryRoot { get; init; }
Source
Gets the repository root to harvest and preview.
Defaults to the current directory. Use this when running the CLI from a parent directory, script workspace, or package output folder. The value must resolve to an existing directory.
string? Urls { get; init; }
Source
Gets the explicit URL binding forwarded to the RazorDocs host.
Use this for a full Kestrel binding such as http://127.0.0.1:5189. Prefer Port when only the port needs to change.
int? Port { get; init; }
Source
Gets the port shortcut forwarded to the RazorDocs host.
Use this for local preview scripts that only need a port override. Use Urls for explicit host, scheme, or multi-binding scenarios.
bool StrictHarvest { get; init; }
Source
Gets a value indicating whether startup should fail when every configured RazorDocs harvester fails.
Keep this off for exploratory local preview. Enable it in CI or release checks where a completely failed harvest should stop the command before the site starts.
string? RouteRootPath { get; init; }
Source
Gets the route-family root for RazorDocs version and archive routes.
Use this when the docs route family is mounted somewhere other than /docs, for example --route-root /reference. Pair it with DocsRootPath when the live preview path should differ from archive/version routes.
string? DocsRootPath { get; init; }
Source
Gets the live docs preview root path.
Use this to preview current docs under a nested route, for example --route-root /reference --docs-root /reference/next. Leave unset to use RazorDocs defaults.
string? EnvironmentName { get; init; }
Source
Gets the host environment forwarded to the RazorDocs standalone host.
Use Development for local preview diagnostics and development defaults. Leave unset to let the host choose its normal environment from command-line and process configuration.
double StartupTimeoutSeconds { get; init; }
Source
Gets the number of seconds to wait for the web host to start before failing fast.
Defaults to 30 seconds. Set to 0 to disable the startup watchdog. Negative, infinite, and NaN values are rejected before the host starts.
Describes the RazorDocs host invocation produced by the CLI option translator.
RepositoryRootAbsolute repository root that the RazorDocs host should harvest.ArgsCommand-line arguments forwarded to the standalone RazorDocs host.StartupTimeoutStartup watchdog timeout, or null when disabled.Starts a RazorDocs host for CLI preview commands.
This seam keeps command parsing and validation testable without starting a real web host. Production implementations should honor cancellation before delegating into long-running host lifetimes.
Task RunAsync(string[] args, TimeSpan? startupTimeout, CancellationToken cancellationToken)
Source
Runs the RazorDocs host with translated command-line arguments.
argsArguments forwarded to the standalone RazorDocs host.startupTimeoutStartup watchdog timeout, or null to disable it.cancellationTokenToken that cancels before the host is started.A task that completes when the host exits.
Production IRazorDocsHostRunner that delegates to the standalone RazorDocs web host.
Use this adapter for the packaged AppSurface CLI path. Tests should prefer fake runners so they can verify argument translation without starting Kestrel. The type is internal and sealed because callers should depend on IRazorDocsHostRunner rather than subclassing host lifetime behavior.
Provides the DI-backed execution runtime for AppSurface CLI commands.
This internal runtime exists so the top-level tool entry point stays thin while command discovery, dependency registration, logging defaults, and CliFx execution stay testable. It discovers commands from the AppSurface CLI entry assembly, applies module and caller-provided service registrations, temporarily assigns CommandService.PrimaryServiceProvider for constructor-injected command dependencies, and always restores the previous provider after command execution.
Task RunAsync(string[] args, Action<ConsoleOptions>? configureOptions = null)
Source
Runs the AppSurface CLI with the provided command-line arguments.
argsCommand-line arguments to parse and execute.configureOptionsOptional callback that customizes ConsoleOptions before execution. Defaults start from ConsoleOptions.Default with ConsoleOutputMode.CommandFirst so command output remains the primary console experience.A task that completes when the selected command finishes.
Use this seam from process entry points and tests that need the real command pipeline without shelling out. The method builds and disposes a fresh service provider for each run, registers AppSurface CLI defaults, then applies custom registrations last so tests or future host integrations can replace defaults intentionally.