string Environment { get; }
Gets the current environment name (e.g., "Development", "Staging", "Production").
Core
Namespaces
ForgeTrust.Runnable.Core
The foundation of the Runnable ecosystem. This package defines the core abstractions, the startup pipeline, and the module system that powers all other Runnable libraries.
Overview
The Core library is designed to be lightweight and implementation-agnostic. it provides the infrastructure to:
- Define Modules (
IRunnableModule,IRunnableHostModule) that encapsulate logic. - Manage Dependency Graphs between modules.
- Provide a consistent Startup Pipeline (
RunnableStartup) that sits on top of the .NET Generic Host.
Key Concepts
IRunnableModule: The base interface for any unit of functionality that needs to register services or configure the application.StartupContext: Provides metadata about the running application (e.g., environment, entry point assembly).RunnableStartup: The base class that orchestrates the host building and service registration process.
Usage
Most users will use a more specialized package like ForgeTrust.Runnable.Web or ForgeTrust.Runnable.Console, which inherit from the abstractions provided here.
RunnableStartup
Provides a base implementation for starting and running applications with module support.
GetStartupLogger
ILogger GetStartupLogger()
Provides an ILogger named after the concrete startup type.
Returns
An ILogger whose category name is the concrete startup type's name.
RunnableStartup<TRootModule>
An abstract base class for initializing a Runnable application with a specific root module.
Type Parameters
TRootModuleThe type of the root module for the application.
RunAsync
3 overloads
Task IRunnableStartup.RunAsync(StartupContext context)
Runs the startup sequence using the provided startup context.
Parameters
contextStartup configuration including application arguments, root module, and dependency/module registrations.
Returns
A task that completes when the startup sequence finishes.
Task RunAsync(string[] args)
Starts the application's run sequence using the specified command-line arguments.
Parameters
argsCommand-line arguments supplied to the application.
Returns
A task that completes when the host run finishes.
Task RunAsync(StartupContext context)
Runs the host configured by the provided startup context and logs lifecycle events.
Parameters
contextContext containing application name, root module, dependencies, and any custom registrations used to build and configure the host.
Returns
A task that completes when the host run has finished and shutdown processing is complete.
Remarks
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.
CreateHostBuilder
IHostBuilder IRunnableStartup.CreateHostBuilder(StartupContext context)
Creates an IHostBuilder configured for the provided startup context.
Parameters
contextThe startup context whose application name, modules, and registrations drive host configuration.
Returns
An IHostBuilder configured according to the given context.
CreateHost
IHost CreateHost(StartupContext context)
Builds an IHost from the host builder configured for the provided startup context.
Parameters
contextThe startup context that provides application name, modules, and configuration used to construct the host.
Returns
The constructed IHost.
CreateHostBuilderCore
IHostBuilder CreateHostBuilderCore(StartupContext context)
Create and configure a host builder using values from the provided startup context.
Parameters
contextStartup context containing the ApplicationName, RootModule, and Dependencies used to configure the host builder.
Returns
A host builder configured with the context's application name, registered modules, and service registrations.
CreateRootModule
TRootModule CreateRootModule()
Creates a new instance of the root module.
Returns
A new TRootModule instance.
ConfigureServicesForAppType
void ConfigureServicesForAppType(StartupContext context, IServiceCollection services)
Registers services required for the specific application type (for example, web or worker) into the provided service collection.
Parameters
contextStartup context containing application metadata, dependencies, and configuration used during registration.servicesThe service collection to which app-type-specific services should be added or overridden.
ConfigureBuilderForAppType
IHostBuilder ConfigureBuilderForAppType(StartupContext context, IHostBuilder builder)
Allows the startup to customize the host builder for the specific application type.
Parameters
contextThe startup context containing application metadata and dependency modules.builderThe host builder to customize.
Returns
The configured IHostBuilder (by default returns the provided builder unchanged).
IRunnableStartup
Defines the entry point for starting and running a Runnable application.
CreateHostBuilder
IHostBuilder CreateHostBuilder(StartupContext context)
Creates and configures the IHostBuilder for the application.
Parameters
contextThe startup context containing configuration and arguments.
Returns
A configured host builder.
RunAsync
Task RunAsync(StartupContext context)
Runs the application asynchronously using the provided startup context.
Parameters
contextThe startup context for the application.
Returns
A task that represents the asynchronous run operation.
IEnvironmentProvider
Provides information about the application's environment and configuration variables.
GetEnvironmentVariable
string? GetEnvironmentVariable(string name, string? defaultValue = null)
Gets the value of an environment variable.
Parameters
nameThe name of the environment variable.defaultValueThe value to return if the environment variable is not set.
Returns
The value of the environment variable, or the default value if not found.
Environment
IsDevelopment
bool IsDevelopment { get; }
Gets a value indicating whether the current environment is "Development".
StartupContext
Provides context and configuration during the application startup process.
Parameters
ArgsCommand-line arguments provided to the application.RootModuleThe root module of the application.ApplicationNameOptional name of the application.EnvironmentProviderOptional provider for environment information.CustomRegistrationsOptional custom service registrations.
GetDependencies
IReadOnlyList<IRunnableModule> GetDependencies()
Gets the list of modules that the application depends on.
Returns
A read-only list of dependent modules.
OverrideEntryPointAssembly
Assembly? OverrideEntryPointAssembly { get; set; }
Gets or sets an assembly that should be treated as the entry point assembly, overriding the default.
RootModuleAssembly
Assembly RootModuleAssembly { get; }
Gets the assembly that contains the root module.
EntryPointAssembly
Assembly EntryPointAssembly { get; }
Gets the entry point assembly for the application.
EnvironmentProvider
IEnvironmentProvider EnvironmentProvider { get; }
Gets the environment provider for the application.
IsDevelopment
bool IsDevelopment { get; }
Gets a value indicating whether the current environment is development.
ApplicationName
string ApplicationName { get; }
Gets the name of the application.
ModuleDependencyBuilder
A builder used to discover and register module dependencies recursively.
AddModule
ModuleDependencyBuilder AddModule<T>()
Adds a module of type T and its dependencies to the builder.
Type Parameters
TThe type of the module to add.
Returns
The current ModuleDependencyBuilder instance.
Modules
IEnumerable<IRunnableModule> Modules { get; }
Gets the collection of registered modules.
CriticalService
A base class for background services that are critical to the application's operation. If a critical service fails or exits, the entire application will be shut down.
RunAsync
Task RunAsync(CancellationToken stoppingToken)
Implements the core logic of the critical service.
Parameters
stoppingTokenA token that is signaled when the service should stop.
Returns
A task that represents the service's execution.
LogInitialize
void LogInitialize(string serviceType)
Logs that the critical service is initializing.
Parameters
serviceTypeThe name of the service type.
LogStopping
void LogStopping(string serviceType)
Logs that the critical service is stopping.
Parameters
serviceTypeThe name of the service type.
LogException
void LogException(Exception exception, string serviceType)
Logs an unhandled exception that occurred in the critical service.
Parameters
exceptionThe unhandled exception.serviceTypeThe name of the service type.
IRunnableModule
Defines a module that can configure services and register dependencies within the Runnable host.
ConfigureServices
void ConfigureServices(StartupContext context, IServiceCollection services)
Configures the services for this module.
Parameters
contextThe context for the current startup process.servicesThe service collection to add registrations to.
RegisterDependentModules
void RegisterDependentModules(ModuleDependencyBuilder builder)
Registers other modules that this module depends on.
Parameters
builderThe builder used to declare module dependencies.
IRunnableHostModule
Defines a module that can specifically configure the IHostBuilder before and after service registration. Only the root module of an application (or explicitly marked host modules) usually implements this.
ConfigureHostBeforeServices
void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Configures the IHostBuilder before any modules have their services configured.
Parameters
contextThe context for the current startup process.builderThe host builder to configure.
ConfigureHostAfterServices
void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Configures the IHostBuilder after all modules have their services configured.
Parameters
contextThe context for the current startup process.builderThe host builder to configure.
PathUtils
Provides utility methods for operations on file and directory paths.
FindRepositoryRoot
string FindRepositoryRoot(string startPath)
Locates the nearest ancestor directory (starting at startPath) that contains a `.git` directory or file, effectively identifying the repository root.
Parameters
startPathThe path from which to begin searching upward for a repository root; may refer to a file or directory.
Returns
The full path of the nearest ancestor directory containing a `.git` directory or file, or the original startPath if none is found.
Exceptions
ArgumentExceptionThrown whenstartPathis null, empty, or consists only of whitespace.