feat: extend support for Error on Missing Configuration Keys OptionsBinding

Author: davidkallesen

CLAUDE.md

@@ -297,7 +297,7 @@ services.AddDependencyRegistrationsFromDomain(
   3. `public const string NameTitle`
   4. `public const string Name`
   5. Auto-inferred from class name
-- Supports validation: `ValidateDataAnnotations`, `ValidateOnStart`, Custom validators (`IValidateOptions<T>`)
+- Supports validation: `ValidateDataAnnotations`, `ValidateOnStart`, `ErrorOnMissingKeys` (fail-fast for missing sections), Custom validators (`IValidateOptions<T>`)
 - **Named options support**: Multiple configurations of the same options type with different names (e.g., Primary/Secondary email servers)
 - Supports lifetime selection: Singleton (IOptions), Scoped (IOptionsSnapshot), Monitor (IOptionsMonitor)
 - Requires classes to be declared `partial`
@@ -325,6 +325,27 @@ services.AddOptions<DatabaseOptions>()
 
 services.AddSingleton<IValidateOptions<DatabaseOptions>, DatabaseOptionsValidator>();
 
+// Input with ErrorOnMissingKeys (fail-fast for missing configuration):
+[OptionsBinding("Database", ErrorOnMissingKeys = true, ValidateOnStart = true)]
+public partial class DatabaseOptions { }
+
+// Output with ErrorOnMissingKeys:
+services.AddOptions<DatabaseOptions>()
+    .Bind(configuration.GetSection("Database"))
+    .Validate(options =>
+    {
+        var section = configuration.GetSection("Database");
+        if (!section.Exists())
+        {
+            throw new global::System.InvalidOperationException(
+                "Configuration section 'Database' is missing. " +
+                "Ensure the section exists in your appsettings.json or other configuration sources.");
+        }
+
+        return true;
+    })
+    .ValidateOnStart();
+
 // Input with named options (multiple configurations):
 [OptionsBinding("Email:Primary", Name = "Primary")]
 [OptionsBinding("Email:Secondary", Name = "Secondary")]

README.md

@@ -259,7 +259,7 @@ Get errors at compile time, not runtime:
 
 ### ⚙️ OptionsBindingGenerator
 
-Eliminate boilerplate configuration binding code. Decorate your options classes with `[OptionsBinding]` and let the generator create type-safe configuration bindings automatically. Supports DataAnnotations validation, startup validation, and custom `IValidateOptions<T>` validators for complex business rules.
+Eliminate boilerplate configuration binding code. Decorate your options classes with `[OptionsBinding]` and let the generator create type-safe configuration bindings automatically. Supports DataAnnotations validation, startup validation, fail-fast validation for missing configuration sections (`ErrorOnMissingKeys`), and custom `IValidateOptions<T>` validators for complex business rules.
 
 #### 📚 Documentation
 

docs/OptionsBindingGenerators-FeatureRoadmap.md

@@ -56,6 +56,7 @@ This roadmap is based on comprehensive analysis of:
 - **Validation support** - `ValidateDataAnnotations` and `ValidateOnStart` parameters
 - **Custom validation** - `IValidateOptions<T>` for complex business rules beyond DataAnnotations
 - **Named options** - Multiple configurations of the same options type with different names
+- **Error on missing keys** - `ErrorOnMissingKeys` fail-fast validation when configuration sections are missing
 - **Lifetime selection** - Singleton (`IOptions`), Scoped (`IOptionsSnapshot`), Monitor (`IOptionsMonitor`)
 - **Multi-project support** - Assembly-specific extension methods with smart naming
 - **Transitive registration** - 4 overloads for automatic/selective assembly registration
@@ -72,7 +73,7 @@ This roadmap is based on comprehensive analysis of:
 | ✅ | [Custom Validation Support (IValidateOptions)](#1-custom-validation-support-ivalidateoptions) | 🔴 High |
 | ✅ | [Named Options Support](#2-named-options-support) | 🔴 High |
 | ❌ | [Post-Configuration Support](#3-post-configuration-support) | 🟡 Medium-High |
-| ❌ | [Error on Missing Configuration Keys](#4-error-on-missing-configuration-keys) | 🔴 High |
+| ✅ | [Error on Missing Configuration Keys](#4-error-on-missing-configuration-keys) | 🔴 High |
 | ❌ | [Configuration Change Callbacks](#5-configuration-change-callbacks) | 🟡 Medium |
 | ❌ | [Bind Configuration Subsections to Properties](#6-bind-configuration-subsections-to-properties) | 🟡 Medium |
 | ❌ | [ConfigureAll Support](#7-configureall-support) | 🟢 Low-Medium |
@@ -296,10 +297,10 @@ services.AddOptions<StorageOptions>()
 ### 4. Error on Missing Configuration Keys
 
 **Priority**: 🔴 **High** ⭐ *Highly requested in GitHub issues*
-**Status**: ❌ Not Implemented
+**Status**: ✅ **Implemented**
 **Inspiration**: [GitHub Issue #36015](https://github.com/dotnet/runtime/issues/36015)
 
-**Description**: Throw exceptions when required configuration keys are missing instead of silently setting properties to null/default.
+**Description**: Throw exceptions when required configuration sections are missing instead of silently binding to null/default values.
 
 **User Story**:
 > "As a developer, I want my application to fail at startup if critical configuration like database connection strings is missing, rather than failing in production with NullReferenceException."
@@ -310,36 +311,53 @@ services.AddOptions<StorageOptions>()
 [OptionsBinding("Database", ErrorOnMissingKeys = true, ValidateOnStart = true)]
 public partial class DatabaseOptions
 {
-    // If "Database:ConnectionString" is missing in appsettings.json,
-    // throw exception at startup instead of silently setting to null
+    [Required, MinLength(10)]
     public string ConnectionString { get; set; } = string.Empty;
 
-    public int MaxRetries { get; set; } = 5;
+    [Range(1, 10)]
+    public int MaxRetries { get; set; } = 3;
+
+    public int TimeoutSeconds { get; set; } = 30;
 }
 
-// Generated code with error checking:
+// Generated code with section existence check:
 services.AddOptions<DatabaseOptions>()
     .Bind(configuration.GetSection("Database"))
     .Validate(options =>
     {
-        if (string.IsNullOrEmpty(options.ConnectionString))
+        var section = configuration.GetSection("Database");
+        if (!section.Exists())
         {
-            throw new OptionsValidationException(
-                nameof(DatabaseOptions),
-                typeof(DatabaseOptions),
-                new[] { "ConnectionString is required but was not found in configuration" });
+            throw new global::System.InvalidOperationException(
+                "Configuration section 'Database' is missing. " +
+                "Ensure the section exists in your appsettings.json or other configuration sources.");
         }
+
         return true;
     })
+    .ValidateDataAnnotations()
     .ValidateOnStart();
 ```
 
-**Implementation Notes**:
+**Implementation Details**:
+
+- ✅ Added `ErrorOnMissingKeys` boolean parameter to `[OptionsBinding]` attribute
+- ✅ Generator checks `IConfigurationSection.Exists()` to detect missing sections
+- ✅ Throws `InvalidOperationException` with descriptive message including section name
+- ✅ Combines with `ValidateOnStart = true` for startup detection (recommended)
+- ✅ Works with all validation options (DataAnnotations, custom validators)
+- ✅ Section name included in error message for easy troubleshooting
+- ⚠️ Named options do NOT support ErrorOnMissingKeys (named options use simpler Configure pattern)
+
+**Testing**:
+- ✅ 11 comprehensive unit tests covering all scenarios
+- ✅ Sample project updated: DatabaseOptions demonstrates ErrorOnMissingKeys
+- ✅ PetStore.Api sample: PetStoreOptions uses ErrorOnMissingKeys for critical configuration
 
-- Add `ErrorOnMissingKeys` boolean parameter
-- Generate validation delegate that checks for null/default values
-- Combine with `ValidateOnStart = true` for startup failure
-- Consider making this opt-in per-property with attribute: `[Required]` from DataAnnotations
+**Best Practices**:
+- Always combine with `ValidateOnStart = true` to catch missing configuration at startup
+- Use for production-critical configuration (databases, external services, API keys)
+- Avoid for optional configuration with reasonable defaults
 
 ---
 
@@ -766,7 +784,7 @@ Based on priority, user demand, and implementation complexity:
 
 ---
 
-**Last Updated**: 2025-01-17
-**Version**: 1.0
+**Last Updated**: 2025-01-19
+**Version**: 1.1
 **Research Date**: January 2025 (.NET 8/9 Options Pattern)
 **Maintained By**: Atc.SourceGenerators Team

docs/OptionsBindingGenerators-Samples.md

@@ -167,7 +167,8 @@ using System.ComponentModel.DataAnnotations;
 namespace Atc.SourceGenerators.OptionsBinding.Domain;
 
 // Explicit section name (highest priority)
-[OptionsBinding("Database", ValidateDataAnnotations = true, ValidateOnStart = true)]
+// Demonstrates fail-fast validation when configuration section is missing
+[OptionsBinding("Database", ValidateDataAnnotations = true, ValidateOnStart = true, ErrorOnMissingKeys = true)]
 public partial class DatabaseOptions
 {
     [Required]
@@ -595,7 +596,8 @@ public class EmailService
 5. **Multi-Project**: Each project gets its own `AddOptionsFromXXX()` method
 6. **Flexible Lifetimes**: Choose between Singleton, Scoped, or Monitor
 7. **Startup Validation**: Catch configuration errors before runtime
-8. **Named Options**: Multiple configurations of the same type for fallback/multi-tenant scenarios
+8. **Error on Missing Keys**: Fail-fast validation when configuration sections are missing
+9. **Named Options**: Multiple configurations of the same type for fallback/multi-tenant scenarios
 
 ## 🔗 Related Documentation
 

docs/OptionsBindingGenerators.md

@@ -74,6 +74,8 @@ services.AddOptions<DatabaseOptions>()
       - [🏷️ Data Annotations Validation](#️-data-annotations-validation)
       - [🚀 Validate on Startup](#-validate-on-startup)
       - [🔗 Combined Validation](#-combined-validation)
+      - [🎯 Custom Validation (IValidateOptions)](#-custom-validation-ivalidateoptions)
+      - [🚨 Error on Missing Configuration Keys](#-error-on-missing-configuration-keys)
     - [⏱️ Options Lifetimes](#️-options-lifetimes)
   - [🔧 How It Works](#-how-it-works)
     - [1️⃣ Attribute Detection](#1️⃣-attribute-detection)
@@ -741,6 +743,7 @@ Console.WriteLine($"Other interval: {otherOptions.Value.RepeatIntervalInSeconds}
 - **🧠 Automatic section name inference** - Smart resolution from explicit names, const fields (`SectionName`, `NameTitle`, `Name`), or auto-inferred from class names
 - **🔒 Built-in validation** - Integrated DataAnnotations validation (`ValidateDataAnnotations`) and startup validation (`ValidateOnStart`)
 - **🎯 Custom validation** - Support for `IValidateOptions<T>` for complex business rules beyond DataAnnotations
+- **🚨 Error on missing keys** - Fail-fast validation when configuration sections are missing (`ErrorOnMissingKeys`) to catch deployment issues at startup
 - **📛 Named options** - Multiple configurations of the same options type with different names (e.g., Primary/Secondary email servers)
 - **🎯 Explicit section paths** - Support for nested sections like `"App:Database"` or `"Services:Email"`
 - **📦 Multiple options classes** - Register multiple configuration sections in a single assembly with one method call
@@ -1028,6 +1031,75 @@ services.AddSingleton<global::Microsoft.Extensions.Options.IValidateOptions<glob
 - Can validate cross-property dependencies
 - Returns detailed failure messages
 
+#### 🚨 Error on Missing Configuration Keys
+
+The `ErrorOnMissingKeys` feature provides fail-fast validation when configuration sections are missing, preventing runtime errors from invalid or missing configuration.
+
+**When to use:**
+- Critical configuration that must be present (database connections, API keys, etc.)
+- Detect configuration issues at application startup instead of later at runtime
+- Ensure deployment validation catches missing configuration files or sections
+
+**Example:**
+
+```csharp
+using System.ComponentModel.DataAnnotations;
+
+[OptionsBinding("Database",
+    ValidateDataAnnotations = true,
+    ValidateOnStart = true,
+    ErrorOnMissingKeys = true)]
+public partial class DatabaseOptions
+{
+    [Required, MinLength(10)]
+    public string ConnectionString { get; set; } = string.Empty;
+
+    [Range(1, 10)]
+    public int MaxRetries { get; set; } = 3;
+
+    public int TimeoutSeconds { get; set; } = 30;
+}
+```
+
+**Generated Code:**
+
+```csharp
+services.AddOptions<global::MyApp.Options.DatabaseOptions>()
+    .Bind(configuration.GetSection("Database"))
+    .Validate(options =>
+    {
+        var section = configuration.GetSection("Database");
+        if (!section.Exists())
+        {
+            throw new global::System.InvalidOperationException(
+                "Configuration section 'Database' is missing. " +
+                "Ensure the section exists in your appsettings.json or other configuration sources.");
+        }
+
+        return true;
+    })
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+**Behavior:**
+- Validates that the configuration section exists using `IConfigurationSection.Exists()`
+- Throws `InvalidOperationException` with descriptive message if section is missing
+- Combines with `ValidateOnStart = true` to fail at startup (recommended)
+- Error message includes the section name for easy troubleshooting
+
+**Best Practices:**
+- Always combine with `ValidateOnStart = true` to catch missing configuration at startup
+- Use for production-critical configuration (databases, external services, etc.)
+- Avoid for optional configuration with reasonable defaults
+- Ensure deployment processes validate configuration files exist
+
+**Example Error Message:**
+```
+System.InvalidOperationException: Configuration section 'Database' is missing.
+Ensure the section exists in your appsettings.json or other configuration sources.
+```
+
 ### ⏱️ Options Lifetimes
 
 Control which options interface consumers should inject. **All three interfaces are always available**, but the `Lifetime` property indicates the recommended interface for your use case:

sample/Atc.SourceGenerators.OptionsBinding/Options/DatabaseOptions.cs

@@ -3,8 +3,9 @@ namespace Atc.SourceGenerators.OptionsBinding.Options;
 /// <summary>
 /// Database configuration options with validation.
 /// Explicitly binds to "Database" section in appsettings.json.
+/// Demonstrates ErrorOnMissingKeys to fail fast if configuration is missing.
 /// </summary>
-[OptionsBinding("Database", ValidateDataAnnotations = true, ValidateOnStart = true, Validator = typeof(Validators.DatabaseOptionsValidator))]
+[OptionsBinding("Database", ValidateDataAnnotations = true, ValidateOnStart = true, ErrorOnMissingKeys = true, Validator = typeof(Validators.DatabaseOptionsValidator))]
 public partial class DatabaseOptions
 {
     [Required]

sample/Atc.SourceGenerators.OptionsBinding/Options/EmailOptions.cs

@@ -34,4 +34,4 @@ public partial class EmailOptions
     /// Gets or sets the timeout in seconds.
     /// </summary>
     public int TimeoutSeconds { get; set; } = 30;
-}
+}

sample/Atc.SourceGenerators.OptionsBinding/Options/Validators/DatabaseOptionsValidator.cs

@@ -6,7 +6,9 @@ namespace Atc.SourceGenerators.OptionsBinding.Options.Validators;
 /// </summary>
 public class DatabaseOptionsValidator : IValidateOptions<DatabaseOptions>
 {
-    public ValidateOptionsResult Validate(string? name, DatabaseOptions options)
+    public ValidateOptionsResult Validate(
+        string? name,
+        DatabaseOptions options)
     {
         var failures = new List<string>();
 
@@ -20,7 +22,8 @@ public ValidateOptionsResult Validate(string? name, DatabaseOptions options)
         if (!string.IsNullOrWhiteSpace(options.ConnectionString))
         {
             var connStr = options.ConnectionString.ToLowerInvariant();
-            if (!connStr.Contains("server=") && !connStr.Contains("data source="))
+            if (!connStr.Contains("server=", StringComparison.Ordinal) &&
+                !connStr.Contains("data source=", StringComparison.Ordinal))
             {
                 failures.Add("ConnectionString must contain 'Server=' or 'Data Source=' parameter");
             }
@@ -30,4 +33,4 @@ public ValidateOptionsResult Validate(string? name, DatabaseOptions options)
             ? ValidateOptionsResult.Fail(failures)
             : ValidateOptionsResult.Success;
     }
-}
+}

sample/Atc.SourceGenerators.OptionsBinding/Program.cs

@@ -19,7 +19,7 @@
 
 Console.WriteLine("1. Testing DatabaseOptions (with validation):");
 Console.WriteLine("   - Section: \"Database\"");
-Console.WriteLine("   - Validation: DataAnnotations + ValidateOnStart");
+Console.WriteLine("   - Validation: DataAnnotations + ValidateOnStart + ErrorOnMissingKeys");
 
 try
 {

sample/PetStore.Domain/Options/PetStoreOptions.cs

@@ -2,8 +2,9 @@ namespace PetStore.Domain.Options;
 
 /// <summary>
 /// Configuration options for the pet store.
+/// Demonstrates ErrorOnMissingKeys for critical configuration that must be present.
 /// </summary>
-[OptionsBinding("PetStore", ValidateDataAnnotations = true, ValidateOnStart = true, Validator = typeof(Validators.PetStoreOptionsValidator))]
+[OptionsBinding("PetStore", ValidateDataAnnotations = true, ValidateOnStart = true, ErrorOnMissingKeys = true, Validator = typeof(Validators.PetStoreOptionsValidator))]
 public partial class PetStoreOptions
 {
     /// <summary>