feat: extend support for Early Access to Options During Service Registration

Author: davidkallesen

CLAUDE.md

@@ -349,6 +349,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<T>()` | ✅ 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<DatabaseOptions>(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<IFeatureX, FeatureXService>();
+}
+
+// Normal AddOptionsFrom* methods register with service collection
+services.AddOptionsFromDomain(configuration);
+// Options available via IOptions<T>, IOptionsSnapshot<T>, IOptionsMonitor<T>
+```
+
+**How the Smart Dispatcher Works:**
+- **Library assemblies** (no OptionsBinding references): Don't generate `GetOptions<T>()` - use assembly-specific methods
+- **Consuming assemblies** (with OptionsBinding references): Generate smart dispatcher that routes based on type:
+  ```csharp
+  public static T GetOptions<T>(...)
+  {
+      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

README.md

@@ -354,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

docs/OptionsBindingGenerators-FeatureRoadmap.md

@@ -84,7 +84,7 @@ 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 |
-| ❌ | [Early Access to Options During Service Registration](#10-early-access-to-options-during-service-registration) | 🔴 High |
+| ✅ | [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 |
@@ -863,9 +863,16 @@ public partial class NotificationOptions
 ### 10. Early Access to Options During Service Registration
 
 **Priority**: 🔴 **High** ⭐ *Avoids BuildServiceProvider anti-pattern*
-**Status**: ❌ Not Implemented
+**Status**: ✅ **Implemented**
 **Inspiration**: [StackOverflow: Avoid BuildServiceProvider](https://stackoverflow.com/questions/66263977/how-to-avoid-using-using-buildserviceprovider-method-at-multiple-places)
 
+> **📝 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<T>()` - 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.
+
 **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.
 
 **User Story**:
@@ -1636,7 +1643,7 @@ Based on priority, user demand, and implementation complexity:
 | 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** | ❌ |
+| **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+ | ❌ |

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<T>, IEnumerable<T>, arrays
 - **Dictionaries** - Dictionary<string, string>, Dictionary<string, T>