feat: extend support for Named-Options OptionsBinding

Author: davidkallesen

CLAUDE.md

@@ -298,6 +298,7 @@ services.AddDependencyRegistrationsFromDomain(
   4. `public const string Name`
   5. Auto-inferred from class name
 - Supports validation: `ValidateDataAnnotations`, `ValidateOnStart`, 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`
 - **Smart naming** - uses short suffix if unique, full name if conflicts exist
@@ -323,6 +324,22 @@ services.AddOptions<DatabaseOptions>()
     .ValidateOnStart();
 
 services.AddSingleton<IValidateOptions<DatabaseOptions>, DatabaseOptionsValidator>();
+
+// Input with named options (multiple configurations):
+[OptionsBinding("Email:Primary", Name = "Primary")]
+[OptionsBinding("Email:Secondary", Name = "Secondary")]
+[OptionsBinding("Email:Fallback", Name = "Fallback")]
+public partial class EmailOptions { }
+
+// Output with named options:
+services.Configure<EmailOptions>("Primary", configuration.GetSection("Email:Primary"));
+services.Configure<EmailOptions>("Secondary", configuration.GetSection("Email:Secondary"));
+services.Configure<EmailOptions>("Fallback", configuration.GetSection("Email:Fallback"));
+
+// Usage: Access via IOptionsSnapshot<T>.Get(name)
+var emailSnapshot = serviceProvider.GetRequiredService<IOptionsSnapshot<EmailOptions>>();
+var primaryEmail = emailSnapshot.Get("Primary");
+var secondaryEmail = emailSnapshot.Get("Secondary");
 ```
 
 **Smart Naming:**

README.md

@@ -318,6 +318,8 @@ services.AddOptionsFromApp(configuration);
 
 - **🧠 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
+- **📛 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
 - **🏗️ Multi-Project Support**: Smart naming generates assembly-specific extension methods (e.g., `AddOptionsFromDomain()`, `AddOptionsFromDataAccess()`)

docs/OptionsBindingGenerators-FeatureRoadmap.md

@@ -54,6 +54,8 @@ This roadmap is based on comprehensive analysis of:
 
 - **Section name resolution** - 5-level priority system (explicit → const SectionName → const NameTitle → const Name → auto-inferred)
 - **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
 - **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
@@ -68,7 +70,7 @@ This roadmap is based on comprehensive analysis of:
 | Status | Feature | Priority |
 |:------:|---------|----------|
 | ✅ | [Custom Validation Support (IValidateOptions)](#1-custom-validation-support-ivalidateoptions) | 🔴 High |
-| ❌ | [Named Options Support](#2-named-options-support) | 🔴 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 |
 | ❌ | [Configuration Change Callbacks](#5-configuration-change-callbacks) | 🟡 Medium |
@@ -165,7 +167,7 @@ services.AddOptions<ConnectionPoolOptions>()
 ### 2. Named Options Support
 
 **Priority**: 🔴 **High**
-**Status**: ❌ Not Implemented
+**Status**: ✅ **Implemented**
 **Inspiration**: Microsoft.Extensions.Options named options
 
 **Description**: Support multiple configuration sections binding to the same options class with different names.
@@ -224,12 +226,19 @@ public class DataService
 }
 ```
 
-**Implementation Notes**:
+**Implementation Details**:
+
+- ✅ `[OptionsBinding]` attribute supports `AllowMultiple = true`
+- ✅ Added `Name` property to distinguish named instances
+- ✅ Named options use `Configure<T>(name, section)` pattern
+- ✅ Named options accessed via `IOptionsSnapshot<T>.Get(name)`
+- ✅ Can mix named and unnamed options on the same class
+- ⚠️ Named options do NOT support validation chain (ValidateDataAnnotations, ValidateOnStart, Validator)
 
-- Allow multiple `[OptionsBinding]` attributes on same class
-- Add `Name` parameter to distinguish named instances
-- Use `Configure<T>(string name, ...)` for named options
-- Generate helper properties/methods for easy access
+**Testing**:
+- ✅ 8 comprehensive unit tests covering all scenarios
+- ✅ Sample project with EmailOptions demonstrating Primary/Secondary/Fallback servers
+- ✅ PetStore.Api sample with NotificationOptions (Email/SMS/Push channels)
 
 ---
 

docs/OptionsBindingGenerators-Samples.md

@@ -447,6 +447,145 @@ public partial class LoggingOptions { }
 // Inject: IOptionsMonitor<LoggingOptions>
 ```
 
+## 📛 Named Options Support
+
+**Named Options** allow multiple configurations of the same options type with different names - perfect for fallback scenarios, multi-tenant applications, or multi-region deployments.
+
+### 🎯 Example: Email Server Fallback
+
+**Options Class:**
+
+```csharp
+using Atc.SourceGenerators.Annotations;
+
+namespace Atc.SourceGenerators.OptionsBinding.Options;
+
+[OptionsBinding("Email:Primary", Name = "Primary")]
+[OptionsBinding("Email:Secondary", Name = "Secondary")]
+[OptionsBinding("Email:Fallback", Name = "Fallback")]
+public partial class EmailOptions
+{
+    public string SmtpServer { get; set; } = string.Empty;
+    public int Port { get; set; } = 587;
+    public bool UseSsl { get; set; } = true;
+    public string FromAddress { get; set; } = string.Empty;
+    public int TimeoutSeconds { get; set; } = 30;
+}
+```
+
+**Configuration (appsettings.json):**
+
+```json
+{
+  "Email": {
+    "Primary": {
+      "SmtpServer": "smtp.primary.example.com",
+      "Port": 587,
+      "UseSsl": true,
+      "FromAddress": "noreply@primary.example.com",
+      "TimeoutSeconds": 30
+    },
+    "Secondary": {
+      "SmtpServer": "smtp.secondary.example.com",
+      "Port": 587,
+      "UseSsl": true,
+      "FromAddress": "noreply@secondary.example.com",
+      "TimeoutSeconds": 45
+    },
+    "Fallback": {
+      "SmtpServer": "smtp.fallback.example.com",
+      "Port": 25,
+      "UseSsl": false,
+      "FromAddress": "noreply@fallback.example.com",
+      "TimeoutSeconds": 60
+    }
+  }
+}
+```
+
+**Generated Code:**
+
+```csharp
+// <auto-generated />
+namespace Atc.SourceGenerators.Annotations;
+
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddOptionsFromOptionsBinding(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        // Configure EmailOptions (Named: "Primary")
+        services.Configure<EmailOptions>("Primary", configuration.GetSection("Email:Primary"));
+
+        // Configure EmailOptions (Named: "Secondary")
+        services.Configure<EmailOptions>("Secondary", configuration.GetSection("Email:Secondary"));
+
+        // Configure EmailOptions (Named: "Fallback")
+        services.Configure<EmailOptions>("Fallback", configuration.GetSection("Email:Fallback"));
+
+        return services;
+    }
+}
+```
+
+**Usage in Services:**
+
+```csharp
+public class EmailService
+{
+    private readonly IOptionsSnapshot<EmailOptions> _emailSnapshot;
+
+    public EmailService(IOptionsSnapshot<EmailOptions> emailSnapshot)
+    {
+        _emailSnapshot = emailSnapshot;
+    }
+
+    public async Task SendAsync(string to, string body)
+    {
+        // Try primary first
+        var primaryEmail = _emailSnapshot.Get("Primary");
+        if (await TrySendAsync(primaryEmail, to, body))
+            return;
+
+        // Fallback to secondary
+        var secondaryEmail = _emailSnapshot.Get("Secondary");
+        if (await TrySendAsync(secondaryEmail, to, body))
+            return;
+
+        // Last resort: fallback server
+        var fallbackEmail = _emailSnapshot.Get("Fallback");
+        await TrySendAsync(fallbackEmail, to, body);
+    }
+
+    private async Task<bool> TrySendAsync(EmailOptions options, string to, string body)
+    {
+        try
+        {
+            // Send email using options.SmtpServer, options.Port, etc.
+            return true;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+}
+```
+
+### ⚠️ Important Notes
+
+- **Use `IOptionsSnapshot<T>`**: Named options are accessed via `IOptionsSnapshot<T>.Get(name)`, not `IOptions<T>.Value`
+- **No Validation Chain**: Named options use the simpler `Configure<T>(name, section)` pattern without validation support
+- **AllowMultiple**: The `[OptionsBinding]` attribute supports multiple instances on the same class
+
+### 🎯 Common Use Cases
+
+- **Fallback Servers**: Primary/Secondary/Fallback email or database servers
+- **Multi-Region**: Different API endpoints for US, EU, Asia regions
+- **Multi-Tenant**: Tenant-specific configurations
+- **Environment Tiers**: Production, Staging, Development endpoints
+
 ## ✨ Key Takeaways
 
 1. **Zero Boilerplate**: No manual `AddOptions().Bind()` code to write
@@ -456,6 +595,7 @@ public partial class LoggingOptions { }
 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
 
 ## 🔗 Related Documentation
 

docs/OptionsBindingGenerators.md

@@ -741,6 +741,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
+- **📛 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
 - **🏗️ Multi-project support** - Smart naming generates assembly-specific extension methods (e.g., `AddOptionsFromDomain()`, `AddOptionsFromDataAccess()`)
@@ -1270,6 +1271,133 @@ var configuration = new ConfigurationBuilder()
 services.AddOptionsFromApp(configuration);
 ```
 
+### 📛 Named Options (Multiple Configurations)
+
+**Named Options** allow you to have multiple configurations of the same options type with different names. This is useful when you need different configurations for the same logical service (e.g., Primary/Secondary email servers, Production/Staging databases).
+
+#### ✨ Use Cases
+
+- **🔄 Fallback Servers**: Primary, Secondary, and Fallback email/database servers
+- **🌍 Multi-Region**: Different API endpoints for different regions (US, EU, Asia)
+- **🎯 Multi-Tenant**: Tenant-specific configurations
+- **🔧 Environment Tiers**: Production, Staging, Development endpoints
+
+#### 🎯 Basic Example
+
+**Define options with multiple named instances:**
+
+```csharp
+[OptionsBinding("Email:Primary", Name = "Primary")]
+[OptionsBinding("Email:Secondary", Name = "Secondary")]
+[OptionsBinding("Email:Fallback", Name = "Fallback")]
+public partial class EmailOptions
+{
+    public string SmtpServer { get; set; } = string.Empty;
+    public int Port { get; set; } = 587;
+    public bool UseSsl { get; set; } = true;
+    public string FromAddress { get; set; } = string.Empty;
+}
+```
+
+**Configure appsettings.json:**
+
+```json
+{
+  "Email": {
+    "Primary": {
+      "SmtpServer": "smtp.primary.example.com",
+      "Port": 587,
+      "UseSsl": true,
+      "FromAddress": "noreply@primary.example.com"
+    },
+    "Secondary": {
+      "SmtpServer": "smtp.secondary.example.com",
+      "Port": 587,
+      "UseSsl": true,
+      "FromAddress": "noreply@secondary.example.com"
+    },
+    "Fallback": {
+      "SmtpServer": "smtp.fallback.example.com",
+      "Port": 25,
+      "UseSsl": false,
+      "FromAddress": "noreply@fallback.example.com"
+    }
+  }
+}
+```
+
+**Access named options using IOptionsSnapshot:**
+
+```csharp
+public class EmailService
+{
+    private readonly IOptionsSnapshot<EmailOptions> _emailOptionsSnapshot;
+
+    public EmailService(IOptionsSnapshot<EmailOptions> emailOptionsSnapshot)
+    {
+        _emailOptionsSnapshot = emailOptionsSnapshot;
+    }
+
+    public async Task SendAsync(string to, string body)
+    {
+        // Try primary first
+        var primaryOptions = _emailOptionsSnapshot.Get("Primary");
+        if (await TrySendAsync(primaryOptions, to, body))
+            return;
+
+        // Fallback to secondary
+        var secondaryOptions = _emailOptionsSnapshot.Get("Secondary");
+        if (await TrySendAsync(secondaryOptions, to, body))
+            return;
+
+        // Last resort: fallback server
+        var fallbackOptions = _emailOptionsSnapshot.Get("Fallback");
+        await TrySendAsync(fallbackOptions, to, body);
+    }
+}
+```
+
+#### 🔧 Generated Code
+
+```csharp
+// Generated registration methods
+services.Configure<EmailOptions>("Primary", configuration.GetSection("Email:Primary"));
+services.Configure<EmailOptions>("Secondary", configuration.GetSection("Email:Secondary"));
+services.Configure<EmailOptions>("Fallback", configuration.GetSection("Email:Fallback"));
+```
+
+#### ⚠️ Important Notes
+
+- **📝 Use `IOptionsSnapshot<T>`**: Named options are accessed via `IOptionsSnapshot<T>.Get(name)`, not `IOptions<T>.Value`
+- **🚫 No Validation Chain**: Named options use the simpler `Configure<T>(name, section)` pattern without validation support
+- **🔄 AllowMultiple**: The `[OptionsBinding]` attribute supports `AllowMultiple = true` to enable multiple configurations
+
+#### 🎯 Mixing Named and Unnamed Options
+
+You can have both named and unnamed options on the same class:
+
+```csharp
+// Default unnamed instance
+[OptionsBinding("Email")]
+
+// Named instances for specific use cases
+[OptionsBinding("Email:Backup", Name = "Backup")]
+public partial class EmailOptions
+{
+    public string SmtpServer { get; set; } = string.Empty;
+    public int Port { get; set; } = 587;
+}
+```
+
+```csharp
+// Access default (unnamed) instance
+var defaultEmail = serviceProvider.GetRequiredService<IOptions<EmailOptions>>();
+
+// Access named instances
+var emailSnapshot = serviceProvider.GetRequiredService<IOptionsSnapshot<EmailOptions>>();
+var backupEmail = emailSnapshot.Get("Backup");
+```
+
 ---
 
 ## 🛡️ Diagnostics

docs/PetStoreApi-Samples.md

@@ -106,7 +106,7 @@ graph TB
 
 ### Project References (Clean Architecture)
 
-```
+```text
 PetStore.Api
 ├── PetStore.Domain
 │   ├── PetStore.DataAccess (NO Api.Contract reference)