Core

Remarks

This helper enforces lexical containment and does not resolve symbolic-link targets. Use a filesystem posture check as well when callers must reject links or aliases.

Remarks

FindRepositoryRootCore calls GetExistingFileDirectory only after File.Exists(string?) has accepted startPath as an existing file. The method normalizes the value with Path.GetFullPath(string) so relative file paths are canonicalized before returning the directory portion from Path.GetDirectoryName(string?) . If normalization cannot produce a containing directory, ArgumentException.ThrowIfNullOrEmpty(string?, string?) throws to surface the broken existing-file invariant instead of silently probing from an unrelated fallback path.

Remarks

The explicit drive-letter and leading-separator checks reject Windows-looking inputs even on Unix hosts, so a configuration validated on one operating system cannot become rooted when consumed on another.

Remarks

Components are whitespace-trimmed before comparison because Windows filesystem APIs can discard surrounding whitespace from path components. The comparison remains ordinal and does not reject dots embedded in names.

Remarks

The separator appended to the descendant prefix prevents sibling names that merely share the base path text from matching. This is a lexical check and does not resolve symbolic links.

Remarks

This follows the repository's supported operating-system boundary. It does not probe per-volume case sensitivity.

Remarks

Validates loaded assembly identities and references before invoking CreateRootModule . A custom root factory that loads additional plugins must validate their metadata before scanning or activating their types. Factory exceptions propagate to the caller without being relabeled as compatibility failures.

Remarks

By default this method emits an informational shutdown log via logger.LogInformation("Run Exited - Shutting down") after host.RunAsync() completes. When StartupContext.ConsoleOutputMode is ConsoleOutputMode.CommandFirst , that shutdown log is suppressed so command-first console flows can keep help and validation output free of lifecycle noise. Logs a warning if shutdown is cancelled or does not complete in time. On an unhandled exception logs a critical error and sets Environment.ExitCode to -100 .

Remarks

The string RunAsync(string[]) entry point validates already loaded assembly contracts before calling this factory. Overrides retain control of root construction. If an override loads plugins, call AppSurfacePackageCompatibility.ValidateAssemblies on those assemblies before type discovery or activation.

Remarks

App-type startups normally let AppSurface call this during host-builder creation. Specialized startup lifecycles may call it earlier when they need module-derived options before building the host. For example, CLI hosts that need packaged-asset or web-option defaults before the Generic Host exists should call RegisterDependencies(context) before reading those settings.

The method adds Defaults.InternalServicesModule first, invokes IAppSurfaceModule.RegisterDependentModules(ModuleDependencyBuilder) on the root module, and then marks StartupContext.DependenciesRegistered so repeated calls are no-ops for the same context. This method is not thread-safe; access each StartupContext from a single thread during startup.

Before the first dependency callback, loaded package identities and references are checked by AppSurfacePackageCompatibility.ValidateAssemblies . This also protects specialized startups that prepare dependencies before creating a host builder. Module callbacks that load more plugins own their metadata validation before activation; this check does not intercept assembly loading inside user code.

Remarks

When streamOutput is enabled, output is drained concurrently from both pipes, logged as lines arrive, and still buffered into the returned CommandResult . Any exception thrown by the logger or stderrLogLevelSelector is allowed to propagate so callers do not receive a partial success result with truncated output. The returned CommandResult preserves the exact standard output and standard error characters emitted by the process in both streaming and non-streaming modes.

Remarks

This method is internal so tests can deterministically verify the stream-drain and cancellation behavior without depending on timing-sensitive child-process races.

Remarks

The module instance is created with the new() constraint and pre-registered before IAppSurfaceModule.RegisterDependentModules(ModuleDependencyBuilder) runs. That pre-registration prevents infinite recursion for cyclic module graphs and means dependency callbacks observe already-created module instances. Prefer manual registration or a factory-based composition root when module construction needs dependency injection, runtime arguments, or externally owned disposable resources. If dependency registration throws, the newly created module remains in the builder, so later AddModule{T} calls for that same type are no-ops against a partial graph. Treat registration failures as fatal for the current builder instance.

Remarks

Implementations should be side-effect-free and preserve the platform's environment-name behavior: Windows is generally case-insensitive, while Unix-like systems are case-sensitive. Return defaultValue only when the variable is unset and the underlying lookup returns null ; an explicitly empty variable is a real empty string and should not be replaced by the default.

Remarks

Use a snapshot when inspecting native name spellings together or when one operation needs a consistent inventory. Use GetEnvironmentVariable for a point read of one known name. Implementations must preserve empty values and must not fold names or combine separate captures.

Remarks

ConfigureServices should add deterministic registrations to services and should tolerate being called during host construction before the application is running. Do not resolve runtime services or perform blocking I/O here unless the module explicitly documents that startup cost.

Remarks

Dependencies should be declared before their services are required. ModuleDependencyBuilder handles duplicate module types and pre-registers modules to avoid recursive cycles, but modules should still avoid relying on incidental traversal order for behavior.

Remarks

Contract assembly names are matched case-insensitively and must have assembly version 0.2.0.0. This is an assembly-contract check, not a NuGet package-version or API-content check. Dynamic assemblies are skipped because they do not provide a finalized persisted reference table. Metadata read failures propagate unchanged.