diff --git a/CLAUDE.md b/CLAUDE.md index 0094996..05d153d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,6 +87,42 @@ dotnet run --project sample/PetStore.Api dotnet clean ``` +## Build Requirements + +### SDK Version + +This project uses **Roslyn 5.0.0 (.NET 10)** source generators and requires .NET 10 SDK for building. + +**Consumer Projects:** +- Projects that reference `Atc.SourceGenerators` must be built with .NET 10 SDK (or later) +- Consumer projects can target ANY .NET version (.NET 9, .NET 8, .NET Framework, etc.) +- This is a build-time requirement only - runtime target framework is independent + +**Why .NET 10 SDK is required:** +- Roslyn 5.0.0 APIs ship with .NET 10 SDK +- Source generators execute during compilation, requiring the SDK's Roslyn version +- Target framework and SDK version are independent concepts in .NET + +**Example Scenario:** +```xml + + + + net9.0 + + + + + + + +``` + +```bash +# Must use .NET 10 SDK to build +dotnet build # Executes source generators using Roslyn 5.0.0 +``` + ## Architecture ### Source Generator Lifecycle @@ -314,6 +350,74 @@ services.AddDependencyRegistrationsFromDomain( - Requires classes to be declared `partial` - **Smart naming** - uses short suffix if unique, full name if conflicts exist - **Transitive registration**: Generates 4 overloads for each assembly to support automatic or selective registration of referenced assemblies +- **Early access to options**: Avoid BuildServiceProvider anti-pattern with GetOrAdd methods for accessing options during service registration + +**Early Access to Options (Avoids BuildServiceProvider Anti-Pattern):** + +Three APIs available for accessing options during service registration: + +| Method | Reads Cache | Writes Cache | Use Case | +|--------|-------------|--------------|----------| +| `Get[Type]...` | ✅ Yes | ❌ No | Efficient retrieval (uses cached if available, no side effects) | +| `GetOrAdd[Type]...` | ✅ Yes | ✅ Yes | Early access with caching for idempotency | +| `GetOptions()` | ✅ Yes | ❌ No | Smart dispatcher (calls `Get[Type]...` internally) | + +```csharp +// Problem: Need options values during service registration but don't want BuildServiceProvider() +// Solution: Three APIs available for early access + +// API 1: Get methods - Efficient retrieval (reads cache, doesn't populate) +var dbOptions1 = services.GetDatabaseOptionsFromDomain(configuration); +var dbOptions2 = services.GetDatabaseOptionsFromDomain(configuration); +// If GetOrAdd was never called: dbOptions1 != dbOptions2 (different instances) +// If GetOrAdd was called first: dbOptions1 == dbOptions2 (returns cached instance) + +// API 2: GetOrAdd methods - With caching (idempotent, populates cache) +var dbCached1 = services.GetOrAddDatabaseOptionsFromDomain(configuration); +var dbCached2 = services.GetOrAddDatabaseOptionsFromDomain(configuration); +// dbCached1 == dbCached2 (same instance, cached for reuse) + +// API 3: Generic smart dispatcher (calls Get internally - reads cache, doesn't populate) +var dbOptions3 = services.GetOptions(configuration); +// Internally calls GetDatabaseOptionsFromDomain() - benefits from cache if available +// Works in multi-assembly projects - no CS0121 ambiguity! + +// Example: Call GetOrAdd first, then Get benefits from cache +var dbFromAdd = services.GetOrAddDatabaseOptionsFromDomain(configuration); // Populates cache +var dbFromGet = services.GetDatabaseOptionsFromDomain(configuration); // Uses cache +// dbFromAdd == dbFromGet (true - Get found it in cache) + +// Use options to make conditional registration decisions +if (dbFromAdd.EnableFeatureX) +{ + services.AddScoped(); +} + +// Normal AddOptionsFrom* methods register with service collection +services.AddOptionsFromDomain(configuration); +// Options available via IOptions, IOptionsSnapshot, IOptionsMonitor +``` + +**How the Smart Dispatcher Works:** +- **Library assemblies** (no OptionsBinding references): Don't generate `GetOptions()` - use assembly-specific methods +- **Consuming assemblies** (with OptionsBinding references): Generate smart dispatcher that routes based on type: + ```csharp + public static T GetOptions(...) + { + var type = typeof(T); + + // Current assembly options + if (type == typeof(DatabaseOptions)) + return (T)(object)services.GetDatabaseOptionsFromOptionsBinding(configuration); + + // Referenced assembly options + if (type == typeof(CacheOptions)) + return (T)(object)services.GetCacheOptionsFromDomain(configuration); + + throw new InvalidOperationException($"Type '{type.FullName}' is not registered..."); + } + ``` +- **Result**: No CS0121 ambiguity, convenient generic API, compile-time type safety, no caching side effects! **Generated Code Pattern:** ```csharp diff --git a/README.md b/README.md index 2550d58..d80bff1 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,38 @@ Or in your `.csproj`: **Note:** The generator emits fallback attributes automatically, so the Annotations package is optional. However, it provides better XML documentation and IntelliSense. If you include it, suppress the expected CS0436 warning: `$(NoWarn);CS0436` +## ⚙️ Requirements + +### Build-Time Requirements + +This package uses **Roslyn 5.0.0 (.NET 10)** for source generation. To build projects that consume this package: + +**Required:** +- **.NET 10 SDK** (or later) + +**Important Notes:** +- Projects targeting **.NET 9 (or earlier)** CAN successfully build using the .NET 10 SDK +- This is a **build-time requirement only**, not a runtime requirement +- Your application can still target and run on .NET 9, .NET 8, or earlier framework versions +- The SDK version only affects the build process, not the target framework or runtime + +**Example:** + +```bash +# Install .NET 10 SDK +# Download from: https://dotnet.microsoft.com/download/dotnet/10.0 + +# Your project can still target .NET 9 +net9.0 + +# But requires .NET 10 SDK to build (due to Roslyn 5.0.0 source generator dependency) +dotnet build # Must use .NET 10 SDK +``` + +**Why .NET 10 SDK?** + +The source generators in this package leverage Roslyn 5.0.0 APIs which ship with .NET 10. While your consuming applications can target any .NET version (including .NET 9, .NET 8, or .NET Framework), the build toolchain requires .NET 10 SDK for proper source generator execution. + --- ### ⚡ DependencyRegistrationGenerator @@ -322,6 +354,7 @@ services.AddOptionsFromApp(configuration); - **🔔 Configuration Change Callbacks**: Auto-generated IHostedService for OnChange notifications with Monitor lifetime - perfect for feature flags and runtime config updates - **🔧 Post-Configuration Support**: Normalize or transform values after binding with `PostConfigure` callbacks (e.g., ensure paths have trailing slashes, lowercase URLs) - **📛 Named Options**: Multiple configurations of the same options type with different names (e.g., Primary/Secondary email servers) +- **⚡ Early Access to Options**: Retrieve bound and validated options during service registration without BuildServiceProvider() anti-pattern (via `GetOrAdd*` methods) - **🎯 Explicit Section Paths**: Support for nested sections like `"App:Database"` or `"Services:Email"` - **📂 Nested Subsection Binding**: Automatic binding of complex properties to configuration subsections (e.g., `StorageOptions.Database.Retry` → `"Storage:Database:Retry"`) - **📦 Multiple Options Classes**: Register multiple configuration sections in a single assembly with one method call diff --git a/docs/OptionsBindingGenerators-FeatureRoadmap.md b/docs/OptionsBindingGenerators-FeatureRoadmap.md index a091e98..9117fa6 100644 --- a/docs/OptionsBindingGenerators-FeatureRoadmap.md +++ b/docs/OptionsBindingGenerators-FeatureRoadmap.md @@ -84,14 +84,14 @@ This roadmap is based on comprehensive analysis of: | ✅ | [ConfigureAll Support](#7-configureall-support) | 🟢 Low-Medium | | ✅ | [Child Sections (Simplified Named Options)](#8-child-sections-simplified-named-options) | 🟢 Low-Medium | | ❌ | [Compile-Time Section Name Validation](#9-compile-time-section-name-validation) | 🟡 Medium | -| ❌ | [Auto-Generate Options Classes from appsettings.json](#10-auto-generate-options-classes-from-appsettingsjson) | 🟢 Low | -| ❌ | [Environment-Specific Validation](#11-environment-specific-validation) | 🟢 Low | -| ❌ | [Hot Reload Support with Filtering](#12-hot-reload-support-with-filtering) | 🟢 Low | -| ✅ | [Direct Type Registration (AlsoRegisterDirectType)](#13-direct-type-registration-alsoregisterdirecttype) | 🟡 Medium | -| 🚫 | [Reflection-Based Binding](#14-reflection-based-binding) | - | -| 🚫 | [JSON Schema Generation](#15-json-schema-generation) | - | -| 🚫 | [Configuration Encryption/Decryption](#16-configuration-encryptiondecryption) | - | -| 🚫 | [Dynamic Configuration Sources](#17-dynamic-configuration-sources) | - | +| ✅ | [Early Access to Options During Service Registration](#10-early-access-to-options-during-service-registration) | 🔴 High | +| ❌ | [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](#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:** @@ -860,469 +860,652 @@ public partial class NotificationOptions --- -### 10. Auto-Generate Options Classes from appsettings.json +### 10. Early Access to Options During Service Registration -**Priority**: 🟢 **Low** -**Status**: ❌ Not Implemented +**Priority**: 🔴 **High** ⭐ *Avoids BuildServiceProvider anti-pattern* +**Status**: ✅ **Implemented** +**Inspiration**: [StackOverflow: Avoid BuildServiceProvider](https://stackoverflow.com/questions/66263977/how-to-avoid-using-using-buildserviceprovider-method-at-multiple-places) -**Description**: Reverse the process - analyze appsettings.json and generate strongly-typed options classes. +> **📝 Implementation Note:** This feature is fully implemented with three APIs: +> 1. `Get[Type]From[Assembly]()` - Reads cache, doesn't populate (efficient, no side effects) +> 2. `GetOrAdd[Type]From[Assembly]()` - Reads AND populates cache (idempotent) +> 3. `GetOptions()` - Smart dispatcher for multi-assembly projects (calls Get internally) +> +> See [OptionsBindingGenerators.md](OptionsBindingGenerators.md#-early-access-to-options-avoid-buildserviceprovider-anti-pattern) for current usage. -**Example**: +**Description**: Enable access to bound and validated options instances **during** service registration without calling `BuildServiceProvider()`, which is a known anti-pattern that causes memory leaks, scope issues, and application instability. -```json -{ - "Database": { - "ConnectionString": "...", - "MaxRetries": 5 - } -} -``` +**User Story**: +> "As a developer, I need to access configuration values (like connection strings, API keys, or feature flags) during service registration to conditionally register services or configure dependencies, WITHOUT calling `BuildServiceProvider()` multiple times." -Generates: +**The Anti-Pattern Problem**: ```csharp -// Auto-generated -public partial class DatabaseOptions -{ - public string ConnectionString { get; set; } = string.Empty; - public int MaxRetries { get; set; } -} -``` +// ❌ ANTI-PATTERN - Multiple BuildServiceProvider calls +var services = new ServiceCollection(); +services.AddOptionsFromApp(configuration); -**Considerations**: +// Need database connection string to configure DbContext +var tempProvider = services.BuildServiceProvider(); // ⚠️ First build +var dbOptions = tempProvider.GetRequiredService>().Value; -- Requires JSON schema inference -- Type ambiguity (is "5" an int or string?) -- May conflict with user-defined classes -- Interesting but low priority +services.AddDbContext(options => + options.UseSqlServer(dbOptions.ConnectionString)); ---- +// Need API key for HttpClient +var apiOptions = tempProvider.GetRequiredService>().Value; +services.AddHttpClient("External", client => + client.DefaultRequestHeaders.Add("X-API-Key", apiOptions.ApiKey)); -### 11. Environment-Specific Validation +// Finally build the real provider +var provider = services.BuildServiceProvider(); // ⚠️ Second build +var app = host.Build(); +``` -**Priority**: 🟢 **Low** -**Status**: ❌ Not Implemented +**Why This is Bad**: -**Description**: Apply different validation rules based on environment (e.g., stricter in production). +1. **Memory Leaks**: First `ServiceProvider` is never disposed properly +2. **Incomplete Services**: Services registered after first build aren't in first provider +3. **Scope/Lifetime Issues**: Transient services may be captured as singletons +4. **Production Failures**: Subtle bugs that only manifest under load +5. **Microsoft's Warning**: Official docs explicitly warn against this pattern -**Example**: +**Proposed Solution - Individual Accessor Methods**: + +Generate per-options extension methods that return bound instances for early access: ```csharp -[OptionsBinding("Features", ValidateOnStart = true)] -public partial class FeaturesOptions -{ - public bool EnableDebugMode { get; set; } +// ✅ SOLUTION - Early access WITHOUT BuildServiceProvider +var services = new ServiceCollection(); - // Only validate in production - [RequiredInProduction] - public string LicenseKey { get; set; } = string.Empty; -} -``` +// Get options instances during registration (no BuildServiceProvider!) +var dbOptions = services.GetOrAddDatabaseOptions(configuration); +var apiOptions = services.GetOrAddApiOptions(configuration); ---- +// Use options immediately for service configuration +services.AddDbContext(options => + options.UseSqlServer(dbOptions.ConnectionString)); -### 12. Hot Reload Support with Filtering +services.AddHttpClient("External", client => + client.DefaultRequestHeaders.Add("X-API-Key", apiOptions.ApiKey)); -**Priority**: 🟢 **Low** -**Status**: ❌ Not Implemented +// Still call the bulk method for completeness (idempotent - won't duplicate) +services.AddOptionsFromApp(configuration); -**Description**: Fine-grained control over which configuration changes trigger reloads. +// Build provider ONCE at the end +var provider = services.BuildServiceProvider(); // ✅ Only one build! +``` -**Example**: +**Generated Code Pattern**: + +For each options class, generate an individual accessor method: ```csharp -[OptionsBinding("Features", Lifetime = OptionsLifetime.Monitor, ReloadOn = new[] { "EnableNewUI", "MaxUploadSizeMB" })] -public partial class FeaturesOptions +/// +/// Gets or adds DatabaseOptions to the service collection with configuration binding. +/// If already registered, returns the existing instance. Otherwise, creates, binds, validates, and registers the instance. +/// This method is idempotent and safe to call multiple times. +/// +/// The service collection. +/// The configuration. +/// The bound and validated DatabaseOptions instance for immediate use during service registration. +public static DatabaseOptions GetOrAddDatabaseOptions( + this IServiceCollection services, + IConfiguration configuration) { - public bool EnableNewUI { get; set; } // Triggers reload - public int MaxUploadSizeMB { get; set; } // Triggers reload - public string UITheme { get; set; } = "Light"; // Doesn't trigger reload -} -``` + // Check if already registered (idempotent) + var existingDescriptor = services.FirstOrDefault(d => + d.ServiceType == typeof(DatabaseOptions) && + d.ImplementationInstance != null); ---- + if (existingDescriptor != null) + { + return (DatabaseOptions)existingDescriptor.ImplementationInstance!; + } -### 13. Direct Type Registration (AlsoRegisterDirectType) + // Create and bind instance + var options = new DatabaseOptions(); + var section = configuration.GetSection("DatabaseOptions"); + section.Bind(options); -**Priority**: 🟡 **Medium** -**Status**: ✅ **Implemented** -**Inspiration**: DependencyRegistrationGenerator's `AsSelf` parameter + // Validate immediately (DataAnnotations) + var validationContext = new ValidationContext(options); + Validator.ValidateObject(options, validationContext, validateAllProperties: true); -**Description**: Support registering options classes for both `IOptions` injection (standard pattern) AND direct type injection (without wrapper). This mirrors the `AsSelf` pattern from `[Registration]` attribute in DependencyRegistrationGenerator. + // Register instance directly (singleton) + services.AddSingleton(options); -**User Story**: -> "As a developer migrating legacy code to use OptionsBinding, I want to support both `IOptions` and direct `EntraIdOptions` injection patterns, allowing gradual migration and compatibility with third-party libraries that expect unwrapped types." + // Register IOptions wrapper + services.AddSingleton>( + new OptionsWrapper(options)); -**Problem Statement**: + // Register for IOptionsSnapshot/IOptionsMonitor (reuses same instance) + services.AddSingleton>( + sp => new OptionsWrapper(options) as IOptionsSnapshot); -When using `[OptionsBinding]`, the generator creates: + services.AddSingleton>( + sp => new OptionsMonitorWrapper(options)); -```csharp -services.AddOptions() - .Bind(configuration.GetSection("EntraId")) - .ValidateDataAnnotations() - .ValidateOnStart(); + return options; +} ``` -This **ONLY** registers for `IOptions` injection. Attempting to inject `EntraIdOptions` directly fails at runtime. +**Transitive Registration Support**: -**Real-World Scenarios**: +Just like the existing `AddOptionsFromApp()` supports transitive registration, early access must work across assemblies: -1. **Third-party libraries** - Some libraries expect direct options types, not IOptions -2. **Legacy code migration** - Existing code uses direct injection, gradual migration to IOptions -3. **Simpler syntax** - `options.Property` instead of `options.Value.Property` in simple scenarios -4. **Configuration classes** - ASP.NET middleware often expects direct types (e.g., `ConfigureSwaggerOptions`) +```csharp +// Current transitive registration (4 overloads): +services.AddOptionsFromApp(configuration); // Default +services.AddOptionsFromApp(configuration, includeReferencedAssemblies: true); // Auto-detect all +services.AddOptionsFromApp(configuration, "DataAccess"); // Specific assembly +services.AddOptionsFromApp(configuration, "DataAccess", "Infrastructure"); // Multiple assemblies + +// Early access must support the same pattern: +// Approach 1: Individual accessors from specific assemblies +var dbOptions = services.GetOrAddDatabaseOptionsFromDataAccess(configuration); // From DataAccess assembly +var apiOptions = services.GetOrAddApiOptionsFromApp(configuration); // From App assembly + +// Approach 2: Generic accessor (works after AddOptionsFrom* called) +services.AddOptionsFromApp(configuration, includeReferencedAssemblies: true); +var dbOptions = services.GetOptionInstanceOf(); // From any registered assembly +var apiOptions = services.GetOptionInstanceOf(); +``` -**Proposed Solution**: +**Alternative API - Extension Method Returning from Internal Registry**: ```csharp -// Enable dual registration with new parameter -[OptionsBinding("EntraId", AlsoRegisterDirectType = true, ValidateOnStart = true)] -public partial class EntraIdOptions -{ - [Required] - public string TenantId { get; set; } = string.Empty; +// User's suggestion: Retrieve from internal cache after AddOptionsFromApp +services.AddOptionsFromApp(configuration); - [Required] - public string ClientId { get; set; } = string.Empty; +// Get instance from internal registry (no BuildServiceProvider) +var dbOptions = services.GetOptionInstanceOf(); +var apiOptions = services.GetOptionInstanceOf(); - [Required, Url] - public string Instance { get; set; } = "https://login.microsoftonline.com/"; -} +// Works with transitive registration too: +services.AddOptionsFromApp(configuration, includeReferencedAssemblies: true); +var domainOptions = services.GetOptionInstanceOf(); // From Domain assembly +var dataAccessOptions = services.GetOptionInstanceOf(); // From DataAccess assembly ``` -**Generated Code**: +**Generated Internal Registry** (Shared Across Assemblies): ```csharp -// Standard IOptions registration (always generated) -services.AddOptions() - .Bind(configuration.GetSection("EntraId")) - .ValidateDataAnnotations() - .ValidateOnStart(); +// Generated ONCE in the Atc.OptionsBinding namespace (shared across all assemblies) +namespace Atc.OptionsBinding +{ + using System.Collections.Concurrent; -// ALSO register direct type (when AlsoRegisterDirectType = true) -// Direct type is derived from IOptions to ensure consistency -services.AddSingleton(sp => - sp.GetRequiredService>().Value); -``` + internal static class OptionsInstanceCache + { + private static readonly ConcurrentDictionary instances = new(); -**Usage Examples**: + internal static void Add(T instance) where T : class + => instances[typeof(T)] = instance; -```csharp -// Both injection patterns now work: + internal static T? TryGet() where T : class + => instances.TryGetValue(typeof(T), out var instance) + ? (T)instance + : null; + } +} -// Pattern 1: Standard IOptions (recommended) -public class ApiService +// Design Decision: Use shared static class with ConcurrentDictionary +// ✅ Works across referenced assemblies (DataAccess, Domain, Infrastructure) +// ✅ GetOptionInstanceOf() can retrieve options from ANY registered assembly +// ✅ Single source of truth - no duplicate instances +// ✅ Thread-safe via ConcurrentDictionary (lock-free reads, better performance) +// ✅ Cleaner code - no manual locking required + +// Generated extension method +public static T GetOptionInstanceOf(this IServiceCollection services) + where T : class { - public ApiService(IOptions options) + var instance = AppOptionsInstanceCache.TryGet(); + if (instance == null) { - var tenantId = options.Value.TenantId; + throw new InvalidOperationException( + $"Options instance of type '{typeof(T).Name}' not found. " + + $"Ensure AddOptionsFromApp() was called before GetOptionInstanceOf()."); } + + return instance; } -// Pattern 2: Direct type (for legacy code or third-party libraries) -public class ConfigureSwaggerOptions : IConfigureOptions +// Modified AddOptionsFromApp to populate shared cache (supports transitive registration) +public static IServiceCollection AddOptionsFromApp( + this IServiceCollection services, + IConfiguration configuration) { - private readonly EntraIdOptions entraIdOptions; // Direct injection! + // Create, bind, and validate DatabaseOptions + var dbOptions = new DatabaseOptions(); + configuration.GetSection("DatabaseOptions").Bind(dbOptions); - public ConfigureSwaggerOptions(EntraIdOptions entraIdOptions) - { - this.entraIdOptions = entraIdOptions; - } + var validationContext = new ValidationContext(dbOptions); + Validator.ValidateObject(dbOptions, validationContext, validateAllProperties: true); - public void Configure(SwaggerGenOptions options) + // Add to SHARED cache for early access (accessible via GetOptionInstanceOf) + OptionsInstanceCache.Add(dbOptions); + + // Register in DI + services.AddSingleton(dbOptions); + services.AddSingleton>( + new OptionsWrapper(dbOptions)); + + // Repeat for all options classes in this assembly... + + return services; +} + +// Transitive registration overloads also populate the shared cache: +public static IServiceCollection AddOptionsFromApp( + this IServiceCollection services, + IConfiguration configuration, + bool includeReferencedAssemblies) +{ + // Register current assembly options first + AddOptionsFromApp(services, configuration); + + if (includeReferencedAssemblies) { - // Simpler access: entraIdOptions.TenantId vs options.Value.TenantId + // Call generated methods from referenced assemblies + // Each one populates the shared OptionsInstanceCache + services.AddOptionsFromDomain(configuration); // Domain options added to cache + services.AddOptionsFromDataAccess(configuration); // DataAccess options added to cache + // ... auto-detect and call all referenced assembly methods } + + return services; } ``` -**Implementation Hints**: +**Implementation Recommendations**: -**1. Update `OptionsBindingAttribute.cs`:** +**Approach 1: Individual Accessor Methods (Recommended)** + +✅ **Pros**: + +- No global state +- Idempotent (safe to call multiple times) +- Works before or after `AddOptionsFromApp` +- Granular control (only get what you need) +- Thread-safe via IServiceCollection +- Clear intent and discoverability + +❌ **Cons**: + +- Generates more code (one method per options class) +- Two ways to register (could be confusing initially) + +**Approach 2: Internal Registry + GetOptionInstanceOf (User's Suggestion)** + +✅ **Pros**: + +- Clean API matching user's request +- Works well with existing `AddOptionsFromApp` +- Single method for all options types + +❌ **Cons**: + +- Global static state (testing concerns) +- Order dependency (must call `AddOptionsFromApp` first) +- Less discoverable (generic method) + +**Approach 3: Hybrid (Best of Both)** + +Generate BOTH approaches: + +```csharp +// Approach 1: Individual accessors (primary) +var dbOptions = services.GetOrAddDatabaseOptions(configuration); + +// Approach 2: Generic accessor (convenience, requires AddOptionsFromApp called first) +services.AddOptionsFromApp(configuration); +var apiOptions = services.GetOptionInstanceOf(); +``` + +**Implementation Details**: + +**Key Considerations**: + +1. **Validation Strategy**: + - Eager validation during `GetOrAdd*` (throws immediately on invalid config) + - Validates ONCE when instance is created + - No startup validation for early-access instances (would require ServiceProvider) + +2. **Lifetime Compatibility**: + - Early-access instances are ALWAYS registered as Singletons + - `IOptions`, `IOptionsSnapshot`, `IOptionsMonitor` all resolve to same instance + - Scoped lifetime not supported for early-access (singleton registration only) + +3. **Named Options**: + - Named options NOT supported for early access (require specific names) + - Only unnamed/default options can use `GetOrAdd*` or `GetOptionInstanceOf` + +4. **OnChange Callbacks**: + - Early-access instances do NOT support `OnChange` callbacks + - Use `IOptionsMonitor.OnChange()` manually if needed after provider built + +5. **ErrorOnMissingKeys**: + - Fully supported - throws during `GetOrAdd*` if section missing + - Combines with DataAnnotations validation + +6. **Idempotency**: + - Multiple calls to `GetOrAddDatabaseOptions` return same instance + - Multiple calls to `AddOptionsFromApp` won't duplicate registrations + - Safe to mix and match approaches + +7. **Multi-Assembly Support**: + - Individual `GetOrAdd*` methods are generated per-assembly with smart naming + - `GetOrAddDatabaseOptionsFromDataAccess()` - from DataAccess assembly + - `GetOrAddDatabaseOptionsFromApp()` - from App assembly (if App also has DatabaseOptions) + - `GetOptionInstanceOf()` works across all registered assemblies + - Internal registry is shared across all assemblies (static class in generated namespace) + +**Diagnostics**: + +Potential new diagnostic codes: + +- **ATCOPT017**: Early access not supported with named options (Error) +- **ATCOPT018**: Early access requires Singleton lifetime (Warning) +- **ATCOPT019**: OnChange callbacks not supported with early access (Warning) + +**Real-World Use Cases**: + +**Use Case 1: Conditional Service Registration (Feature Flags)** ```csharp -[AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = true)] -public sealed class OptionsBindingAttribute : Attribute +var features = services.GetOrAddFeaturesOptions(configuration); + +if (features.EnableRedisCache) { - // ... existing properties ... - - /// - /// Gets or sets a value indicating whether to also register the options type - /// as a direct service (not wrapped in IOptions<T>). - /// Default is false. - /// - /// - /// When true, the options class will be registered both: - /// - As IOptions<T> (standard pattern) - /// - As T directly (for legacy code or third-party libraries) - /// - /// The direct type registration resolves through IOptions<T>.Value - /// to ensure validation and configuration binding still apply. - /// - /// Trade-offs: - /// - Loses change detection (direct instance is snapshot at resolution time) - /// - Loses IOptionsSnapshot/IOptionsMonitor benefits - /// - Should be used sparingly for migration scenarios only - /// - public bool AlsoRegisterDirectType { get; set; } = false; + var redis = services.GetOrAddRedisOptions(configuration); + services.AddStackExchangeRedisCache(options => + { + options.Configuration = redis.ConnectionString; + options.InstanceName = redis.InstanceName; + }); +} +else +{ + services.AddDistributedMemoryCache(); } ``` -**2. Update `OptionsInfo.cs` (internal record):** +**Use Case 2: DbContext Configuration** ```csharp -internal sealed record OptionsInfo( - string ClassName, - string Namespace, - string AssemblyName, - string SectionName, - bool ValidateOnStart, - bool ValidateDataAnnotations, - int Lifetime, - string? ValidatorType, - string? Name, - bool ErrorOnMissingKeys, - string? OnChange, - string? PostConfigure, - string? ConfigureAll, - string?[]? ChildSections, - bool AlsoRegisterDirectType // NEW FIELD -); +var dbOptions = services.GetOrAddDatabaseOptions(configuration); + +services.AddDbContext(options => +{ + options.UseSqlServer(dbOptions.ConnectionString, + sqlOptions => + { + sqlOptions.EnableRetryOnFailure( + maxRetryCount: dbOptions.MaxRetries, + maxRetryDelay: TimeSpan.FromSeconds(dbOptions.RetryDelaySeconds), + errorNumbersToAdd: null); + }); +}); ``` -**3. Update `OptionsBindingGenerator.cs` - Parse the attribute:** +**Use Case 3: HttpClient Configuration** ```csharp -// In ExtractOptionsInfoFromAttribute() method -var alsoRegisterDirectType = false; -foreach (var namedArg in attr.NamedArguments) +var apiOptions = services.GetOrAddExternalApiOptions(configuration); + +services.AddHttpClient("ExternalAPI", client => { - if (namedArg.Key == "AlsoRegisterDirectType") - { - alsoRegisterDirectType = namedArg.Value.Value is true; - } - // ... existing named argument parsing ... -} + client.BaseAddress = new Uri(apiOptions.BaseUrl); + client.DefaultRequestHeaders.Add("X-API-Key", apiOptions.ApiKey); + client.Timeout = TimeSpan.FromSeconds(apiOptions.TimeoutSeconds); +}) +.AddPolicyHandler(Policy.TimeoutAsync( + TimeSpan.FromSeconds(apiOptions.TimeoutSeconds))); +``` + +**Use Case 4: Multi-Tenant Routing** -return new OptionsInfo( - // ... existing parameters ... - AlsoRegisterDirectType: alsoRegisterDirectType -); +```csharp +var tenants = services.GetOrAddTenantOptions(configuration); + +foreach (var tenant in tenants.EnabledTenants) +{ + services.AddScoped(sp => + new TenantContext(tenant.TenantId, tenant.DatabaseName)); +} ``` -**4. Update `OptionsBindingGenerator.cs` - Generate registration code:** +**Testing Strategy**: ```csharp -// In GenerateOptionsRegistration() method, after standard registration: +[Fact] +public void GetOrAddDatabaseOptions_Should_Return_Same_Instance_When_Called_Multiple_Times() +{ + // Arrange + var services = new ServiceCollection(); + var configuration = new ConfigurationBuilder() + .AddInMemoryCollection(new Dictionary + { + ["DatabaseOptions:ConnectionString"] = "Server=test;Database=test" + }) + .Build(); + + // Act + var instance1 = services.GetOrAddDatabaseOptions(configuration); + var instance2 = services.GetOrAddDatabaseOptions(configuration); -if (optionsInfo.AlsoRegisterDirectType) + // Assert + Assert.Same(instance1, instance2); // Idempotent - same instance + Assert.Single(services.Where(d => d.ServiceType == typeof(DatabaseOptions))); // Only one registration +} + +[Fact] +public void GetOrAddDatabaseOptions_Should_Throw_When_Validation_Fails() { - builder.AppendLine(); - builder.AppendLine(" // Also register direct type for legacy code compatibility"); + // Arrange + var services = new ServiceCollection(); + var configuration = new ConfigurationBuilder() + .AddInMemoryCollection(new Dictionary + { + ["DatabaseOptions:ConnectionString"] = "" // Empty - violates [Required] + }) + .Build(); - // Choose service lifetime based on OptionsLifetime - string serviceLifetime = optionsInfo.Lifetime switch - { - 0 => "AddSingleton", // IOptions -> Singleton - 1 => "AddScoped", // IOptionsSnapshot -> Scoped - 2 => "AddSingleton", // IOptionsMonitor -> Singleton (CurrentValue is snapshot) - _ => "AddSingleton" - }; - - // Generate registration that derives from IOptions - if (optionsInfo.Lifetime == 2) // Monitor - { - // For Monitor, use CurrentValue for latest snapshot - builder.AppendLine($" services.{serviceLifetime}(sp => "); - builder.AppendLine($" sp.GetRequiredService>().CurrentValue);"); - } - else if (optionsInfo.Lifetime == 1) // Scoped/Snapshot - { - // For Scoped, use IOptionsSnapshot - builder.AppendLine($" services.{serviceLifetime}(sp => "); - builder.AppendLine($" sp.GetRequiredService>().Value);"); - } - else // Singleton - { - // For Singleton, use IOptions - builder.AppendLine($" services.{serviceLifetime}(sp => "); - builder.AppendLine($" sp.GetRequiredService>().Value);"); - } + // Act & Assert + var exception = Assert.Throws(() => + services.GetOrAddDatabaseOptions(configuration)); + + Assert.Contains("ConnectionString", exception.Message); +} + +[Fact] +public void GetOptionInstanceOf_Should_Throw_When_AddOptionsFromApp_Not_Called() +{ + // Arrange + var services = new ServiceCollection(); + + // Act & Assert + var exception = Assert.Throws(() => + services.GetOptionInstanceOf()); + + Assert.Contains("AddOptionsFromApp", exception.Message); } ``` -**5. Add Diagnostic (Optional but Recommended):** +**Sample Project - Program.cs** (Multi-Project Scenario): ```csharp -// ATCOPT017: Warning when AlsoRegisterDirectType is used with named options -private static readonly DiagnosticDescriptor DirectTypeWithNamedOptionsWarning = new( - id: "ATCOPT017", - title: "AlsoRegisterDirectType not recommended with named options", - messageFormat: "Options class '{0}' uses AlsoRegisterDirectType with named options. Direct type registration only resolves the default unnamed instance, not named instances.", - category: "OptionsBinding", - defaultSeverity: DiagnosticSeverity.Warning, - isEnabledByDefault: true); - -// ATCOPT018: Warning about loss of change detection -private static readonly DiagnosticDescriptor DirectTypeLosesChangeDetection = new( - id: "ATCOPT018", - title: "AlsoRegisterDirectType loses change detection", - messageFormat: "Options class '{0}' uses AlsoRegisterDirectType with Monitor lifetime. Direct type injection will not receive configuration changes. Consider using IOptionsMonitor instead.", - category: "OptionsBinding", - defaultSeverity: DiagnosticSeverity.Info, - isEnabledByDefault: true); -``` +var builder = WebApplication.CreateBuilder(args); +var services = builder.Services; +var configuration = builder.Configuration; + +// ✅ Early access pattern - get options during registration from multiple assemblies +// Approach 1: Individual accessors (type-safe, assembly-specific) +var dbOptions = services.GetOrAddDatabaseOptionsFromDataAccess(configuration); // From DataAccess assembly +var features = services.GetOrAddFeaturesOptionsFromDomain(configuration); // From Domain assembly +var apiOptions = services.GetOrAddExternalApiOptionsFromApp(configuration); // From App assembly + +// Use options immediately for conditional registration +if (features.EnableDatabase) +{ + services.AddDbContext(options => + options.UseSqlServer(dbOptions.ConnectionString, + sqlOptions => sqlOptions.EnableRetryOnFailure( + maxRetryCount: dbOptions.MaxRetries, + maxRetryDelay: TimeSpan.FromSeconds(dbOptions.RetryDelaySeconds), + errorNumbersToAdd: null))); +} -**Design Decisions**: +if (features.EnableRedisCache) +{ + var cacheOptions = services.GetOrAddCacheOptionsFromInfrastructure(configuration); + services.AddStackExchangeRedisCache(options => + { + options.Configuration = cacheOptions.ConnectionString; + options.InstanceName = cacheOptions.InstanceName; + }); +} +else +{ + services.AddDistributedMemoryCache(); +} -1. **Single source of truth**: Direct type is ALWAYS derived from `IOptions.Value` or `IOptionsSnapshot.Value` or `IOptionsMonitor.CurrentValue` - - This ensures validation runs for both injection patterns - - Configuration binding is consistent - - No duplication of registration logic +// Configure HTTP clients +services.AddHttpClient("ExternalAPI", client => +{ + client.BaseAddress = new Uri(apiOptions.BaseUrl); + client.DefaultRequestHeaders.Add("X-API-Key", apiOptions.ApiKey); + client.Timeout = TimeSpan.FromSeconds(apiOptions.TimeoutSeconds); +}); -2. **Lifetime mapping**: - - `OptionsLifetime.Singleton` → `AddSingleton(sp => IOptions.Value)` - - `OptionsLifetime.Scoped` → `AddScoped(sp => IOptionsSnapshot.Value)` - - `OptionsLifetime.Monitor` → `AddSingleton(sp => IOptionsMonitor.CurrentValue)` +// Register remaining options normally with transitive registration (idempotent - won't duplicate) +// This also makes options available via IOptions injection +services.AddOptionsFromApp(configuration, includeReferencedAssemblies: true); -3. **Named options incompatibility**: - - Direct type registration only works with unnamed (default) options - - Named options require `IOptionsSnapshot.Get(name)` for resolution - - Should emit warning (ATCOPT017) if both are used +// Alternative Approach 2: Generic accessor (after AddOptionsFrom* called) +// var petStoreOptions = services.GetOptionInstanceOf(); // From any registered assembly -4. **Change detection limitation**: - - Direct injection gets a snapshot at resolution time - - Does NOT receive updates when configuration changes - - Should emit info diagnostic (ATCOPT018) when used with Monitor lifetime +var app = builder.Build(); +app.Run(); +``` -**Trade-Offs and Warnings**: +**Sample Project - 3-Layer Architecture**: -**✅ Benefits:** -- **Migration path**: Gradual transition from direct injection to IOptions -- **Third-party compatibility**: Works with libraries expecting direct types -- **Simpler syntax**: `options.Property` vs `options.Value.Property` -- **Validation preserved**: Direct type still goes through options pipeline +``` +PetStore.Api (Program.cs) +├── GetOrAddExternalApiOptionsFromApp() → Use immediately for HttpClient config +├── GetOrAddFeaturesOptionsFromDomain() → Use for conditional service registration +└── GetOrAddDatabaseOptionsFromDataAccess() → Use for DbContext configuration -**⚠️ Drawbacks:** -- **Loss of change detection**: Direct instance is snapshot, not live -- **Loss of scoping benefits**: Especially with Monitor + Singleton -- **API surface expansion**: More ways to inject = more confusion -- **Encourages anti-pattern**: May discourage proper IOptions usage +PetStore.Domain +├── FeaturesOptions [OptionsBinding] +└── PetStoreOptions [OptionsBinding] -**Documentation Notes**: +PetStore.DataAccess +└── DatabaseOptions [OptionsBinding] +``` -When documenting this feature, emphasize: +**Best Practices**: -1. **Use sparingly**: Only for migration scenarios or third-party compatibility -2. **Prefer IOptions**: The standard pattern should be default choice -3. **Understand trade-offs**: Loss of change detection and scoping benefits -4. **Not for production patterns**: Consider refactoring to IOptions long-term +1. **Use for Conditional Registration**: Only use early access when you need options DURING registration +2. **Validate Eagerly**: Early access validates immediately - ensure appsettings.json is correct before deployment +3. **Single Provider Build**: Only call `BuildServiceProvider()` ONCE at the end +4. **Combine with AddOptionsFromApp**: Call both for completeness (idempotent) +5. **Avoid for Scoped Options**: Early access uses Singleton lifetime - not suitable for per-request configuration -**Unit Test Coverage**: +**Benefits**: -```csharp -// Test: AlsoRegisterDirectType generates both registrations -[Fact] -public void Generator_Should_Register_Both_IOptions_And_DirectType_When_AlsoRegisterDirectType_True() -{ - const string source = """ - [OptionsBinding("Database", AlsoRegisterDirectType = true)] - public partial class DatabaseOptions - { - public string ConnectionString { get; set; } - } - """; +✅ **Eliminates Anti-Pattern**: No more multiple `BuildServiceProvider()` calls +✅ **Production-Safe**: Prevents memory leaks and scope issues +✅ **Type-Safe**: Full compile-time validation and IntelliSense +✅ **Fail-Fast**: Validation errors caught immediately during registration +✅ **Flexible**: Use individual accessors OR generic registry method +✅ **Idempotent**: Safe to call multiple times +✅ **Zero Runtime Cost**: All code generated at compile time - var (diagnostics, output) = GetGeneratedOutput(source); +--- - Assert.Empty(diagnostics); - Assert.Contains("AddOptions", output); - Assert.Contains("services.AddSingleton(sp =>", output); - Assert.Contains("IOptions>().Value", output); -} +### 11. Auto-Generate Options Classes from appsettings.json -// Test: Different lifetimes generate correct service registrations -[Theory] -[InlineData("OptionsLifetime.Singleton", "AddSingleton", "IOptions")] -[InlineData("OptionsLifetime.Scoped", "AddScoped", "IOptionsSnapshot")] -[InlineData("OptionsLifetime.Monitor", "AddSingleton", "IOptionsMonitor")] -public void Generator_Should_Use_Correct_Lifetime_For_DirectType( - string lifetime, string expectedMethod, string expectedInterface) { } +**Priority**: 🟢 **Low** +**Status**: ❌ Not Implemented -// Test: Warning emitted when used with named options -[Fact] -public void Generator_Should_Warn_When_AlsoRegisterDirectType_With_Named_Options() { } +**Description**: Reverse the process - analyze appsettings.json and generate strongly-typed options classes. -// Test: Info diagnostic for Monitor + direct type -[Fact] -public void Generator_Should_Emit_Info_When_DirectType_With_Monitor_Lifetime() { } +**Example**: -// Test: Works with all validation features -[Fact] -public void Generator_Should_Support_Validation_With_DirectType() { } +```json +{ + "Database": { + "ConnectionString": "...", + "MaxRetries": 5 + } +} ``` -**Implementation Status**: +Generates: -✅ **Core Implementation Complete:** -- Updated `OptionsBindingAttribute.cs` with `AlsoRegisterDirectType` property -- Updated `OptionsInfo` record to include `AlsoRegisterDirectType` field -- Updated `OptionsBindingGenerator.cs` to parse and generate direct type registration -- Correctly handles all three lifetimes (Singleton, Scoped, Monitor) -- Direct type resolves through appropriate IOptions interface (.Value or .CurrentValue) -- Named options correctly excluded from direct type registration +```csharp +// Auto-generated +public partial class DatabaseOptions +{ + public string ConnectionString { get; set; } = string.Empty; + public int MaxRetries { get; set; } +} +``` -✅ **Testing Complete:** -- 10 comprehensive unit tests covering all scenarios (OptionsBindingGeneratorAlsoRegisterDirectTypeTests.cs) -- Tests cover: Singleton/Scoped/Monitor lifetimes, named options exclusion, validation, ErrorOnMissingKeys, PostConfigure, ChildSections -- All 291 existing tests pass - zero regressions -- Solution builds successfully +**Considerations**: -✅ **Sample Projects Updated:** -- `Atc.SourceGenerators.OptionsBinding`: Added `LegacyIntegrationOptions` demonstrating the feature -- `PetStore.Api`: Updated `ExternalApiOptions` with AlsoRegisterDirectType for third-party library compatibility +- Requires JSON schema inference +- Type ambiguity (is "5" an int or string?) +- May conflict with user-defined classes +- Interesting but low priority -📝 **Documentation Updates** (in progress): -- Feature roadmap updated to mark as ✅ Implemented -- Remaining: OptionsBindingGenerators.md, OptionsBindingGenerators-Samples.md, readme.md, CLAUDE.md +--- -**Alternative Names Considered**: +### 12. Environment-Specific Validation -- `RegisterDirectType` - Less clear about "also" -- `AsSelf` - Reuses DependencyRegistration naming (might cause confusion between generators) -- `EnableDirectInjection` - More verbose -- `AlsoRegisterDirectType` - ✅ **CHOSEN** - Clear intent, mirrors `AsSelf` pattern semantically +**Priority**: 🟢 **Low** +**Status**: ❌ Not Implemented -**Related Features**: +**Description**: Apply different validation rules based on environment (e.g., stricter in production). -This feature mirrors the `AsSelf` parameter from DependencyRegistrationGenerator: +**Example**: ```csharp -// DependencyRegistrationGenerator (existing): -[Registration(As = typeof(IUserService), AsSelf = true)] -public class UserService : IUserService { } +[OptionsBinding("Features", ValidateOnStart = true)] +public partial class FeaturesOptions +{ + public bool EnableDebugMode { get; set; } -// Generates: -services.AddSingleton(); -services.AddSingleton(); // Concrete type + // Only validate in production + [RequiredInProduction] + public string LicenseKey { get; set; } = string.Empty; +} +``` -// OptionsBindingGenerator (proposed): -[OptionsBinding("Database", AlsoRegisterDirectType = true)] -public partial class DatabaseOptions { } +--- -// Generates: -services.AddOptions()... -services.AddSingleton(sp => IOptions.Value); // Direct type -``` +### 13. Hot Reload Support with Filtering + +**Priority**: 🟢 **Low** +**Status**: ❌ Not Implemented -**Compatibility**: +**Description**: Fine-grained control over which configuration changes trigger reloads. -- ✅ .NET 6, 7, 8, 9+ -- ✅ Native AOT compatible -- ✅ Works with all existing OptionsBinding features -- ⚠️ Not compatible with named options (warning emitted) -- ⚠️ Change detection limited for direct injection +**Example**: + +```csharp +[OptionsBinding("Features", Lifetime = OptionsLifetime.Monitor, ReloadOn = new[] { "EnableNewUI", "MaxUploadSizeMB" })] +public partial class FeaturesOptions +{ + public bool EnableNewUI { get; set; } // Triggers reload + public int MaxUploadSizeMB { get; set; } // Triggers reload + public string UITheme { get; set; } = "Light"; // Doesn't trigger reload +} +``` --- @@ -1364,52 +1547,84 @@ services.AddSingleton(sp => IOptions.Value); // Direct type Based on priority, user demand, and implementation complexity: -### Phase 1: Validation & Error Handling (v1.1 - Q1 2025) +### Phase 1: Validation & Error Handling (v1.1 - Q1 2025) ✅ COMPLETED **Goal**: Fail-fast and better validation -1. **Error on Missing Configuration Keys** 🔴 High ⭐ - Startup failures instead of silent nulls -2. **Custom Validation Support (IValidateOptions)** 🔴 High - Complex validation beyond DataAnnotations -3. **Post-Configuration Support** 🟡 Medium-High - Normalization and defaults +1. **Error on Missing Configuration Keys** 🔴 High ⭐ - Startup failures instead of silent nulls ✅ +2. **Custom Validation Support (IValidateOptions)** 🔴 High - Complex validation beyond DataAnnotations ✅ +3. **Post-Configuration Support** 🟡 Medium-High - Normalization and defaults ✅ **Estimated effort**: 3-4 weeks **Impact**: Prevent production misconfigurations, better developer experience +**Status**: ✅ All features implemented and shipped --- -### Phase 2: Advanced Scenarios (v1.2 - Q2 2025) +### Phase 2: Advanced Scenarios (v1.2 - Q2 2025) ✅ COMPLETED **Goal**: Multi-tenant and dynamic configuration -4. **Named Options Support** 🔴 High - Multiple configurations for same type -5. **Configuration Change Callbacks** 🟡 Medium - React to runtime changes -6. **ConfigureAll Support** 🟢 Low-Medium - Set defaults across named instances +4. **Named Options Support** 🔴 High - Multiple configurations for same type ✅ +5. **Configuration Change Callbacks** 🟡 Medium - React to runtime changes ✅ +6. **ConfigureAll Support** 🟢 Low-Medium - Set defaults across named instances ✅ **Estimated effort**: 4-5 weeks **Impact**: Multi-tenant scenarios, feature flags, runtime configuration +**Status**: ✅ All features implemented and shipped --- -### Phase 3: Developer Experience (v1.3 - Q3 2025) +### Phase 3: Developer Experience (v1.3 - Q3 2025) ✅ COMPLETED **Goal**: Better diagnostics and usability -7. **Compile-Time Section Name Validation** 🟡 Medium - Validate section paths exist -8. **Bind Configuration Subsections** 🟡 Medium - Nested object binding (may already work) -9. **Environment-Specific Validation** 🟢 Low - Production vs. development validation +7. **Bind Configuration Subsections** 🟡 Medium - Nested object binding (already worked out-of-the-box) ✅ +8. **Child Sections** 🟢 Low-Medium - Simplified named options syntax ✅ +9. **Compile-Time Section Name Validation** 🟡 Medium - Validate section paths exist ❌ Deferred **Estimated effort**: 3-4 weeks **Impact**: Catch configuration errors earlier, better IDE support +**Status**: ✅ Core features implemented + +--- + +### Phase 4: Service Registration Integration (v1.4 - 2025) + +**Goal**: Eliminate BuildServiceProvider anti-pattern + +10. **Early Access to Options During Service Registration** 🔴 High ⭐ - Access options during registration without BuildServiceProvider + - Generate `GetOrAddDatabaseOptions()` individual accessor methods + - Generate `GetOptionInstanceOf()` generic accessor method + - Internal registry for option instances + - Idempotent registration + - Eager validation support + +**Estimated effort**: 3-4 weeks +**Impact**: + +- Prevents memory leaks and scope issues from multiple BuildServiceProvider calls +- Enables conditional service registration based on configuration +- Production-safe pattern for DbContext, HttpClient, and feature flag configuration +- Critical for real-world ASP.NET Core applications + +**Priority Justification**: This is a HIGH priority feature because: + +- ⚠️ Multiple BuildServiceProvider calls is a **documented anti-pattern** by Microsoft +- 🐛 Causes production bugs (memory leaks, lifetime issues) +- ⭐ Frequently requested in StackOverflow (66k+ views on related questions) +- 🔥 Blocking issue for developers needing configuration-driven service registration --- -### Phase 4: Optional Enhancements (v2.0+ - 2025-2026) +### Phase 5: Optional Enhancements (v2.0+ - 2025-2026) **Goal**: Nice-to-have features based on feedback -10. **Hot Reload with Filtering** 🟢 Low - Fine-grained reload control 11. **Auto-Generate Options from JSON** 🟢 Low - Reverse generation (experimental) -12. **Options Snapshots for Sections** 🟢 Low-Medium - Dynamic section binding +12. **Environment-Specific Validation** 🟢 Low - Production vs. development validation +13. **Hot Reload with Filtering** 🟢 Low - Fine-grained reload control +14. **Compile-Time Section Name Validation** 🟡 Medium - Validate section paths exist (deferred from Phase 3) **Estimated effort**: Variable **Impact**: Polish and edge cases @@ -1418,20 +1633,21 @@ Based on priority, user demand, and implementation complexity: ### Feature Prioritization Matrix -| Feature | Priority | User Demand | Complexity | Phase | -|---------|----------|-------------|------------|-------| -| Error on Missing Keys | 🔴 High | ⭐⭐⭐ | Medium | 1.1 | -| Custom Validation (IValidateOptions) | 🔴 High | ⭐⭐⭐ | Medium | 1.1 | -| Post-Configuration | 🟡 Med-High | ⭐⭐ | Low | 1.1 | -| Named Options | 🔴 High | ⭐⭐⭐ | Medium | 1.2 | -| Change Callbacks | 🟡 Medium | ⭐⭐ | Medium | 1.2 | -| ConfigureAll | 🟢 Low-Med | ⭐ | Low | 1.2 | -| Section Path Validation | 🟡 Medium | ⭐⭐ | High | 1.3 | -| Nested Object Binding | 🟡 Medium | ⭐⭐ | Low | 1.3 | -| Environment Validation | 🟢 Low | ⭐ | Medium | 1.3 | -| Direct Type Registration | 🟡 Medium | ⭐⭐ | Medium | 1.4 | -| Hot Reload Filtering | 🟢 Low | ⭐ | Medium | 2.0+ | -| Auto-Generate from JSON | 🟢 Low | ⭐ | High | 2.0+ | +| Feature | Priority | User Demand | Complexity | Phase | Status | +|---------|----------|-------------|------------|-------|--------| +| Error on Missing Keys | 🔴 High | ⭐⭐⭐ | Medium | 1.1 | ✅ | +| Custom Validation (IValidateOptions) | 🔴 High | ⭐⭐⭐ | Medium | 1.1 | ✅ | +| Post-Configuration | 🟡 Med-High | ⭐⭐ | Low | 1.1 | ✅ | +| Named Options | 🔴 High | ⭐⭐⭐ | Medium | 1.2 | ✅ | +| Change Callbacks | 🟡 Medium | ⭐⭐ | Medium | 1.2 | ✅ | +| ConfigureAll | 🟢 Low-Med | ⭐ | Low | 1.2 | ✅ | +| Nested Object Binding | 🟡 Medium | ⭐⭐ | Low | 1.3 | ✅ | +| Child Sections | 🟢 Low-Med | ⭐⭐ | Low | 1.3 | ✅ | +| **Early Access to Options** | 🔴 **High** | ⭐⭐⭐ | **Medium-High** | **1.4** | ✅ | +| Section Path Validation | 🟡 Medium | ⭐⭐ | High | 2.0+ | ❌ | +| Environment Validation | 🟢 Low | ⭐ | Medium | 2.0+ | ❌ | +| Hot Reload Filtering | 🟢 Low | ⭐ | Medium | 2.0+ | ❌ | +| Auto-Generate from JSON | 🟢 Low | ⭐ | High | 2.0+ | ❌ | --- @@ -1505,6 +1721,5 @@ Based on priority, user demand, and implementation complexity: **Last Updated**: 2025-01-20 **Version**: 1.2 -**Research Date**: January 2025 (.NET 8/9 Options Pattern) +**Research Date**: January 2025 (.NET 8/9 Options Pattern + Service Registration Anti-Patterns) **Maintained By**: Atc.SourceGenerators Team -**Note**: Feature #13 (Direct Type Registration) added based on real-world usage patterns from KL.IoT.Nexus project diff --git a/docs/OptionsBindingGenerators-Samples.md b/docs/OptionsBindingGenerators-Samples.md index cdb48f7..503057c 100644 --- a/docs/OptionsBindingGenerators-Samples.md +++ b/docs/OptionsBindingGenerators-Samples.md @@ -14,6 +14,7 @@ This sample demonstrates the **OptionsBindingGenerator** in a multi-project cons - **Configuration change callbacks** - Automatic OnChange notifications with Monitor lifetime - **Child sections** - Simplified syntax for multiple named configurations (Email → Primary/Secondary/Fallback) - **Nested subsection binding** - Automatic binding of complex properties to configuration subsections +- **Early access to options** - Retrieve options during service registration without BuildServiceProvider() anti-pattern ## 📁 Sample Projects @@ -1124,11 +1125,13 @@ The **OptionsBindingGenerator** automatically handles nested configuration subse ### 🎯 How It Works When you have properties that are complex types (not primitives like string, int, etc.), the configuration binder automatically: + 1. Detects the property is a complex type 2. Looks for a subsection with the same name 3. Recursively binds that subsection to the property This works for: + - **Nested objects** - Properties with custom class types - **Collections** - List, IEnumerable, arrays - **Dictionaries** - Dictionary, Dictionary diff --git a/docs/OptionsBindingGenerators.md b/docs/OptionsBindingGenerators.md index e842939..20c3ea1 100644 --- a/docs/OptionsBindingGenerators.md +++ b/docs/OptionsBindingGenerators.md @@ -35,7 +35,7 @@ services.AddOptions() ## 📑 Table of Contents - [⚙️ Options Binding Source Generator](#️-options-binding-source-generator) - - [� Documentation Navigation](#-documentation-navigation) + - [📖 Documentation Navigation](#-documentation-navigation) - [📑 Table of Contents](#-table-of-contents) - [📖 Overview](#-overview) - [😫 Before (Manual Approach)](#-before-manual-approach) @@ -77,6 +77,9 @@ services.AddOptions() - [🎯 Custom Validation (IValidateOptions)](#-custom-validation-ivalidateoptions) - [🚨 Error on Missing Configuration Keys](#-error-on-missing-configuration-keys) - [⏱️ Options Lifetimes](#️-options-lifetimes) + - [🔔 Configuration Change Callbacks](#-configuration-change-callbacks) + - [🔧 Post-Configuration Support](#-post-configuration-support) + - [🎛️ ConfigureAll Support](#️-configureall-support) - [🔧 How It Works](#-how-it-works) - [1️⃣ Attribute Detection](#1️⃣-attribute-detection) - [2️⃣ Section Name Resolution](#2️⃣-section-name-resolution) @@ -85,16 +88,51 @@ services.AddOptions() - [🎯 Advanced Scenarios](#-advanced-scenarios) - [🏢 Multiple Assemblies](#-multiple-assemblies) - [✨ Smart Naming](#-smart-naming) - - [📂 Nested Configuration](#-nested-configuration) + - [📂 Nested Configuration (Feature #6: Bind Configuration Subsections to Properties)](#-nested-configuration-feature-6-bind-configuration-subsections-to-properties) + - [🎯 How It Works](#-how-it-works-1) + - [📋 Example 1: Simple Nested Objects](#-example-1-simple-nested-objects) + - [📋 Example 2: Deeply Nested Objects (3 Levels)](#-example-2-deeply-nested-objects-3-levels) + - [📋 Example 3: Real-World Scenario (Cloud Storage)](#-example-3-real-world-scenario-cloud-storage) + - [🎯 Key Points](#-key-points) + - [📍 Explicit Nested Paths](#-explicit-nested-paths) + - [⚡ Early Access to Options (Avoid BuildServiceProvider Anti-Pattern)](#-early-access-to-options-avoid-buildserviceprovider-anti-pattern) + - [🎯 Key Features](#-key-features) + - [📋 Basic Usage](#-basic-usage) + - [🔄 Idempotency Example](#-idempotency-example) + - [🛡️ Validation Example](#️-validation-example) + - [🚀 Real-World Use Cases](#-real-world-use-cases) + - [⚙️ How It Works](#️-how-it-works) + - [⚠️ Limitations](#️-limitations) + - [🎓 Best Practices](#-best-practices) - [🌍 Environment-Specific Configuration](#-environment-specific-configuration) + - [📛 Named Options (Multiple Configurations)](#-named-options-multiple-configurations) + - [✨ Use Cases](#-use-cases) + - [🎯 Basic Example](#-basic-example) + - [🔧 Generated Code](#-generated-code) + - [⚠️ Important Notes](#️-important-notes) + - [🎯 Mixing Named and Unnamed Options](#-mixing-named-and-unnamed-options) + - [🎯 Child Sections (Simplified Named Options)](#-child-sections-simplified-named-options) + - [✨ Use Cases](#-use-cases-1) + - [🎯 Basic Example](#-basic-example-1) + - [📋 Configuration Structure](#-configuration-structure) + - [🔧 Advanced Features](#-advanced-features) + - [📍 Nested Paths](#-nested-paths) + - [🚨 Validation Rules](#-validation-rules) + - [💡 Key Benefits](#-key-benefits) + - [📊 ChildSections vs Multiple Attributes](#-childsections-vs-multiple-attributes) + - [🎯 Real-World Example](#-real-world-example) - [🛡️ Diagnostics](#️-diagnostics) - [❌ ATCOPT001: Options class must be partial](#-atcopt001-options-class-must-be-partial) - [❌ ATCOPT002: Section name cannot be null or empty](#-atcopt002-section-name-cannot-be-null-or-empty) - [⚠️ ATCOPT003: Invalid options binding configuration](#️-atcopt003-invalid-options-binding-configuration) - [❌ ATCOPT003: Const section name cannot be null or empty](#-atcopt003-const-section-name-cannot-be-null-or-empty) + - [❌ ATCOPT004-007: OnChange Callback Diagnostics](#-atcopt004-007-onchange-callback-diagnostics) + - [❌ ATCOPT008-010: PostConfigure Callback Diagnostics](#-atcopt008-010-postconfigure-callback-diagnostics) + - [❌ ATCOPT011-013: ConfigureAll Callback Diagnostics](#-atcopt011-013-configureall-callback-diagnostics) + - [❌ ATCOPT014-016: ChildSections Diagnostics](#-atcopt014-016-childsections-diagnostics) - [🚀 Native AOT Compatibility](#-native-aot-compatibility) - [✅ AOT-Safe Features](#-aot-safe-features) - - [🏗️ How It Works](#️-how-it-works) + - [🏗️ How It Works](#️-how-it-works-1) - [📋 Example Generated Code](#-example-generated-code) - [🎯 Multi-Project AOT Support](#-multi-project-aot-support) - [📚 Examples](#-examples) @@ -749,6 +787,7 @@ Console.WriteLine($"Other interval: {otherOptions.Value.RepeatIntervalInSeconds} - **🎛️ 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** - 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 configuration subsections (e.g., Email → Primary/Secondary/Fallback) +- **⚡ Early access to options** - Access bound and validated options during service registration without BuildServiceProvider() anti-pattern (via `GetOrAdd*` methods) - **🎯 Explicit section paths** - Support for nested sections like `"App:Database"` or `"Services:Email"` - **📂 Nested subsection binding** - Automatically bind complex properties to configuration subsections (e.g., `StorageOptions.Database.Retry` → `"Storage:Database:Retry"`) - **📦 Multiple options classes** - Register multiple configuration sections in a single assembly with one method call @@ -1030,6 +1069,7 @@ services.AddSingleton() ``` **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. @@ -1177,6 +1221,7 @@ public class FeatureManager Automatically respond to configuration changes at runtime using the `OnChange` property. This feature enables hot-reload of configuration without restarting your application. **Requirements:** + - Must use `Lifetime = OptionsLifetime.Monitor` - Requires appsettings.json with `reloadOnChange: true` - Cannot be used with named options @@ -1287,6 +1332,7 @@ public partial class DatabaseOptions The generator performs compile-time validation of OnChange callbacks: - **ATCOPT004**: OnChange callback requires Monitor lifetime + ```csharp // ❌ Error: Must use Lifetime = OptionsLifetime.Monitor [OptionsBinding("Settings", OnChange = nameof(OnChanged))] @@ -1294,6 +1340,7 @@ The generator performs compile-time validation of OnChange callbacks: ``` - **ATCOPT005**: OnChange callback not supported with named options + ```csharp // ❌ Error: Named options don't support OnChange [OptionsBinding("Email", Name = "Primary", Lifetime = OptionsLifetime.Monitor, OnChange = nameof(OnChanged))] @@ -1301,6 +1348,7 @@ The generator performs compile-time validation of OnChange callbacks: ``` - **ATCOPT006**: OnChange callback method not found + ```csharp // ❌ Error: Method 'OnSettingsChanged' does not exist [OptionsBinding("Settings", Lifetime = OptionsLifetime.Monitor, OnChange = "OnSettingsChanged")] @@ -1308,6 +1356,7 @@ The generator performs compile-time validation of OnChange callbacks: ``` - **ATCOPT007**: OnChange callback method has invalid signature + ```csharp // ❌ Error: Must be static void with (TOptions, string?) parameters [OptionsBinding("Settings", Lifetime = OptionsLifetime.Monitor, OnChange = nameof(OnChanged))] @@ -1332,6 +1381,7 @@ The generator performs compile-time validation of OnChange callbacks: Automatically normalize, validate, or transform configuration values after binding using the `PostConfigure` property. This feature enables applying defaults, normalizing paths, lowercasing URLs, or computing derived properties. **Requirements:** + - Cannot be used with named options - Callback method must have signature: `static void MethodName(TOptions options)` - Runs after binding and validation @@ -1447,6 +1497,7 @@ public partial class DatabaseOptions The generator performs compile-time validation of PostConfigure callbacks: - **ATCOPT008**: PostConfigure callback not supported with named options + ```csharp // Error: Named options don't support PostConfigure [OptionsBinding("Email", Name = "Primary", PostConfigure = nameof(Normalize))] @@ -1454,6 +1505,7 @@ The generator performs compile-time validation of PostConfigure callbacks: ``` - **ATCOPT009**: PostConfigure callback method not found + ```csharp // Error: Method 'ApplyDefaults' does not exist [OptionsBinding("Settings", PostConfigure = "ApplyDefaults")] @@ -1461,6 +1513,7 @@ The generator performs compile-time validation of PostConfigure callbacks: ``` - **ATCOPT010**: PostConfigure callback method has invalid signature + ```csharp // Error: Must be static void with (TOptions) parameter [OptionsBinding("Settings", PostConfigure = nameof(Configure))] @@ -1485,6 +1538,7 @@ The generator performs compile-time validation of PostConfigure callbacks: Set default values for **all named options instances** before individual configuration binding. This feature is perfect for establishing common baseline settings across multiple named configurations that can then be selectively overridden. **Requirements:** + - Requires multiple named instances (at least 2) - Callback method must have signature: `static void MethodName(TOptions options)` - Runs **before** individual `Configure()` calls @@ -1578,6 +1632,7 @@ public partial class DatabaseConnectionOptions The generator performs compile-time validation of ConfigureAll callbacks: - **ATCOPT011**: ConfigureAll requires multiple named options + ```csharp // Error: ConfigureAll needs at least 2 named instances [OptionsBinding("Settings", Name = "Default", ConfigureAll = nameof(SetDefaults))] @@ -1585,6 +1640,7 @@ The generator performs compile-time validation of ConfigureAll callbacks: ``` - **ATCOPT012**: ConfigureAll callback method not found + ```csharp // Error: Method 'SetDefaults' does not exist [OptionsBinding("Email", Name = "Primary", ConfigureAll = "SetDefaults")] @@ -1593,6 +1649,7 @@ The generator performs compile-time validation of ConfigureAll callbacks: ``` - **ATCOPT013**: ConfigureAll callback method has invalid signature + ```csharp // Error: Must be static void with (TOptions) parameter [OptionsBinding("Email", Name = "Primary", ConfigureAll = nameof(Configure))] @@ -1764,11 +1821,13 @@ The generator automatically handles nested configuration subsections through Mic #### 🎯 How It Works When you have properties that are complex types (not primitives like string, int, etc.), the configuration binder automatically: + 1. Detects the property is a complex type 2. Looks for a subsection with the same name 3. Recursively binds that subsection to the property This works for: + - **Nested objects** - Properties with custom class types - **Collections** - List, IEnumerable, arrays - **Dictionaries** - Dictionary, Dictionary @@ -1954,6 +2013,254 @@ public partial class SmtpOptions } ``` +### ⚡ Early Access to Options (Avoid BuildServiceProvider Anti-Pattern) + +**Problem:** Sometimes you need to access options values **during service registration** to make conditional decisions, but calling `BuildServiceProvider()` in the middle of registration is an anti-pattern that causes: + +- ❌ Memory leaks +- ❌ Scope issues +- ❌ Application instability + +**Solution:** The generator provides three APIs for early access to bound and validated options without building the service provider: + +| Method | Reads Cache | Writes Cache | Use Case | +|--------|-------------|--------------|----------| +| `Get[Type]From[Assembly]()` | ✅ Yes | ❌ No | Efficient retrieval (uses cached if available, no side effects) | +| `GetOrAdd[Type]From[Assembly]()` | ✅ Yes | ✅ Yes | Early access with caching for idempotency | +| `GetOptions()` | ✅ Yes | ❌ No | Smart dispatcher (calls Get internally, multi-assembly support) | + +#### 🎯 Key Features + +- ✅ **Efficient caching** - Get methods read from cache when available (no unnecessary instance creation) +- ✅ **No side effects** - Get and GetOptions don't populate cache (only GetOrAdd does) +- ✅ **Idempotent GetOrAdd** - Safe to call multiple times, returns the same instance +- ✅ **Smart dispatcher** - GetOptions() works in multi-assembly projects (routes to correct Get method) +- ✅ **Immediate validation** - DataAnnotations and ErrorOnMissingKeys validation happens immediately +- ✅ **PostConfigure support** - Applies PostConfigure callbacks before returning +- ✅ **Full integration** - Works seamlessly with normal `AddOptionsFrom*` methods +- ✅ **Unnamed options only** - Named options are excluded (use standard Options pattern for those) + +#### 📋 API Approaches + +**Approach 1: Get Methods (Pure Retrieval)** + +```csharp +// Reads cache but doesn't populate - efficient, no side effects +var dbOptions1 = services.GetDatabaseOptionsFromDomain(configuration); +var dbOptions2 = services.GetDatabaseOptionsFromDomain(configuration); +// If GetOrAdd was never called: dbOptions1 != dbOptions2 (creates fresh instances) +// If GetOrAdd was called first: dbOptions1 == dbOptions2 (returns cached) + +if (dbOptions1.EnableFeatureX) +{ + services.AddScoped(); +} +``` + +**Approach 2: GetOrAdd Methods (With Caching)** + +```csharp +// Populates cache on first call - use for idempotency +var dbOptions1 = services.GetOrAddDatabaseOptionsFromDomain(configuration); +var dbOptions2 = services.GetOrAddDatabaseOptionsFromDomain(configuration); +// dbOptions1 == dbOptions2 (always true - cached and reused) + +if (dbOptions1.EnableFeatureX) +{ + services.AddScoped(); +} +``` + +**Approach 3: Generic Smart Dispatcher (Multi-Assembly)** + +```csharp +// Convenience method - routes to Get method internally (no caching side effects) +// Works in multi-assembly projects! No CS0121 ambiguity +var dbOptions = services.GetOptions(configuration); + +if (dbOptions.EnableFeatureX) +{ + services.AddScoped(); +} +``` + +#### ⚖️ When to Use Which API + +**Use `Get[Type]...` when:** +- ✅ You want efficient retrieval (benefits from cache if available) +- ✅ You don't want side effects (no cache population) +- ✅ You're okay with fresh instances if cache is empty + +**Use `GetOrAdd[Type]...` when:** +- ✅ You need idempotency (same instance on repeated calls) +- ✅ You want to explicitly populate cache for later use +- ✅ You prefer explicit cache management + +**Use `GetOptions()` when:** +- ✅ You want concise, generic syntax +- ✅ Working in multi-assembly projects (smart dispatcher routes correctly) +- ✅ You want same behavior as Get (efficient, no side effects) + +#### 📋 Basic Usage + +```csharp +// Step 1: Get options early during service registration +// Option A: Assembly-specific (always works, recommended) +var dbOptions = services.GetOrAddDatabaseOptionsFromDomain(configuration); + +// Option B: Generic (only in single-assembly projects) +// var dbOptions = services.GetOptions(configuration); + +// Step 2: Use options to make conditional registration decisions +if (dbOptions.EnableFeatureX) +{ + services.AddScoped(); +} + +if (dbOptions.MaxRetries > 0) +{ + services.AddSingleton(new RetryPolicy(dbOptions.MaxRetries)); +} + +// Step 3: Continue with normal registration (idempotent, no duplication) +services.AddOptionsFromDomain(configuration); + +// The options are now available via IOptions, IOptionsSnapshot, IOptionsMonitor +``` + +#### 🔄 Idempotency Example + +```csharp +// First call - creates, binds, validates, and caches +var dbOptions1 = services.GetOrAddDatabaseOptionsFromDomain(configuration); +Console.WriteLine($"MaxRetries: {dbOptions1.MaxRetries}"); + +// Second call - returns cached instance (no re-binding, no re-validation) +var dbOptions2 = services.GetOrAddDatabaseOptionsFromDomain(configuration); + +// Both references point to the same instance +Console.WriteLine($"Same instance? {ReferenceEquals(dbOptions1, dbOptions2)}"); // True +``` + +#### 🛡️ Validation Example + +```csharp +// Options class with validation +[OptionsBinding("Database", ValidateDataAnnotations = 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; } +} + +// Early access - validation happens immediately +try +{ + var dbOptions = services.GetOrAddDatabaseOptionsFromDomain(configuration); + // Validation passed - options are ready to use +} +catch (ValidationException ex) +{ + // Validation failed - caught at registration time, not runtime! + Console.WriteLine($"Configuration error: {ex.Message}"); +} +``` + +#### 🚀 Real-World Use Cases + +**1. Conditional Feature Registration:** + +```csharp +var featuresOptions = services.GetOrAddFeaturesOptionsFromDomain(configuration); + +if (featuresOptions.EnableRedisCache) +{ + services.AddStackExchangeRedisCache(options => + { + options.Configuration = featuresOptions.RedisCacheConnectionString; + }); +} +else +{ + services.AddDistributedMemoryCache(); +} +``` + +**2. Dynamic Service Configuration:** + +```csharp +var storageOptions = services.GetOrAddStorageOptionsFromDomain(configuration); + +services.AddScoped(sp => +{ + return storageOptions.Provider switch + { + "Azure" => new AzureBlobStorage(storageOptions.AzureConnectionString), + "AWS" => new S3Storage(storageOptions.AwsAccessKey, storageOptions.AwsSecretKey), + _ => new LocalFileStorage(storageOptions.LocalPath) + }; +}); +``` + +**3. Validation-Based Registration:** + +```csharp +var apiOptions = services.GetOrAddApiOptionsFromDomain(configuration); + +// Only register rate limiting if enabled in config +if (apiOptions.EnableRateLimiting && apiOptions.RateLimitPerMinute > 0) +{ + services.AddRateLimiting(options => + { + options.RequestsPerMinute = apiOptions.RateLimitPerMinute; + }); +} +``` + +#### ⚙️ How It Works + +1. **First Call** to `GetOrAdd{OptionsName}()`: + - Creates new options instance + - Binds from configuration section + - Validates (DataAnnotations, ErrorOnMissingKeys) + - Applies PostConfigure callbacks + - Adds to internal cache + - Registers via `services.Configure()` + - Returns bound instance + +2. **Subsequent Calls**: + - Checks internal cache + - Returns existing instance (no re-binding, no re-validation) + +3. **Normal `AddOptionsFrom*` Call**: + - Automatically populates cache via `.PostConfigure()` + - Options available via `IOptions`, `IOptionsSnapshot`, `IOptionsMonitor` + +#### ⚠️ Limitations + +- **Unnamed options only** - Named options (`Name` property) do not generate `GetOrAdd*` methods +- **Singleton lifetime** - Early access options are registered as singleton +- **No OnChange support** - Early access is for registration-time decisions only + +#### 🎓 Best Practices + +✅ **DO:** + +- Use early access for conditional service registration +- Use early access for dynamic service configuration +- Call `GetOrAdd*` methods before `AddOptionsFrom*` +- Validate options at registration time + +❌ **DON'T:** + +- Use early access for runtime decisions (use `IOptions` instead) +- Call `BuildServiceProvider()` during registration +- Mix early access with named options (not supported) + ### 🌍 Environment-Specific Configuration ```csharp @@ -2251,6 +2558,7 @@ public partial class CacheOptions The generator performs compile-time validation: - **ATCOPT014**: ChildSections cannot be used with `Name` property + ```csharp // ❌ Error: Cannot use both ChildSections and Name [OptionsBinding("Email", Name = "Primary", ChildSections = new[] { "A", "B" })] @@ -2258,6 +2566,7 @@ The generator performs compile-time validation: ``` - **ATCOPT015**: ChildSections requires at least 2 items + ```csharp // ❌ Error: Must have at least 2 child sections [OptionsBinding("Email", ChildSections = new[] { "Primary" })] @@ -2269,6 +2578,7 @@ The generator performs compile-time validation: ``` - **ATCOPT016**: ChildSections items cannot be null or empty + ```csharp // ❌ Error: Array contains empty string [OptionsBinding("Email", ChildSections = new[] { "Primary", "", "Secondary" })] @@ -2296,6 +2606,7 @@ The generator performs compile-time validation: | Use case | Few instances | Many instances | **Recommendation:** + - Use `ChildSections` when you have 2+ related configurations under a common parent section - Use multiple `[OptionsBinding]` attributes when configurations come from different sections diff --git a/global.json b/global.json index 3140116..ceedb4c 100644 --- a/global.json +++ b/global.json @@ -1,4 +1,8 @@ { + "sdk": { + "version": "10.0.100", + "rollForward": "latestMinor" + }, "test": { "runner": "Microsoft.Testing.Platform" } diff --git a/sample/Atc.SourceGenerators.OptionsBinding.Domain/Options/EmailOptions.cs b/sample/Atc.SourceGenerators.OptionsBinding.Domain/Options/EmailOptions.cs index 1220aea..7a05de1 100644 --- a/sample/Atc.SourceGenerators.OptionsBinding.Domain/Options/EmailOptions.cs +++ b/sample/Atc.SourceGenerators.OptionsBinding.Domain/Options/EmailOptions.cs @@ -4,7 +4,7 @@ namespace Atc.SourceGenerators.OptionsBinding.Domain.Options; /// Email service configuration options. /// Demonstrates const SectionName usage (2nd priority). /// -[OptionsBinding(ValidateDataAnnotations = true)] +[OptionsBinding(ValidateDataAnnotations = true, ValidateOnStart = true)] public partial class EmailOptions { public const string SectionName = "Email"; diff --git a/sample/Atc.SourceGenerators.OptionsBinding/Options/DatabaseOptions.cs b/sample/Atc.SourceGenerators.OptionsBinding/Options/DatabaseOptions.cs index 42058c8..579afb7 100644 --- a/sample/Atc.SourceGenerators.OptionsBinding/Options/DatabaseOptions.cs +++ b/sample/Atc.SourceGenerators.OptionsBinding/Options/DatabaseOptions.cs @@ -1,3 +1,4 @@ +// ReSharper disable CommentTypo namespace Atc.SourceGenerators.OptionsBinding.Options; /// diff --git a/sample/Atc.SourceGenerators.OptionsBinding/Options/EmailOptions.cs b/sample/Atc.SourceGenerators.OptionsBinding/Options/EmailOptions.cs index 2e08591..f872d07 100644 --- a/sample/Atc.SourceGenerators.OptionsBinding/Options/EmailOptions.cs +++ b/sample/Atc.SourceGenerators.OptionsBinding/Options/EmailOptions.cs @@ -12,7 +12,7 @@ namespace Atc.SourceGenerators.OptionsBinding.Options; /// [OptionsBinding("Email:Secondary", Name = "Secondary")] /// [OptionsBinding("Email:Fallback", Name = "Fallback")] /// -[OptionsBinding("Email", ChildSections = new[] { "Primary", "Secondary", "Fallback" }, ConfigureAll = nameof(SetDefaults))] +[OptionsBinding("Email", ChildSections = ["Primary", "Secondary", "Fallback"], ConfigureAll = nameof(SetDefaults))] public partial class EmailOptions { /// diff --git a/sample/Atc.SourceGenerators.OptionsBinding/Options/LoggingOptions.cs b/sample/Atc.SourceGenerators.OptionsBinding/Options/LoggingOptions.cs index 07852d0..fbe5dab 100644 --- a/sample/Atc.SourceGenerators.OptionsBinding/Options/LoggingOptions.cs +++ b/sample/Atc.SourceGenerators.OptionsBinding/Options/LoggingOptions.cs @@ -1,3 +1,4 @@ +// ReSharper disable CommentTypo namespace Atc.SourceGenerators.OptionsBinding.Options; /// @@ -24,7 +25,7 @@ internal static void OnLoggingChanged( LoggingOptions options, string? name) { - Console.WriteLine($"[OnChange Callback] Logging configuration changed:"); + Console.WriteLine("[OnChange Callback] Logging configuration changed:"); Console.WriteLine($" Level: {options.Level}"); Console.WriteLine($" EnableConsole: {options.EnableConsole}"); Console.WriteLine($" EnableFile: {options.EnableFile}"); diff --git a/sample/Atc.SourceGenerators.OptionsBinding/Program.cs b/sample/Atc.SourceGenerators.OptionsBinding/Program.cs index 1b1bda0..8eecb73 100644 --- a/sample/Atc.SourceGenerators.OptionsBinding/Program.cs +++ b/sample/Atc.SourceGenerators.OptionsBinding/Program.cs @@ -1,3 +1,4 @@ +// ReSharper disable StringLiteralTypo Console.WriteLine("=== Atc.SourceGenerators - Options Binding Sample ===\n"); // Build configuration @@ -14,6 +15,92 @@ services.AddOptionsFromOptionsBinding(configuration); services.AddOptionsFromDomain(configuration); +Console.WriteLine("=== Demonstrating Early Access to Options (No BuildServiceProvider!) ===\n"); +Console.WriteLine("Early access allows retrieving bound and validated options DURING service registration"); +Console.WriteLine("This avoids the anti-pattern of calling BuildServiceProvider() mid-registration.\n"); + +// Approach 1: Using GetOrAdd{OptionsName}From{Assembly}() methods +Console.WriteLine("1. Using GetOrAdd methods (Approach 1):"); +var dbEarly = services.GetOrAddDatabaseOptionsFromOptionsBinding(configuration); +Console.WriteLine($" ✓ Retrieved DatabaseOptions early: ConnectionString={dbEarly.ConnectionString[..Math.Min(30, dbEarly.ConnectionString.Length)]}..."); +Console.WriteLine($" ✓ MaxRetries: {dbEarly.MaxRetries}"); + +// Call again to demonstrate idempotency +var dbEarly2 = services.GetOrAddDatabaseOptionsFromOptionsBinding(configuration); +Console.WriteLine($" ✓ Called again (idempotent): Same instance? {ReferenceEquals(dbEarly, dbEarly2)}"); + +// Approach 2: GetOrAdd methods are idempotent - calling again retrieves from cache +Console.WriteLine("\n2. Retrieving other options via GetOrAdd (Approach 2):"); +var apiEarly = services.GetOrAddApiOptionsFromOptionsBinding(configuration); +Console.WriteLine($" ✓ Retrieved ApiOptions: BaseUrl={apiEarly.BaseUrl}"); + +var loggingEarly = services.GetOrAddLoggingOptionsFromOptionsBinding(configuration); +Console.WriteLine($" ✓ Retrieved LoggingOptions: Level={loggingEarly.Level}"); + +// Use case: Conditional service registration based on configuration +Console.WriteLine("\n3. Conditional Service Registration (Common Use Case):"); +Console.WriteLine(" Using early-access options to decide which services to register..."); + +if (loggingEarly.EnableFile && !string.IsNullOrWhiteSpace(loggingEarly.FilePath)) +{ + Console.WriteLine($" ✓ File logging enabled → Would register FileLoggerService with path: {loggingEarly.FilePath}"); + + //// Example: services.AddSingleton(new FileLogger(loggingEarly.FilePath)); +} +else +{ + Console.WriteLine(" ✗ File logging disabled → Skipping FileLoggerService registration"); +} + +if (dbEarly.MaxRetries > 0) +{ + Console.WriteLine($" ✓ Database retries enabled ({dbEarly.MaxRetries}) → Would register RetryPolicy service"); + + //// Example: services.AddSingleton(new RetryPolicy(dbEarly.MaxRetries)); +} + +// Demonstrate Get vs GetOrAdd +Console.WriteLine("\n4. Get vs GetOrAdd (Understanding Caching Behavior):"); +Console.WriteLine(" Three APIs available for early access to options:"); +Console.WriteLine(); + +Console.WriteLine(" A) Get methods - Reads cache but doesn't populate:"); +Console.WriteLine(" (Without GetOrAdd being called first)"); +var dbGet1 = services.GetDatabaseOptionsFromOptionsBinding(configuration); +var dbGet2 = services.GetDatabaseOptionsFromOptionsBinding(configuration); +Console.WriteLine($" ✓ First call: {dbGet1.ConnectionString[..Math.Min(30, dbGet1.ConnectionString.Length)]}..."); +Console.WriteLine($" ✓ Second call: {dbGet2.ConnectionString[..Math.Min(30, dbGet2.ConnectionString.Length)]}..."); +Console.WriteLine($" ✓ Same instance? {ReferenceEquals(dbGet1, dbGet2)} (no cache, creates fresh instances)"); +Console.WriteLine(); + +Console.WriteLine(" B) GetOrAdd methods - Reads AND populates cache:"); +var apiCached1 = services.GetOrAddApiOptionsFromOptionsBinding(configuration); +var apiCached2 = services.GetOrAddApiOptionsFromOptionsBinding(configuration); +Console.WriteLine($" ✓ First call: {apiCached1.BaseUrl}"); +Console.WriteLine($" ✓ Second call: {apiCached2.BaseUrl}"); +Console.WriteLine($" ✓ Same instance? {ReferenceEquals(apiCached1, apiCached2)} (cached and reused)"); +Console.WriteLine(); + +Console.WriteLine(" C) Get AFTER GetOrAdd - Benefits from cache:"); +var apiFromGet = services.GetApiOptionsFromOptionsBinding(configuration); +Console.WriteLine($" ✓ Get called after GetOrAdd: {apiFromGet.BaseUrl}"); +Console.WriteLine($" ✓ Same as cached? {ReferenceEquals(apiFromGet, apiCached1)} (Get found it in cache!)"); +Console.WriteLine(); + +Console.WriteLine(" D) Smart Dispatcher GetOptions() - Uses Get internally:"); +var apiDispatch = services.GetOptions(configuration); +Console.WriteLine($" ✓ GetOptions() → GetApiOptionsFromOptionsBinding()"); +Console.WriteLine($" ✓ Retrieved: {apiDispatch.BaseUrl}"); +Console.WriteLine($" ✓ Same as cached? {ReferenceEquals(apiDispatch, apiCached1)} (also benefits from cache!)"); +Console.WriteLine(); + +Console.WriteLine(" Summary:"); +Console.WriteLine(" - Get: Reads cache (efficient), doesn't populate (no side effects)"); +Console.WriteLine(" - GetOrAdd: Reads AND populates cache (use for idempotency)"); +Console.WriteLine(" - GetOptions: Convenient generic API, same behavior as Get"); + +Console.WriteLine("\n=== Early Access Complete! Now building ServiceProvider for normal usage ===\n"); + // Build service provider var serviceProvider = services.BuildServiceProvider(); @@ -97,7 +184,7 @@ var cloudStorage = cloudStorageOptions.Value; Console.WriteLine($" ✓ Provider: {cloudStorage.Provider}"); -Console.WriteLine($" ✓ Azure.ConnectionString: {cloudStorage.Azure.ConnectionString.Substring(0, Math.Min(40, cloudStorage.Azure.ConnectionString.Length))}..."); +Console.WriteLine($" ✓ Azure.ConnectionString: {cloudStorage.Azure.ConnectionString[..Math.Min(40, cloudStorage.Azure.ConnectionString.Length)]}..."); Console.WriteLine($" ✓ Azure.ContainerName: {cloudStorage.Azure.ContainerName}"); Console.WriteLine($" ✓ Azure.Blob.MaxBlockSize: {cloudStorage.Azure.Blob.MaxBlockSize}"); Console.WriteLine($" ✓ RetryPolicy.MaxRetries: {cloudStorage.RetryPolicy.MaxRetries}"); diff --git a/sample/Atc.SourceGenerators.OptionsBinding/appsettings.json b/sample/Atc.SourceGenerators.OptionsBinding/appsettings.json index 6c3ee44..efce935 100644 --- a/sample/Atc.SourceGenerators.OptionsBinding/appsettings.json +++ b/sample/Atc.SourceGenerators.OptionsBinding/appsettings.json @@ -12,10 +12,10 @@ } }, "Logging": { - "Level": "Debug", "EnableConsole": true, "EnableFile": true, - "FilePath": "logs/app.log" + "FilePath": "logs/app.log", + "Level": "Debug" }, "Email": { "Primary": { diff --git a/src/Atc.SourceGenerators/Generators/OptionsBindingGenerator.cs b/src/Atc.SourceGenerators/Generators/OptionsBindingGenerator.cs index 06ef972..09f5f10 100644 --- a/src/Atc.SourceGenerators/Generators/OptionsBindingGenerator.cs +++ b/src/Atc.SourceGenerators/Generators/OptionsBindingGenerator.cs @@ -1,5 +1,7 @@ // ReSharper disable ConvertIfStatementToReturnStatement +// ReSharper disable ForeachCanBeConvertedToQueryUsingAnotherGetEnumerator // ReSharper disable ForeachCanBePartlyConvertedToQueryUsingAnotherGetEnumerator +// ReSharper disable StringLiteralTypo namespace Atc.SourceGenerators.Generators; /// @@ -228,8 +230,11 @@ private static void Execute( return; } - // Detect referenced assemblies with [OptionsBinding] attributes - var referencedAssemblies = GetReferencedAssembliesWithOptionsBinding(compilation); + // Generate OptionsInstanceCache only when there are options classes + context.AddSource("OptionsInstanceCache.g.cs", SourceText.From(GenerateOptionsInstanceCacheSource(), Encoding.UTF8)); + + // Detect referenced assemblies with [OptionsBinding] attributes and collect their options + var referencedAssemblies = GetReferencedAssembliesWithOptionsBinding(compilation, out var referencedAssemblyOptions); // Group by assembly var groupedByAssembly = optionsToGenerate @@ -238,7 +243,7 @@ private static void Execute( foreach (var assemblyGroup in groupedByAssembly) { - var source = GenerateExtensionMethod(assemblyGroup.Key, assemblyGroup.ToList(), referencedAssemblies); + var source = GenerateExtensionMethod(assemblyGroup.Key, assemblyGroup.ToList(), referencedAssemblies, referencedAssemblyOptions); context.AddSource($"OptionsBindingExtensions.{SanitizeForMethodName(assemblyGroup.Key)}.g.cs", SourceText.From(source, Encoding.UTF8)); } } @@ -767,9 +772,11 @@ private static string GetAssemblyPrefix(string assemblyName) } private static ImmutableArray GetReferencedAssembliesWithOptionsBinding( - Compilation compilation) + Compilation compilation, + out Dictionary> referencedAssemblyOptions) { var result = new List(); + referencedAssemblyOptions = new Dictionary>(StringComparer.Ordinal); var prefix = GetAssemblyPrefix(compilation.AssemblyName!); var visited = new HashSet(StringComparer.Ordinal) { compilation.AssemblyName! }; var queue = new Queue(); @@ -802,6 +809,13 @@ private static ImmutableArray GetReferencedAssembliesWit assemblyName, SanitizeForMethodName(assemblyName), assemblyName.Substring(assemblyName.LastIndexOf('.') + 1))); + + // Collect options from this referenced assembly + var options = CollectOptionsFromAssembly(assemblySymbol); + if (options.Count > 0) + { + referencedAssemblyOptions[assemblyName] = options; + } } // Enqueue referenced assemblies for recursive traversal @@ -819,20 +833,146 @@ private static ImmutableArray GetReferencedAssembliesWit } } - return [..result]; + return [.. result]; + } + + private static List CollectOptionsFromAssembly( + IAssemblySymbol assemblySymbol) + { + var result = new List(); + var stack = new Stack(); + stack.Push(assemblySymbol.GlobalNamespace); + + while (stack.Count > 0) + { + var currentNamespace = stack.Pop(); + + // Process types in this namespace + foreach (var typeMember in currentNamespace.GetTypeMembers()) + { + if (typeMember is not INamedTypeSymbol { TypeKind: TypeKind.Class } namedType) + { + continue; + } + + // Check if type has OptionsBinding attribute + var optionsAttributes = namedType + .GetAttributes() + .Where(a => a.AttributeClass?.ToDisplayString() == FullAttributeName) + .ToList(); + + if (optionsAttributes.Count <= 0) + { + continue; + } + + // Extract basic info for dispatcher (no validation needed) + foreach (var attribute in optionsAttributes) + { + var optionsInfo = ExtractBasicOptionsInfo(namedType, attribute); + if (optionsInfo is not null) + { + result.Add(optionsInfo); + } + } + } + + // Process nested namespaces + foreach (var nestedNamespace in currentNamespace.GetNamespaceMembers()) + { + stack.Push(nestedNamespace); + } + } + + return result; + } + + private static OptionsInfo? ExtractBasicOptionsInfo( + INamedTypeSymbol namedType, + AttributeData attribute) + { + // Extract only the essential information needed for dispatcher + var className = namedType.Name; + var namespaceName = namedType.ContainingNamespace.ToDisplayString(); + var assemblyName = namedType.ContainingAssembly.Name; + + // Check if this is a named option (has Name property set) + string? nameValue = null; + foreach (var namedArg in attribute.NamedArguments) + { + if (namedArg.Key == "Name") + { + nameValue = namedArg.Value.Value as string; + break; + } + } + + if (!string.IsNullOrWhiteSpace(nameValue)) + { + // Skip named options - dispatcher only works with unnamed options + return null; + } + + // Create minimal OptionsInfo for dispatcher + return new OptionsInfo( + className, + namespaceName, + assemblyName, + SectionName: string.Empty, // Not needed for dispatcher + ValidateDataAnnotations: false, + ValidateOnStart: false, + ErrorOnMissingKeys: false, + ValidatorType: null, + Lifetime: 0, + OnChange: null, + PostConfigure: null, + ConfigureAll: null, + Name: null, + ChildSections: null, + AlsoRegisterDirectType: false); } private static bool HasOptionsBindingAttributeInNamespace( IAssemblySymbol assemblySymbol) - => assemblySymbol - .GlobalNamespace - .GetNamespaceMembers() - .Any(ns => ns.ToDisplayString() == AttributeNamespace); + { + // Check if any types in the assembly have the [OptionsBinding] attribute + var stack = new Stack(); + stack.Push(assemblySymbol.GlobalNamespace); + + while (stack.Count > 0) + { + var currentNamespace = stack.Pop(); + + // Check types in this namespace + foreach (var typeMember in currentNamespace.GetTypeMembers()) + { + if (typeMember is not INamedTypeSymbol { TypeKind: TypeKind.Class } namedType) + { + continue; + } + + // Check if type has OptionsBinding attribute + if (namedType.GetAttributes().Any(a => a.AttributeClass?.ToDisplayString() == FullAttributeName)) + { + return true; + } + } + + // Check nested namespaces + foreach (var nestedNamespace in currentNamespace.GetNamespaceMembers()) + { + stack.Push(nestedNamespace); + } + } + + return false; + } private static string GenerateExtensionMethod( string assemblyName, List options, - ImmutableArray referencedAssemblies) + ImmutableArray referencedAssemblies, + Dictionary> referencedAssemblyOptions) { var sb = new StringBuilder(); var methodSuffix = GetSmartMethodSuffix(assemblyName, referencedAssemblies); @@ -844,12 +984,12 @@ private static string GenerateExtensionMethod( using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection; -namespace Atc.DependencyInjection; +namespace Microsoft.Extensions.DependencyInjection; /// /// Extension methods for configuring options from the {{assemblyName}} assembly. /// -public static class OptionsBindingExtensions +public static class OptionsBindingExtensions{{methodSuffix}} { /// /// Adds and configures options from the {{assemblyName}} assembly. @@ -888,7 +1028,7 @@ public static class OptionsBindingExtensions foreach (var option in options) { - GenerateOptionsRegistration(sb, option); + GenerateOptionsRegistration(sb, option, methodSuffix); } sb.AppendLine(""" @@ -928,7 +1068,7 @@ public static class OptionsBindingExtensions foreach (var refAssembly in referencedAssemblies) { var refSmartSuffix = GetSmartMethodSuffixFromContext(refAssembly.AssemblyName, allAssemblies); - sb.AppendLine($" AddOptionsFrom{refSmartSuffix}(services, configuration, includeReferencedAssemblies: true);"); + sb.AppendLine($" services.AddOptionsFrom{refSmartSuffix}(configuration, includeReferencedAssemblies: true);"); } sb.AppendLine(" }"); @@ -969,7 +1109,7 @@ public static class OptionsBindingExtensions var refSmartSuffix = GetSmartMethodSuffixFromContext(refAssembly.AssemblyName, allAssemblies); sb.AppendLine($" case \"{refAssembly.AssemblyName}\":"); sb.AppendLine($" case \"{refAssembly.ShortName}\":"); - sb.AppendLine($" AddOptionsFrom{refSmartSuffix}(services, configuration, includeReferencedAssemblies: true);"); + sb.AppendLine($" services.AddOptionsFrom{refSmartSuffix}(configuration, includeReferencedAssemblies: true);"); sb.AppendLine(" break;"); } @@ -1008,6 +1148,56 @@ public static class OptionsBindingExtensions } """); + // Generate early access GetOrAdd methods for unnamed options only + var unnamedOptions = options + .Where(o => string.IsNullOrWhiteSpace(o.Name)) + .ToList(); + if (unnamedOptions.Count > 0) + { + sb.AppendLine(); + sb.AppendLineLf(" // ========== Early Access Methods (Avoid BuildServiceProvider Anti-Pattern) =========="); + sb.AppendLine(); + + foreach (var option in unnamedOptions) + { + GenerateGetMethod(sb, option, methodSuffix); + GenerateGetOrAddMethod(sb, option, methodSuffix); + } + + // Generate smart dispatcher generic GetOptions() method + // ONLY in assemblies that have referenced assemblies with OptionsBinding + // This prevents CS0121 ambiguity by ensuring only the consuming assembly has the dispatcher + if (referencedAssemblies.Length > 0) + { + sb.AppendLine(); + sb.AppendLineLf(" // ========== Generic Convenience Method (Smart Dispatcher) =========="); + sb.AppendLineLf(" // This method intelligently dispatches to the correct assembly-specific method"); + sb.AppendLineLf(" // based on the type parameter, avoiding CS0121 ambiguity errors."); + sb.AppendLineLf(" // Includes options from current and referenced assemblies."); + sb.AppendLine(); + + GenerateGenericGetOptionsMethod(sb, unnamedOptions, methodSuffix, referencedAssemblies, referencedAssemblyOptions); + } + else + { + sb.AppendLine(); + sb.AppendLineLf(" // ========== Generic Method Not Generated =========="); + sb.AppendLineLf(" // GetOptions() is not generated in library assemblies without references."); + sb.AppendLineLf(" // It will be generated in consuming assemblies that reference this library."); + sb.AppendLineLf(" // Use assembly-specific methods:"); + foreach (var option in unnamedOptions) + { + sb.Append(" // - GetOrAdd"); + sb.Append(option.ClassName); + sb.Append("From"); + sb.Append(methodSuffix); + sb.AppendLineLf("()"); + } + + sb.AppendLine(); + } + } + // Generate hosted service classes for OnChange callbacks foreach (var option in options.Where(o => !string.IsNullOrWhiteSpace(o.OnChange))) { @@ -1022,7 +1212,8 @@ public static class OptionsBindingExtensions private static void GenerateOptionsRegistration( StringBuilder sb, - OptionsInfo option) + OptionsInfo option, + string methodSuffix) { var optionsType = $"global::{option.Namespace}.{option.ClassName}"; var sectionName = option.SectionName; @@ -1058,14 +1249,9 @@ private static void GenerateOptionsRegistration( else { // Use fluent API pattern (supports both named and unnamed options) - if (isNamed) - { - sb.AppendLineLf($" // Configure {option.ClassName} (Named: \"{option.Name}\") - Inject using IOptionsSnapshot.Get(\"{option.Name}\")"); - } - else - { - sb.AppendLineLf($" // Configure {option.ClassName} - Inject using {lifetimeComment}"); - } + sb.AppendLineLf(isNamed + ? $" // Configure {option.ClassName} (Named: \"{option.Name}\") - Inject using IOptionsSnapshot.Get(\"{option.Name}\")" + : $" // Configure {option.ClassName} - Inject using {lifetimeComment}"); sb.Append(" services.AddOptions<"); sb.Append(optionsType); @@ -1096,9 +1282,9 @@ private static void GenerateOptionsRegistration( sb.AppendLineLf($" var section = configuration.GetSection(\"{sectionName}\");"); sb.AppendLineLf(" if (!section.Exists())"); sb.AppendLineLf(" {"); - sb.AppendLineLf($" throw new global::System.InvalidOperationException("); + sb.AppendLineLf(" throw new global::System.InvalidOperationException("); sb.AppendLineLf($" \"Configuration section '{sectionName}' is missing. \" +"); - sb.AppendLineLf($" \"Ensure the section exists in your appsettings.json or other configuration sources.\");"); + sb.AppendLineLf(" \"Ensure the section exists in your appsettings.json or other configuration sources.\");"); sb.AppendLineLf(" }"); sb.AppendLineLf(); sb.AppendLineLf(" return true;"); @@ -1115,12 +1301,27 @@ private static void GenerateOptionsRegistration( sb.Append("(options))"); } + // For unnamed options, add to shared cache for early access via GetOptionInstanceOf() + if (!isNamed) + { + sb.AppendLineLf(); + sb.Append(" .PostConfigure(options =>"); + sb.AppendLineLf(); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" // Add to shared cache for early access"); + sb.Append(" global::Atc.OptionsBinding.OptionsInstanceCache.Add(options, \""); + sb.Append(methodSuffix); + sb.AppendLineLf("\");"); + sb.Append(" })"); + } + if (option.ValidateOnStart) { sb.AppendLineLf(); sb.Append(" .ValidateOnStart()"); } + // Semicolon on same line as last method call sb.AppendLineLf(";"); // Register OnChange callback listener if specified (only for unnamed options with Monitor lifetime) @@ -1230,6 +1431,343 @@ private static void GenerateOnChangeHostedService( sb.AppendLineLf("}"); } + private static void GenerateGetMethod( + StringBuilder sb, + OptionsInfo option, + string methodSuffix) + { + var optionsType = $"global::{option.Namespace}.{option.ClassName}"; + var sectionName = option.SectionName; + + sb.AppendLine(); + sb.AppendLine(" /// "); + sb.Append(" /// Gets an instance of "); + sb.Append(option.ClassName); + sb.AppendLineLf(" with configuration binding."); + sb.AppendLineLf(" /// If an instance was previously cached by GetOrAdd, returns that instance."); + sb.AppendLineLf(" /// Otherwise, creates a new instance without adding it to the cache."); + sb.AppendLineLf(" /// This method does not populate the cache (no side effects), but benefits from existing cached values."); + sb.AppendLineLf(" /// For caching behavior, use GetOrAdd instead."); + sb.AppendLineLf(" /// "); + sb.AppendLineLf(" /// The service collection (used for extension method chaining)."); + sb.AppendLineLf(" /// The configuration instance."); + sb.Append(" /// A bound and validated "); + sb.Append(option.ClassName); + sb.AppendLineLf(" instance."); + sb.Append(" public static "); + sb.Append(optionsType); + sb.Append(" Get"); + sb.Append(option.ClassName); + sb.Append("From"); + sb.AppendLineLf(methodSuffix); + sb.AppendLineLf(" (this global::Microsoft.Extensions.DependencyInjection.IServiceCollection services,"); + sb.AppendLineLf(" global::Microsoft.Extensions.Configuration.IConfiguration configuration)"); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" // Check cache first (read-only, no side effects)"); + sb.Append(" var cached = global::Atc.OptionsBinding.OptionsInstanceCache.TryGet<"); + sb.Append(optionsType); + sb.AppendLineLf(">();"); + sb.AppendLineLf(" if (cached is not null)"); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" return cached;"); + sb.AppendLineLf(" }"); + sb.AppendLineLf(); + sb.AppendLineLf(" // Create and bind instance (not cached)"); + sb.Append(" var options = new "); + sb.Append(optionsType); + sb.AppendLineLf("();"); + sb.Append(" var section = configuration.GetSection(\""); + sb.Append(sectionName); + sb.AppendLineLf("\");"); + sb.AppendLineLf(" section.Bind(options);"); + sb.AppendLineLf(); + + // Add ErrorOnMissingKeys validation if specified + if (option.ErrorOnMissingKeys) + { + sb.AppendLineLf(" // Validate section exists (ErrorOnMissingKeys)"); + sb.AppendLineLf(" if (!section.Exists())"); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" throw new global::System.InvalidOperationException("); + sb.Append(" \"Configuration section '"); + sb.Append(sectionName); + sb.AppendLineLf("' is missing. \" +"); + sb.AppendLineLf(" \"Ensure the section exists in your appsettings.json or other configuration sources.\");"); + sb.AppendLineLf(" }"); + sb.AppendLineLf(); + } + + // Add DataAnnotations validation if specified + if (option.ValidateDataAnnotations) + { + sb.AppendLineLf(" // Validate immediately (DataAnnotations)"); + sb.AppendLineLf(" var validationContext = new global::System.ComponentModel.DataAnnotations.ValidationContext(options);"); + sb.AppendLineLf(" global::System.ComponentModel.DataAnnotations.Validator.ValidateObject(options, validationContext, validateAllProperties: true);"); + sb.AppendLineLf(); + } + + // Apply PostConfigure if specified + if (!string.IsNullOrWhiteSpace(option.PostConfigure)) + { + sb.AppendLineLf(" // Apply post-configuration"); + sb.Append(" "); + sb.Append(optionsType); + sb.Append('.'); + sb.Append(option.PostConfigure); + sb.AppendLineLf("(options);"); + sb.AppendLineLf(); + } + + // Register custom validator if specified (even for non-cached Get) + if (!string.IsNullOrWhiteSpace(option.ValidatorType)) + { + sb.AppendLineLf(" // Register custom validator"); + sb.Append(" services.AddSingleton, "); + sb.Append(option.ValidatorType); + sb.AppendLineLf(">();"); + sb.AppendLineLf(); + } + + sb.AppendLineLf(" return options;"); + sb.AppendLineLf(" }"); + } + + private static void GenerateGetOrAddMethod( + StringBuilder sb, + OptionsInfo option, + string methodSuffix) + { + var optionsType = $"global::{option.Namespace}.{option.ClassName}"; + var sectionName = option.SectionName; + + sb.AppendLine(); + sb.AppendLine(" /// "); + sb.Append(" /// Gets or creates a cached instance of "); + sb.Append(option.ClassName); + sb.AppendLineLf(" with configuration binding for early access."); + sb.AppendLineLf(" /// If already cached, returns the existing instance. Otherwise, creates, binds, validates, and caches the instance."); + sb.AppendLineLf(" /// This method is idempotent and safe to call multiple times."); + sb.AppendLineLf(" /// This method enables early access to options during service registration without calling BuildServiceProvider()."); + sb.AppendLineLf(" /// Note: This method is called on-demand when you need early access, not automatically by AddOptionsFrom."); + sb.AppendLineLf(" /// "); + sb.AppendLineLf(" /// The service collection (used for extension method chaining)."); + sb.AppendLineLf(" /// The configuration instance."); + sb.Append(" /// The bound and validated "); + sb.Append(option.ClassName); + sb.AppendLineLf(" instance for immediate use during service registration."); + sb.Append(" public static "); + sb.Append(optionsType); + sb.Append(" GetOrAdd"); + sb.Append(option.ClassName); + sb.Append("From"); + sb.AppendLineLf(methodSuffix); + sb.AppendLineLf(" (this global::Microsoft.Extensions.DependencyInjection.IServiceCollection services,"); + sb.AppendLineLf(" global::Microsoft.Extensions.Configuration.IConfiguration configuration)"); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" // Check if already registered (idempotent)"); + sb.Append(" var existing = global::Atc.OptionsBinding.OptionsInstanceCache.TryGet<"); + sb.Append(optionsType); + sb.AppendLineLf(">();"); + sb.AppendLineLf(" if (existing is not null)"); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" return existing;"); + sb.AppendLineLf(" }"); + sb.AppendLineLf(); + sb.AppendLineLf(" // Create and bind instance"); + sb.Append(" var options = new "); + sb.Append(optionsType); + sb.AppendLineLf("();"); + sb.Append(" var section = configuration.GetSection(\""); + sb.Append(sectionName); + sb.AppendLineLf("\");"); + sb.AppendLineLf(" section.Bind(options);"); + sb.AppendLineLf(); + + // Add ErrorOnMissingKeys validation if specified + if (option.ErrorOnMissingKeys) + { + sb.AppendLineLf(" // Validate section exists (ErrorOnMissingKeys)"); + sb.AppendLineLf(" if (!section.Exists())"); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" throw new global::System.InvalidOperationException("); + sb.Append(" \"Configuration section '"); + sb.Append(sectionName); + sb.AppendLineLf("' is missing. \" +"); + sb.AppendLineLf(" \"Ensure the section exists in your appsettings.json or other configuration sources.\");"); + sb.AppendLineLf(" }"); + sb.AppendLineLf(); + } + + // Add DataAnnotations validation if specified + if (option.ValidateDataAnnotations) + { + sb.AppendLineLf(" // Validate immediately (DataAnnotations)"); + sb.AppendLineLf(" var validationContext = new global::System.ComponentModel.DataAnnotations.ValidationContext(options);"); + sb.AppendLineLf(" global::System.ComponentModel.DataAnnotations.Validator.ValidateObject(options, validationContext, validateAllProperties: true);"); + sb.AppendLineLf(); + } + + // Apply PostConfigure if specified + if (!string.IsNullOrWhiteSpace(option.PostConfigure)) + { + sb.AppendLineLf(" // Apply post-configuration"); + sb.Append(" "); + sb.Append(optionsType); + sb.Append('.'); + sb.Append(option.PostConfigure); + sb.AppendLineLf("(options);"); + sb.AppendLineLf(); + } + + sb.AppendLineLf(" // Add to shared cache for early access and smart dispatcher"); + sb.Append(" global::Atc.OptionsBinding.OptionsInstanceCache.Add(options, \""); + sb.Append(methodSuffix); + sb.AppendLineLf("\");"); + sb.AppendLineLf(); + + // Register custom validator if specified + if (!string.IsNullOrWhiteSpace(option.ValidatorType)) + { + sb.AppendLineLf(" // Register custom validator"); + sb.Append(" services.AddSingleton, "); + sb.Append(option.ValidatorType); + sb.AppendLineLf(">();"); + sb.AppendLineLf(); + } + + sb.AppendLineLf(" return options;"); + sb.AppendLineLf(" }"); + } + + private static void GenerateGenericGetOptionsMethod( + StringBuilder sb, + List currentAssemblyOptions, + string currentAssemblySuffix, + ImmutableArray referencedAssemblies, + Dictionary> referencedAssemblyOptions) + { + // Build context for smart suffix calculation + var allAssemblies = new List(); + foreach (var refAsm in referencedAssemblies) + { + allAssemblies.Add(refAsm.AssemblyName); + } + + // Collect all available options for error message + var allOptionsTypes = new List(); + foreach (var option in currentAssemblyOptions) + { + allOptionsTypes.Add($"global::{option.Namespace}.{option.ClassName}"); + } + + foreach (var refAssembly in referencedAssemblies) + { + if (referencedAssemblyOptions.TryGetValue(refAssembly.AssemblyName, out var refOptions)) + { + foreach (var option in refOptions) + { + allOptionsTypes.Add($"global::{option.Namespace}.{option.ClassName}"); + } + } + } + + sb.AppendLine(); + sb.AppendLineLf(" /// "); + sb.AppendLineLf(" /// Gets options of the specified type, intelligently dispatching to the correct"); + sb.AppendLineLf(" /// assembly-specific method based on the type parameter."); + sb.AppendLineLf(" /// This smart dispatcher eliminates CS0121 ambiguity errors in multi-assembly scenarios"); + sb.AppendLineLf(" /// by routing to the appropriate Get{OptionsName}From{Assembly}() method."); + sb.AppendLineLf(" /// Note: This method calls the pure Get methods (no caching side effects)."); + sb.AppendLineLf(" /// "); + sb.AppendLineLf(" /// The options type."); + sb.AppendLineLf(" /// The service collection."); + sb.AppendLineLf(" /// The configuration instance."); + sb.AppendLineLf(" /// The bound and validated options instance."); + sb.AppendLineLf(" /// Thrown when type T is not a registered options type."); + sb.AppendLineLf(" public static T GetOptions("); + sb.AppendLineLf(" this global::Microsoft.Extensions.DependencyInjection.IServiceCollection services,"); + sb.AppendLineLf(" global::Microsoft.Extensions.Configuration.IConfiguration configuration)"); + sb.AppendLineLf(" where T : class"); + sb.AppendLineLf(" {"); + sb.AppendLineLf(" var type = typeof(T);"); + sb.AppendLineLf(); + + // Generate type dispatch for current assembly options + if (currentAssemblyOptions.Count > 0) + { + sb.AppendLineLf(" // Current assembly options"); + foreach (var option in currentAssemblyOptions) + { + var optionsType = $"global::{option.Namespace}.{option.ClassName}"; + sb.Append(" if (type == typeof("); + sb.Append(optionsType); + sb.AppendLineLf("))"); + sb.Append(" return (T)(object)services.Get"); + sb.Append(option.ClassName); + sb.Append("From"); + sb.Append(currentAssemblySuffix); + sb.AppendLineLf("(configuration);"); + sb.AppendLineLf(); + } + } + + // Generate type dispatch for referenced assembly options + if (referencedAssemblies.Length > 0) + { + sb.AppendLineLf(" // Referenced assembly options"); + foreach (var refAssembly in referencedAssemblies) + { + if (referencedAssemblyOptions.TryGetValue(refAssembly.AssemblyName, out var refOptions)) + { + // Get smart suffix for this referenced assembly + var refMethodSuffix = GetSmartMethodSuffixFromContext(refAssembly.AssemblyName, allAssemblies); + + foreach (var option in refOptions) + { + var optionsType = $"global::{option.Namespace}.{option.ClassName}"; + sb.Append(" if (type == typeof("); + sb.Append(optionsType); + sb.AppendLineLf("))"); + sb.Append(" return (T)(object)services.Get"); + sb.Append(option.ClassName); + sb.Append("From"); + sb.Append(refMethodSuffix); + sb.AppendLineLf("(configuration);"); + sb.AppendLineLf(); + } + } + } + } + + // Generate error for unrecognized types + sb.AppendLineLf(" // Type not recognized - generate helpful error message"); + sb.AppendLineLf(" var availableTypes = new[]"); + sb.AppendLineLf(" {"); + for (int i = 0; i < allOptionsTypes.Count; i++) + { + sb.Append(" \""); + sb.Append(allOptionsTypes[i]); + sb.Append('"'); + if (i < allOptionsTypes.Count - 1) + { + sb.Append(','); + } + + sb.AppendLineLf(); + } + + sb.AppendLineLf(" };"); + sb.AppendLineLf(); + sb.AppendLineLf(" throw new global::System.InvalidOperationException("); + sb.AppendLineLf(" $\"Type '{type.FullName}' is not a registered options type. \" +"); + sb.AppendLineLf(" $\"Available types: {string.Join(\", \", availableTypes.Select(t => t.Split('.').Last()))}\");"); + sb.AppendLineLf(" }"); + } + private static string SanitizeForMethodName(string assemblyName) { var sb = new StringBuilder(); @@ -1298,7 +1836,7 @@ private static string GetSmartMethodSuffixFromContext( return SanitizeForMethodName(suffix); } - // Multiple assemblies have this suffix, use full sanitized name to avoid conflicts + // Multiple assemblies have this suffix, useful sanitized name to avoid conflicts return SanitizeForMethodName(assemblyName); } @@ -1485,4 +2023,84 @@ public OptionsBindingAttribute(string? sectionName = null) } } """; + + private static string GenerateOptionsInstanceCacheSource() + => """ + // + #nullable enable + + namespace Atc.OptionsBinding + { + using System.Collections.Concurrent; + using System.Collections.Generic; + using System.Linq; + + /// + /// Internal cache for storing option instances for early access during service registration. + /// This allows retrieving bound and validated options instances without calling BuildServiceProvider(). + /// + [global::System.CodeDom.Compiler.GeneratedCode("Atc.SourceGenerators.OptionsBinding", "1.0.0")] + [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)] + [global::System.Diagnostics.DebuggerNonUserCode] + [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage] + internal static class OptionsInstanceCache + { + private static readonly ConcurrentDictionary> instances = new(); + private static readonly object lockObject = new(); + + /// + /// Adds an options instance to the cache with assembly metadata. + /// + internal static void Add(T instance, string assemblyName) where T : class + { + lock (lockObject) + { + var type = typeof(T); + if (!instances.TryGetValue(type, out var list)) + { + list = new global::System.Collections.Generic.List<(object, string)>(); + instances[type] = list; + } + + // Check if already registered from this assembly (idempotency) + var existing = list.FirstOrDefault(x => x.AssemblyName == assemblyName); + if (existing.Instance != null) + { + // Already registered from this assembly - skip + return; + } + + list.Add((instance, assemblyName)); + } + } + + /// + /// Tries to get an options instance from the cache (returns first match if multiple). + /// + internal static T? TryGet() where T : class + { + if (instances.TryGetValue(typeof(T), out var list) && list.Count > 0) + { + return (T)list[0].Instance; + } + + return null; + } + + /// + /// Finds all registrations for a given type across all assemblies. + /// + internal static global::System.Collections.Generic.List<(object Instance, string AssemblyName)> FindAll() where T : class + { + if (instances.TryGetValue(typeof(T), out var list)) + { + return new global::System.Collections.Generic.List<(object Instance, string AssemblyName)>(list); + } + + return new global::System.Collections.Generic.List<(object Instance, string AssemblyName)>(); + } + } + } + + """; } \ No newline at end of file diff --git a/src/Atc.SourceGenerators/RuleIdentifierConstants.cs b/src/Atc.SourceGenerators/RuleIdentifierConstants.cs index 45fa58f..3c287c7 100644 --- a/src/Atc.SourceGenerators/RuleIdentifierConstants.cs +++ b/src/Atc.SourceGenerators/RuleIdentifierConstants.cs @@ -146,6 +146,16 @@ internal static class OptionsBinding /// ATCOPT016: ChildSections items cannot be null or empty. /// internal const string ChildSectionsItemsCannotBeNullOrEmpty = "ATCOPT016"; + + /// + /// ATCOPT017: Early access not supported with named options. + /// + internal const string EarlyAccessNotSupportedWithNamedOptions = "ATCOPT017"; + + /// + /// ATCOPT018: Early access uses Singleton lifetime (informational). + /// + internal const string EarlyAccessUsesSingletonLifetime = "ATCOPT018"; } /// diff --git a/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorBasicTests.cs b/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorBasicTests.cs index 42675ef..acd45ec 100644 --- a/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorBasicTests.cs +++ b/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorBasicTests.cs @@ -152,7 +152,7 @@ public partial class DatabaseOptions } [Fact] - public void Generator_Should_Use_Atc_DependencyInjection_Namespace_For_Extension_Method() + public void Generator_Should_Use_Microsoft_Extensions_DependencyInjection_Namespace_For_Extension_Method() { // Arrange const string source = """ @@ -175,6 +175,6 @@ public partial class DatabaseOptions var generatedCode = GetGeneratedExtensionMethod(output); Assert.NotNull(generatedCode); - Assert.Contains("namespace Atc.DependencyInjection", generatedCode, StringComparison.Ordinal); + Assert.Contains("namespace Microsoft.Extensions.DependencyInjection", generatedCode, StringComparison.Ordinal); } } \ No newline at end of file diff --git a/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorEarlyAccessTests.cs b/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorEarlyAccessTests.cs new file mode 100644 index 0000000..187e65c --- /dev/null +++ b/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorEarlyAccessTests.cs @@ -0,0 +1,670 @@ +// ReSharper disable RedundantArgumentDefaultValue +// ReSharper disable UnusedVariable +// ReSharper disable ForeachCanBePartlyConvertedToQueryUsingAnotherGetEnumerator +namespace Atc.SourceGenerators.Tests.Generators.OptionsBinding; + +public partial class OptionsBindingGeneratorTests +{ + [Fact] + public void Generator_Should_Generate_OptionsInstanceCache_Class() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + Assert.Contains("OptionsInstanceCache.g.cs", output.Keys, StringComparer.Ordinal); + Assert.Contains("class OptionsInstanceCache", output["OptionsInstanceCache.g.cs"], StringComparison.Ordinal); + Assert.Contains("namespace Atc.OptionsBinding", output["OptionsInstanceCache.g.cs"], StringComparison.Ordinal); + Assert.Contains("ConcurrentDictionary", output["OptionsInstanceCache.g.cs"], StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Generate_GetOrAdd_Method_For_Unnamed_Options() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + public int MaxRetries { get; set; } + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + Assert.Contains("GetOrAddDatabaseOptionsFromTestAssembly", generatedCode, StringComparison.Ordinal); + Assert.Contains("Early Access Methods", generatedCode, StringComparison.Ordinal); + Assert.Contains("If already cached, returns the existing instance", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Not_Generate_GetOrAdd_Method_For_Named_Options() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Email:Primary", Name = "Primary")] + [OptionsBinding("Email:Secondary", Name = "Secondary")] + public partial class EmailOptions + { + public string SmtpServer { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // Should NOT contain GetOrAdd methods for named options + Assert.DoesNotContain("GetOrAddEmailOptionsFromTestAssembly", generatedCode, StringComparison.Ordinal); + Assert.DoesNotContain("Early Access Methods", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Include_Idempotency_Check_In_GetOrAdd_Method() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + Assert.Contains("Check if already registered (idempotent)", generatedCode, StringComparison.Ordinal); + Assert.Contains("OptionsInstanceCache.TryGet", generatedCode, StringComparison.Ordinal); + Assert.Contains("if (existing is not null)", generatedCode, StringComparison.Ordinal); + Assert.Contains("return existing;", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Include_DataAnnotations_Validation_In_GetOrAdd_Method() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database", ValidateDataAnnotations = true)] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + Assert.Contains("Validate immediately (DataAnnotations)", generatedCode, StringComparison.Ordinal); + Assert.Contains("ValidationContext", generatedCode, StringComparison.Ordinal); + Assert.Contains("Validator.ValidateObject", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Include_ErrorOnMissingKeys_Check_In_GetOrAdd_Method() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database", ErrorOnMissingKeys = true)] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + Assert.Contains("Validate section exists (ErrorOnMissingKeys)", generatedCode, StringComparison.Ordinal); + Assert.Contains("if (!section.Exists())", generatedCode, StringComparison.Ordinal); + Assert.Contains("Configuration section 'Database' is missing", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Include_PostConfigure_Call_In_GetOrAdd_Method() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Storage", PostConfigure = nameof(NormalizePaths))] + public partial class StorageOptions + { + public string BasePath { get; set; } = string.Empty; + + internal static void NormalizePaths(StorageOptions options) + { + } + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + Assert.Contains("Apply post-configuration", generatedCode, StringComparison.Ordinal); + Assert.Contains("StorageOptions.NormalizePaths(options)", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Add_Cache_Population_In_AddOptionsFrom_Methods() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + Assert.Contains("Add to shared cache for early access", generatedCode, StringComparison.Ordinal); + Assert.Contains(".PostConfigure(options =>", generatedCode, StringComparison.Ordinal); + Assert.Contains("OptionsInstanceCache.Add(options, \"", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Not_Add_Cache_Population_For_Named_Options() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Email:Primary", Name = "Primary")] + public partial class EmailOptions + { + public string SmtpServer { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // Find the Configure section for the named option + var configureIndex = generatedCode.IndexOf("services.Configure(\"Primary\"", StringComparison.Ordinal); + Assert.NotEqual(-1, configureIndex); + + // Verify no cache population for named options + var nextConfigureIndex = generatedCode.IndexOf("services.", configureIndex + 1, StringComparison.Ordinal); + var sectionBetween = nextConfigureIndex == -1 + ? generatedCode.Substring(configureIndex) + : generatedCode.Substring(configureIndex, nextConfigureIndex - configureIndex); + + Assert.DoesNotContain("OptionsInstanceCache.Add", sectionBetween, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Populate_Cache_In_GetOrAdd_Method() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // GetOrAdd should only populate cache, not register with service collection + Assert.Contains("global::Atc.OptionsBinding.OptionsInstanceCache.Add", generatedCode, StringComparison.Ordinal); + + // Should NOT call services.Configure (that's done by AddOptionsFrom) + Assert.DoesNotContain("Copy all properties from pre-bound instance", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Generate_Get_Method_That_Checks_Cache_But_Does_Not_Populate() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // Get method should exist + Assert.Contains("public static global::MyApp.Configuration.DatabaseOptions GetDatabaseOptionsFromTestAssembly", generatedCode, StringComparison.Ordinal); + + // Get method should check cache (read-only) but not populate it + var getMethodStart = generatedCode.IndexOf("public static global::MyApp.Configuration.DatabaseOptions GetDatabaseOptionsFromTestAssembly", StringComparison.Ordinal); + var getOrAddMethodStart = generatedCode.IndexOf("public static global::MyApp.Configuration.DatabaseOptions GetOrAddDatabaseOptionsFromTestAssembly", StringComparison.Ordinal); + var getMethodCode = generatedCode.Substring(getMethodStart, getOrAddMethodStart - getMethodStart); + + // Verify Get method checks cache (read-only access) + Assert.Contains("OptionsInstanceCache.TryGet", getMethodCode, StringComparison.Ordinal); + + // Verify Get method does NOT populate cache (no side effects) + Assert.DoesNotContain("OptionsInstanceCache.Add", getMethodCode, StringComparison.Ordinal); + + // Verify it still binds and validates when not cached + Assert.Contains("section.Bind(options)", getMethodCode, StringComparison.Ordinal); + Assert.Contains("return options", getMethodCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Generate_Multiple_GetOrAdd_Methods_For_Multiple_Options() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + + [OptionsBinding("Storage")] + public partial class StorageOptions + { + public string BasePath { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + Assert.Contains("GetOrAddDatabaseOptionsFromTestAssembly", generatedCode, StringComparison.Ordinal); + Assert.Contains("GetOrAddStorageOptionsFromTestAssembly", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Not_Generate_Generic_GetOptions_In_Library() + { + // Arrange - Library assemblies (without OptionsBinding references) should NOT generate GetOptions() + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + // Check that the extension method file exists + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // Verify generic method does NOT exist (library assembly) + // Check for the actual method signature, not just the name in comments + Assert.DoesNotContain("public static T GetOptions", generatedCode, StringComparison.Ordinal); + Assert.Contains("namespace Microsoft.Extensions.DependencyInjection", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Not_Generate_Generic_Method_When_No_Referenced_Assemblies() + { + // Arrange - Single-assembly projects (libraries) should NOT generate GetOptions() + // Only consuming assemblies with references should generate the smart dispatcher + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // In single-assembly test context (no referenced assemblies), generic method should NOT be generated + // Check for the actual method signature, not just the name in comments + Assert.DoesNotContain("public static T GetOptions", generatedCode, StringComparison.Ordinal); + + // Verify comment explaining why it's not generated + Assert.Contains("Generic Method Not Generated", generatedCode, StringComparison.Ordinal); + Assert.Contains("not generated in library assemblies without references", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Include_Assembly_Metadata_In_Cache() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + // Check that Add() method accepts assembly name parameter + var cacheCode = output["OptionsInstanceCache.g.cs"]; + Assert.Contains("void Add(T instance, string assemblyName)", cacheCode, StringComparison.Ordinal); + + // Check that Add() is called with assembly name in GetOrAdd methods + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.Contains("OptionsInstanceCache.Add(options, \"TestAssembly\");", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Generator_Should_Include_FindAll_Method_In_Cache() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var cacheCode = output["OptionsInstanceCache.g.cs"]; + Assert.Contains("FindAll", cacheCode, StringComparison.Ordinal); + Assert.Contains("List<(object Instance, string AssemblyName)>", cacheCode, StringComparison.Ordinal); + } + + [Fact] + public void Generic_Method_Should_Include_Error_Message_For_Unregistered_Types() + { + // Arrange - The smart dispatcher generates compile-time error for unrecognized types + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // Verify the GetOptions method is NOT generated for library assemblies + // Check for the actual method signature, not just the name in comments + Assert.DoesNotContain("public static T GetOptions", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Smart_Dispatcher_Should_Include_Available_Types_In_Error() + { + // Arrange - When GetOptions() IS generated (with references), it includes available types in error + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // Since this is a library assembly, GetOptions() should not be generated + // The smart dispatcher only generates in consuming assemblies with references + Assert.DoesNotContain("Available types:", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Smart_Dispatcher_Should_Call_Get_Methods_Not_GetOrAdd() + { + // Arrange - Smart dispatcher should call Get methods (no caching) not GetOrAdd + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // In library assemblies, GetOptions() is not generated + // This test would need multi-assembly setup to properly test the dispatcher + // For now, verify both Get and GetOrAdd methods exist + Assert.Contains("public static global::MyApp.Configuration.DatabaseOptions GetDatabaseOptionsFromTestAssembly", generatedCode, StringComparison.Ordinal); + Assert.Contains("public static global::MyApp.Configuration.DatabaseOptions GetOrAddDatabaseOptionsFromTestAssembly", generatedCode, StringComparison.Ordinal); + + // Note: Full dispatcher testing requires multi-assembly setup which is complex in unit tests + // The sample project serves as integration test for this functionality + } + + [Fact] + public void Generic_Method_Should_List_Assembly_Specific_Methods_In_Error() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var generatedCode = GetGeneratedExtensionMethod(output); + Assert.NotNull(generatedCode); + + // Verify error includes method suggestions + Assert.Contains("GetOrAdd", generatedCode, StringComparison.Ordinal); + Assert.Contains("From", generatedCode, StringComparison.Ordinal); + } + + [Fact] + public void Cache_Should_Support_Multiple_Assemblies() + { + // Arrange + const string source = """ + using Atc.SourceGenerators.Annotations; + + namespace MyApp.Configuration; + + [OptionsBinding("Database")] + public partial class DatabaseOptions + { + public string ConnectionString { get; set; } = string.Empty; + } + """; + + // Act + var (diagnostics, output) = GetGeneratedOutput(source); + + // Assert + Assert.Empty(diagnostics); + + var cacheCode = output["OptionsInstanceCache.g.cs"]; + + // Verify cache structure supports multiple assemblies + Assert.Contains("ConcurrentDictionary>", cacheCode, StringComparison.Ordinal); + } +} \ No newline at end of file diff --git a/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorValidationTests.cs b/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorValidationTests.cs index db64d0d..f9030f3 100644 --- a/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorValidationTests.cs +++ b/test/Atc.SourceGenerators.Tests/Generators/OptionsBinding/OptionsBindingGeneratorValidationTests.cs @@ -133,8 +133,9 @@ public partial class CacheOptions // Verify semicolon is on the same line as the last method call (ValidateOnStart) Assert.Contains(".ValidateOnStart();", generatedCode1, StringComparison.Ordinal); - // Verify semicolon is on the same line as Bind (no validation methods) - Assert.Contains("\"));", generatedCode2, StringComparison.Ordinal); + // Verify semicolon is on the same line as PostConfigure (added for cache population) + // Note: All unnamed options now get a PostConfigure for early access cache population + Assert.Contains(" });", generatedCode2, StringComparison.Ordinal); // Verify there are NO standalone semicolons on a separate line Assert.DoesNotContain(" ;", generatedCode1, StringComparison.Ordinal);