Example: configuration¶

configuration.md records every configuration key a library reads, how it is retrieved, and which class consumes it. Doc gen produces it only when configuration access is detected, so the whole page is conditional.

What reviewers should check¶

The frontmatter title and the H1 are both Configuration settings. This page is not titled after the library, unlike the other library pages.
Every setting row names the consuming class and a repo-relative source path, so a reviewer can open the file and see the retrieval call.
Settings are placed in the right table by retrieval method: IEnvironmentService calls under Environment API settings, ConfigurationManager.AppSettings under AppSettings, and anything requiring decryption under Secure settings.
Sections with no rows are omitted entirely rather than left empty or filled with "None" or "N/A".
Transitive configuration lists settings the library does not read itself but which its dependencies require at runtime, with the source dependency named.
Configuration dependencies state the concrete failure behavior when something is missing, not just "the library will fail".

Example¶

The document below is a complete, correct configuration.md for a fictional library.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

---
title: Configuration settings
summary: Configuration keys consumed by this library, retrieval methods, and runtime dependencies.
status: draft
owner: Policy Systems Team
last_reviewed: 2026-02-18
library: SAIF.Framework.Validation
reference_type: package
---

# Configuration settings

SAIF.Framework.Validation reads eight settings through two retrieval methods:
`IEnvironmentService` for environment-scoped values such as the rule set
directory and cache behavior, and `ConfigurationManager.AppSettings` for the
two switches that consuming applications override per deployment. One value,
the rule set signing key, is retrieved through the secure configuration path
because it is stored encrypted. All settings are read by `RuleSetLoader` or
`ValidationEngine` on first use rather than at assembly load.

## Configuration retrieval methods

| Method | Class / Interface | Namespace | Usage pattern |
| --- | --- | --- | --- |
| GetConfigSetting | IEnvironmentService | SAIF.Framework.Core.Environment | Called by `RuleSetLoader.EnsureConfigured` with the setting key; returns the environment-specific string value. |
| GetSecureConfigSetting | IEnvironmentService | SAIF.Framework.Core.Environment | Called by `RuleSetLoader.VerifySignature` for encrypted values; decryption happens inside the environment service. |
| AppSettings | ConfigurationManager | System.Configuration | Read directly by `ValidationEngine.Validate` through `ConfigurationManager.AppSettings("key")` with a code default when absent. |

## Environment API settings

Settings retrieved via `IEnvironmentService` (centralized environment configuration service).

| Setting key | Method | Data type | Purpose | Consuming class | Source |
| --- | --- | --- | --- | --- | --- |
| `Validation.RuleSetPath` | `GetConfigSetting` | String | Directory containing the rule set XML files loaded at first evaluation. | RuleSetLoader | src/SAIF.Framework.Validation/RuleSetLoader.vb |
| `Validation.RuleSetCacheMinutes` | `GetConfigSetting` | Integer | Minutes a parsed rule set stays cached before it is re-read from disk. | RuleSetLoader | src/SAIF.Framework.Validation/RuleSetLoader.vb |
| `Validation.DefaultJurisdiction` | `GetConfigSetting` | String | Jurisdiction code applied when the calling application supplies no value in `IValidationContext`. | ValidationEngine | src/SAIF.Framework.Validation/ValidationEngine.vb |
| `Validation.TraceEvaluationTiming` | `GetConfigSetting` | Boolean | Enables per-rule timing entries in the framework trace log for performance investigation. | ValidationEngine | src/SAIF.Framework.Validation/ValidationEngine.vb |

## AppSettings (Web.config)

Settings retrieved via `ConfigurationManager.AppSettings`.

| Setting key | Default value | Purpose | Consuming class | Source |
| --- | --- | --- | --- | --- |
| `Validation.TreatWarningsAsFailures` | `false` | Promotes warning-severity results to blocking failures for deployments that require strict intake. | ValidationEngine | src/SAIF.Framework.Validation/ValidationEngine.vb |
| `Validation.MaxFailuresReturned` | `100` | Caps the number of failures returned in a single `ValidationResult` to bound batch error log size. | ValidationEngine | src/SAIF.Framework.Validation/ValidationEngine.vb |
| `Validation.RequireSignedRuleSets` | `true` | Requires a valid rule set signature before a rule set is loaded outside development environments. | RuleSetLoader | src/SAIF.Framework.Validation/RuleSetLoader.vb |

## Secure settings

Settings that require decryption or credential retrieval.

| Setting key | Encryption method | Purpose | Consuming class | Source |
| --- | --- | --- | --- | --- |
| `Validation.RuleSetSigningKey` | DPAPI-protected configuration section, decrypted by `IEnvironmentService` | Verifies the signature on rule set XML files so unreviewed rule changes cannot be loaded. | RuleSetLoader | src/SAIF.Framework.Validation/RuleSetLoader.vb |

## 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 |
| --- | --- | --- | --- | --- |
| `Framework.TraceListenerName` | `GetConfigSetting` | SAIF.Framework.Core | NuGet | Selects the trace listener that `ValidationComponentBase.WriteTrace` writes component trace entries to. |
| `Framework.EnvironmentName` | `GetConfigSetting` | SAIF.Framework.Core | NuGet | Identifies the deployment environment used to resolve every other environment-scoped setting. |

## Configuration dependencies

| Dependency | Type | Required at | Impact if missing |
| --- | --- | --- | --- |
| IEnvironmentService | service | Runtime, on first rule set load | `RuleSetLoader.EnsureConfigured` raises `FrameworkNotInitializedException` and no rule set can be evaluated. |
| Rule set XML directory | file | Runtime, on first rule set load | `RuleSetNotFoundException` is raised on the first call to `Validate`; `SAIF.PremiumAudit.Batch` aborts the run rather than processing unvalidated records. |
| Encrypted configuration section | section | Startup | Signature verification cannot run; with `Validation.RequireSignedRuleSets` set to `true`, every rule set load fails. |
| appSettings section | section | Runtime, per evaluation | Code defaults apply: warnings stay advisory, the failure cap stays at 100, and signed rule sets remain required. |

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- src/SAIF.Framework.Validation/RuleSetLoader.vb
- src/SAIF.Framework.Validation/ValidationEngine.vb
- src/SAIF.Framework.Validation/SAIF.Framework.Validation.vbproj
- src/SAIF.Framework.Validation/App.config