--- title: Configuration settings summary: Configuration keys consumed by this library, retrieval methods, and runtime dependencies. status: draft owner: Messaging Platform Team last_reviewed: 2026-10-21 library: SAIF.NCore.Messaging reference_type: package --- # Configuration settings SAIF.NCore.Messaging reads ten settings through three mechanisms: seven keys under the `Messaging` section of `IConfiguration`, bound to `MessagingOptions` and `OutboxOptions`; two values from `IEnvironmentClient`, one plain and one secure, applied to `MessagingOptions` after binding; and one process environment variable that disables the outbox dispatcher. Only `Messaging:ServiceName` is mandatory. The configuration keys are read when an options object is first resolved, and the environment variable is read once, while `AddSaifMessagingOutbox` runs at startup. ## Configuration retrieval methods | Method | Class / Interface | Namespace | Usage pattern | | --- | --- | --- | --- | | `Configure` | IServiceCollection | Microsoft.Extensions.DependencyInjection | `AddSaifMessaging` binds the `Messaging` section to `MessagingOptions`, and `AddSaifMessagingOutbox` binds `Messaging:Outbox` to `OutboxOptions`. | | GetSettingValue | IEnvironmentClient | SAIF.NetCore.Environment | Called by `ConfigureMessagingOptions.PostConfigure` with section `Messaging` and key `TopicPrefix`, only after `HasSetting` returns true. | | HasSetting | IEnvironmentClient | SAIF.NetCore.Environment | Called by `ConfigureMessagingOptions.PostConfigure` to test for `Messaging:TopicPrefix` before reading it. | | GetSecureSetting | IEnvironmentClient | SAIF.NetCore.Environment | Called by `ConfigureMessagingOptions.PostConfigure` with section `Messaging`, key `ConnectionString`, and the `SystemType` argument; decryption happens inside the environment client. | | GetEnvironmentVariable | Environment | System | Called by `AddSaifMessagingOutbox` with the variable name and no target, so the process scope is read. | ## Environment API settings Settings retrieved via `IEnvironmentClient` (centralized environment configuration client). | Setting key | Method | Data type | Purpose | Consuming class | Source | | --- | --- | --- | --- | --- | --- | | `Messaging:TopicPrefix` | `GetSettingValue` | String | Prefix prepended to every topic name so lower environments do not share topics with production. | ConfigureMessagingOptions | src/SAIF.NCore.Messaging/Options/ConfigureMessagingOptions.cs | ## appsettings.json and IConfiguration Settings read through `IConfiguration` (`appsettings.json`, `appsettings..json`, environment variables, and any other configured provider). | Setting key | Required | Default value | Retrieval | Purpose | Consuming class | Source | | --- | --- | --- | --- | --- | --- | --- | | `Messaging:ServiceName` | Yes | None | `Configure` | Name stamped on every outgoing message envelope as its source. `MessagePublisher` throws when the value is empty. | MessagePublisher | src/SAIF.NCore.Messaging/Options/MessagingOptions.cs | | `Messaging:DefaultTopic` | No | `saif.events` | `Configure` | Topic used when `Publish` is called without an explicit topic. | MessagePublisher | src/SAIF.NCore.Messaging/Options/MessagingOptions.cs | | `Messaging:MaxDeliveryAttempts` | No | `5` | `Configure` | Handler attempts for a message before it is dead-lettered. | MessageHandlerDispatcher | src/SAIF.NCore.Messaging/Options/MessagingOptions.cs | | `Messaging:PublishTimeoutSeconds` | No | `30` | `Configure` | Time limit for one send to the message bus. | ServiceBusClientAdapter | src/SAIF.NCore.Messaging/Options/MessagingOptions.cs | | `Messaging:Outbox:PollIntervalSeconds` | No | `10` | `Configure` | Seconds between outbox dispatch cycles. | OutboxDispatchService | src/SAIF.NCore.Messaging/Options/OutboxOptions.cs | | `Messaging:Outbox:BatchSize` | No | `100` | `Configure` | Maximum pending outbox rows read in one dispatch cycle. | OutboxDispatchService | src/SAIF.NCore.Messaging/Options/OutboxOptions.cs | | `Messaging:Outbox:RetentionHours` | No | `72` | `Configure` | Hours a dispatched outbox row is kept before `SqlOutboxStore` purges it. | SqlOutboxStore | src/SAIF.NCore.Messaging/Options/OutboxOptions.cs | ## Environment variables | Variable | Scope read | Accepted values | Default when unset | Effect | Source | | --- | --- | --- | --- | --- | --- | | `SAIF_MESSAGING_DISABLE_DISPATCH` | Process | `true` or `false`, case-insensitive; any other value is treated as `false` | `false` | When `true`, `AddSaifMessagingOutbox` does not register `OutboxDispatchService`. The process still writes outbox rows but never dispatches them. The value is read once at startup, so a change needs a restart. | src/SAIF.NCore.Messaging/Extensions/ServiceCollectionExtensions.cs | ## Secure settings Settings that require decryption or credential retrieval. | Setting key | Encryption method | Purpose | Consuming class | Source | | --- | --- | --- | --- | --- | | `Messaging:ConnectionString` | Decrypted by `IEnvironmentClient.GetSecureSetting` using the `SystemType` argument `SystemType.Messaging` | Connection string for the service bus namespace used by `ServiceBusClientAdapter`. | ConfigureMessagingOptions | src/SAIF.NCore.Messaging/Options/ConfigureMessagingOptions.cs | ## Transitive configuration (from dependencies) Settings required at runtime by referenced libraries or packages, not directly consumed by this library's code. | Setting key | Method | Source dependency | Dependency type | Purpose | | --- | --- | --- | --- | --- | | `AppSettings:ApplicationHost` | `IConfiguration` | SAIF.NetCore.ServiceExtensions | NuGet | Names the host the environment client requests settings for, so every `IEnvironmentClient` call made by this library resolves against the right host†. | | `AppSettings:ApplicationName` | `IConfiguration` | SAIF.NetCore.ServiceExtensions | NuGet | Names the application the environment client requests settings for†. | ## Configuration dependencies | Dependency | Type | Required at | Impact if missing | | --- | --- | --- | --- | | IEnvironmentClient | service | Runtime, when `MessagingOptions` is first resolved | `ConfigureMessagingOptions` cannot be constructed, so resolving `IOptions` throws `InvalidOperationException` and `MessagePublisher` and `ServiceBusClientAdapter` fail to resolve. | | `Messaging` section in appsettings.json | section | Runtime, when `MessagePublisher` is first resolved | `MessagingOptions` keeps its code defaults, but `ServiceName` has none, so `MessagePublisher` throws `InvalidOperationException` on first resolution and nothing can be published. | | `Messaging:ConnectionString` secure setting | secure setting | Runtime, when `ServiceBusClientAdapter` is first resolved | The connection string stays unset and `ServiceBusClientAdapter` throws `InvalidOperationException` on first resolution; no message is sent or received. | | `Messaging:TopicPrefix` setting | setting | Runtime, when `MessagingOptions` is first resolved | `HasSetting` returns false and the prefix stays empty, so topic names are used unprefixed. | | `IOutboxConnectionFactory` | service | Runtime, on each outbox dispatch cycle and each outbox publish | `SqlOutboxStore` cannot be constructed. `OutboxDispatchService` logs the failure and retries after the poll interval, and `MessagePublisher` throws `InvalidOperationException` when it resolves the outbox store. | ## Related documentation - Index - Overview - Architecture - Dependencies - Operations and processes - Business rules - [Service registration](service-registration.md) - API reference > **Note:** Statements marked with `†` are derived from dependency library > documentation via the Legends CLI. They describe inherited behavior from the > indicated origin library and should be verified if the dependency version changes. ## Sources - src/SAIF.NCore.Messaging/Extensions/ServiceCollectionExtensions.cs - src/SAIF.NCore.Messaging/Options/MessagingOptions.cs - src/SAIF.NCore.Messaging/Options/OutboxOptions.cs - src/SAIF.NCore.Messaging/Options/ConfigureMessagingOptions.cs - src/SAIF.NCore.Messaging/Hosting/OutboxDispatchService.cs - src/SAIF.NCore.Messaging/Outbox/SqlOutboxStore.cs - src/SAIF.NCore.Messaging/SAIF.NCore.Messaging.csproj