Merge branch 'main' into feature/improvements

Combines:
- Early Access to Options (from feature/improvements)
- Direct Type Registration/AlsoRegisterDirectType (from main)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: davidkallesen

CLAUDE.md

@@ -344,6 +344,7 @@ services.AddDependencyRegistrationsFromDomain(
 - **ConfigureAll support**: Set common default values for all named options instances before individual binding with `ConfigureAll` callbacks (e.g., baseline retry/timeout settings)
 - **Named options support**: Multiple configurations of the same options type with different names (e.g., Primary/Secondary email servers)
 - **Child sections**: Simplified syntax for creating multiple named instances from subsections using `ChildSections` property (e.g., `Email` → Primary/Secondary/Fallback)
+- **Direct type registration**: `AlsoRegisterDirectType` parameter allows registering options classes for both `IOptions<T>` AND direct type injection (for migration scenarios and third-party library compatibility)
 - **Nested subsection binding**: Automatic binding of complex properties to configuration subsections (e.g., `StorageOptions.Database.Retry` → `"Storage:Database:Retry"`) - supported out-of-the-box by Microsoft's `.Bind()` method
 - Supports lifetime selection: Singleton (IOptions), Scoped (IOptionsSnapshot), Monitor (IOptionsMonitor)
 - Requires classes to be declared `partial`
@@ -591,6 +592,34 @@ services.Configure<EmailOptions>("Fallback", configuration.GetSection("Email:Fal
 // [OptionsBinding("Email:Primary", Name = "Primary", ConfigureAll = nameof(SetDefaults))]
 // [OptionsBinding("Email:Secondary", Name = "Secondary")]
 // [OptionsBinding("Email:Fallback", Name = "Fallback")]
+
+// Input with AlsoRegisterDirectType (for legacy code or third-party library compatibility):
+[OptionsBinding("LegacyApi", ValidateDataAnnotations = true, AlsoRegisterDirectType = true)]
+public partial class LegacyApiOptions
+{
+    [Required, Url]
+    public string ApiEndpoint { get; set; } = string.Empty;
+
+    [Required, MinLength(32)]
+    public string ApiKey { get; set; } = string.Empty;
+}
+
+// Output with AlsoRegisterDirectType (generates both registrations):
+// Standard IOptions<T> registration
+services.AddOptions<LegacyApiOptions>()
+    .Bind(configuration.GetSection("LegacyApi"))
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+
+// Also register direct type (for legacy code or third-party libraries)
+services.AddSingleton(sp => sp.GetRequiredService<global::Microsoft.Extensions.Options.IOptions<global::MyApp.LegacyApiOptions>>().Value);
+
+// Usage - Both injection patterns now work:
+// Pattern 1: Standard IOptions<T> (recommended for new code)
+public class ApiService(IOptions<LegacyApiOptions> options) { }
+
+// Pattern 2: Direct type (for legacy code or third-party libraries that expect unwrapped types)
+public class LegacyLibraryClient(LegacyApiOptions options) { }
 ```
 
 **Smart Naming:**

docs/OptionsBindingGenerators-FeatureRoadmap.md

@@ -88,10 +88,10 @@ This roadmap is based on comprehensive analysis of:
 | ❌ | [Auto-Generate Options Classes from appsettings.json](#11-auto-generate-options-classes-from-appsettingsjson) | 🟢 Low |
 | ❌ | [Environment-Specific Validation](#12-environment-specific-validation) | 🟢 Low |
 | ❌ | [Hot Reload Support with Filtering](#13-hot-reload-support-with-filtering) | 🟢 Low |
-| 🚫 | [Reflection-Based Binding](#13-reflection-based-binding) | - |
-| 🚫 | [JSON Schema Generation](#14-json-schema-generation) | - |
-| 🚫 | [Configuration Encryption/Decryption](#15-configuration-encryptiondecryption) | - |
-| 🚫 | [Dynamic Configuration Sources](#16-dynamic-configuration-sources) | - |
+| 🚫 | [Reflection-Based Binding](#15-reflection-based-binding) | - |
+| 🚫 | [JSON Schema Generation](#16-json-schema-generation) | - |
+| 🚫 | [Configuration Encryption/Decryption](#17-configuration-encryptiondecryption) | - |
+| 🚫 | [Dynamic Configuration Sources](#18-dynamic-configuration-sources) | - |
 
 **Legend:**
 

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

@@ -0,0 +1,55 @@
+namespace Atc.SourceGenerators.OptionsBinding.Options;
+
+/// <summary>
+/// Legacy integration configuration options.
+/// Demonstrates Feature #13: Direct type registration (AlsoRegisterDirectType).
+/// This feature allows registering the options class both as IOptions&lt;T&gt; AND as the direct type T.
+/// Useful for migration scenarios or third-party library compatibility.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Use case:</b> You're integrating with a legacy library that expects the options class directly
+/// in its constructor, not wrapped in IOptions&lt;T&gt;. Instead of creating a wrapper service,
+/// you can use AlsoRegisterDirectType = true to register both patterns.
+/// </para>
+/// <para>
+/// <b>Trade-offs:</b>
+/// - Direct injection gets a snapshot at resolution time
+/// - No change detection - configuration updates won't be reflected
+/// - Should be used sparingly for migration/compatibility only
+/// </para>
+/// </remarks>
+[OptionsBinding("LegacyIntegration", ValidateDataAnnotations = true, AlsoRegisterDirectType = true)]
+public partial class LegacyIntegrationOptions
+{
+    /// <summary>
+    /// Gets or sets the API endpoint for the legacy system.
+    /// </summary>
+    [Required]
+    [Url]
+    public string ApiEndpoint { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the API key for authentication.
+    /// </summary>
+    [Required]
+    [MinLength(32)]
+    public string ApiKey { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the timeout in seconds for API calls.
+    /// </summary>
+    [Range(1, 300)]
+    public int TimeoutSeconds { get; set; } = 30;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to use SSL/TLS for connections.
+    /// </summary>
+    public bool UseSsl { get; set; } = true;
+
+    /// <summary>
+    /// Gets or sets the maximum number of retry attempts.
+    /// </summary>
+    [Range(0, 10)]
+    public int MaxRetries { get; set; } = 3;
+}

sample/Atc.SourceGenerators.OptionsBinding/appsettings.json

@@ -79,5 +79,13 @@
     "CachePath": "/var/cache/myapp",
     "TempPath": "C:\\Temp\\MyApp",
     "LogPath": "/var/log/myapp"
+  },
+  "LegacyIntegration": {
+    "ApiEndpoint": "https://legacy-api.example.com/v1",
+    "ApiKey": "legacy-api-key-12345678901234567890abcdef",
+    "TimeoutSeconds": 30,
+    "UseSsl": true,
+    "MaxRetries": 3
   }
 }
+

sample/PetStore.Domain/Options/ExternalApiOptions.cs

@@ -2,10 +2,22 @@ namespace PetStore.Domain.Options;
 
 /// <summary>
 /// External API endpoint configuration options.
-/// Demonstrates PostConfigure feature for normalizing API URLs after binding.
+/// Demonstrates:
+/// - PostConfigure feature for normalizing API URLs after binding
+/// - AlsoRegisterDirectType feature for third-party library compatibility
 /// Ensures all URLs are lowercase and properly formatted for consistent API communication.
 /// </summary>
-[OptionsBinding("ExternalApis", ValidateDataAnnotations = true, ValidateOnStart = true, PostConfigure = nameof(NormalizeUrls))]
+/// <remarks>
+/// AlsoRegisterDirectType = true allows this class to be injected both as IOptions&lt;ExternalApiOptions&gt;
+/// and as ExternalApiOptions directly. This is useful when integrating with third-party API client
+/// libraries that expect configuration objects directly in their constructors.
+/// </remarks>
+[OptionsBinding(
+    "ExternalApis",
+    ValidateDataAnnotations = true,
+    ValidateOnStart = true,
+    PostConfigure = nameof(NormalizeUrls),
+    AlsoRegisterDirectType = true)]
 public partial class ExternalApiOptions
 {
     /// <summary>

src/Atc.SourceGenerators.Annotations/OptionsBindingAttribute.cs

@@ -140,4 +140,37 @@ public OptionsBindingAttribute(string? sectionName = null)
     /// Useful for multi-tenant scenarios, regional configurations, or environment-specific settings.
     /// </remarks>
     public string[]? ChildSections { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to also register the options type
+    /// as a direct service (not wrapped in IOptions&lt;T&gt;).
+    /// Default is false.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When true, the options class will be registered both:
+    /// <list type="bullet">
+    /// <item><description>As IOptions&lt;T&gt;, IOptionsSnapshot&lt;T&gt;, or IOptionsMonitor&lt;T&gt; (standard pattern based on Lifetime)</description></item>
+    /// <item><description>As T directly (for legacy code or third-party libraries)</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// The direct type registration resolves through the appropriate options interface (.Value or .CurrentValue)
+    /// to ensure validation and configuration binding still apply.
+    /// </para>
+    /// <para>
+    /// <b>Trade-offs:</b>
+    /// <list type="bullet">
+    /// <item><description><b>Loss of change detection:</b> Direct injection gets a snapshot at resolution time and won't receive updates when configuration changes</description></item>
+    /// <item><description><b>Loss of scoping benefits:</b> Especially when using Monitor lifetime, the direct type is registered as Singleton and uses CurrentValue snapshot</description></item>
+    /// <item><description><b>Migration aid:</b> Useful for gradual migration from direct injection to IOptions&lt;T&gt; pattern</description></item>
+    /// <item><description><b>Third-party compatibility:</b> Some libraries expect direct types, not IOptions&lt;T&gt;</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// <b>Usage guidance:</b> Use sparingly for migration scenarios or third-party library compatibility only.
+    /// The IOptions&lt;T&gt; pattern should be the default choice for new code.
+    /// </para>
+    /// </remarks>
+    public bool AlsoRegisterDirectType { get; set; }
 }

src/Atc.SourceGenerators/Generators/Internal/OptionsInfo.cs

@@ -14,4 +14,5 @@ internal sealed record OptionsInfo(
     string? OnChange,
     string? PostConfigure,
     string? ConfigureAll,
-    string?[]? ChildSections);
+    string?[]? ChildSections,
+    bool AlsoRegisterDirectType);

src/Atc.SourceGenerators/Generators/OptionsBindingGenerator.cs

@@ -413,6 +413,7 @@ private static List<OptionsInfo> ExtractAllOptionsInfo(
         string? postConfigure = null;
         string? configureAll = null;
         string?[]? childSections = null;
+        var alsoRegisterDirectType = false;
 
         foreach (var namedArg in attribute.NamedArguments)
         {
@@ -458,6 +459,9 @@ private static List<OptionsInfo> ExtractAllOptionsInfo(
                                 .ToArray();
                     }
 
+                    break;
+                case "AlsoRegisterDirectType":
+                    alsoRegisterDirectType = namedArg.Value.Value as bool? ?? false;
                     break;
             }
         }
@@ -678,7 +682,8 @@ private static List<OptionsInfo> ExtractAllOptionsInfo(
                     onChange,
                     postConfigure,
                     configureAll,
-                    childSections));  // Store ChildSections to indicate this is part of a child sections group
+                    childSections,  // Store ChildSections to indicate this is part of a child sections group
+                    alsoRegisterDirectType));
             }
 
             return result;
@@ -701,7 +706,8 @@ private static List<OptionsInfo> ExtractAllOptionsInfo(
                 onChange,
                 postConfigure,
                 configureAll,
-                null) // No ChildSections
+                null, // No ChildSections
+                alsoRegisterDirectType)
         ];
     }
 
@@ -1339,6 +1345,32 @@ private static void GenerateOptionsRegistration(
             sb.AppendLineLf(">();");
         }
 
+        // Register direct type if AlsoRegisterDirectType is true
+        if (option.AlsoRegisterDirectType && !isNamed)
+        {
+            sb.AppendLineLf();
+            sb.AppendLineLf($"        // Also register {option.ClassName} as direct type (for legacy code or third-party library compatibility)");
+
+            // Choose service lifetime and options interface based on OptionsLifetime
+            var (serviceMethod, optionsInterface, valueAccess) = option.Lifetime switch
+            {
+                0 => ("AddSingleton", "IOptions", "Value"),                          // Singleton
+                1 => ("AddScoped", "IOptionsSnapshot", "Value"),                     // Scoped
+                2 => ("AddSingleton", "IOptionsMonitor", "CurrentValue"),            // Monitor
+                _ => ("AddSingleton", "IOptions", "Value"),                          // Default
+            };
+
+            sb.Append("        services.");
+            sb.Append(serviceMethod);
+            sb.Append("(sp => sp.GetRequiredService<global::Microsoft.Extensions.Options.");
+            sb.Append(optionsInterface);
+            sb.Append('<');
+            sb.Append(optionsType);
+            sb.Append(">>().");
+            sb.Append(valueAccess);
+            sb.AppendLineLf(");");
+        }
+
         sb.AppendLineLf();
     }
 
@@ -1980,6 +2012,13 @@ public OptionsBindingAttribute(string? sectionName = null)
                    /// Useful for multi-tenant scenarios, regional configurations, or environment-specific settings.
                    /// </remarks>
                    public string[]? ChildSections { get; set; }
+
+                   /// <summary>
+                   /// Gets or sets a value indicating whether to also register the options type
+                   /// as a direct service (not wrapped in IOptions&lt;T&gt;).
+                   /// Default is false.
+                   /// </summary>
+                   public bool AlsoRegisterDirectType { get; set; }
                }
            }
            """;