feat: extend support for Post-Configuration OptionsBinding

Author: davidkallesen

CLAUDE.md

@@ -299,6 +299,7 @@ services.AddDependencyRegistrationsFromDomain(
   5. Auto-inferred from class name
 - Supports validation: `ValidateDataAnnotations`, `ValidateOnStart`, `ErrorOnMissingKeys` (fail-fast for missing sections), Custom validators (`IValidateOptions<T>`)
 - **Configuration change callbacks**: Auto-generated IHostedService for OnChange notifications with Monitor lifetime - perfect for feature flags and runtime configuration updates
+- **Post-configuration support**: `PostConfigure` callbacks for normalizing/transforming values after binding (e.g., path normalization, URL lowercase)
 - **Named options support**: Multiple configurations of the same options type with different names (e.g., Primary/Secondary email servers)
 - **Nested subsection binding**: Automatic binding of complex properties to configuration subsections (e.g., `StorageOptions.Database.Retry` → `"Storage:Database:Retry"`) - supported out-of-the-box by Microsoft's `.Bind()` method
 - Supports lifetime selection: Singleton (IOptions), Scoped (IOptionsSnapshot), Monitor (IOptionsMonitor)
@@ -404,6 +405,30 @@ services.AddSingleton<IOptionsChangeTokenSource<FeaturesOptions>>(
     new ConfigurationChangeTokenSource<FeaturesOptions>(
         configuration.GetSection("Features")));
 services.Configure<FeaturesOptions>(configuration.GetSection("Features"));
+
+// Input with PostConfigure (path normalization):
+[OptionsBinding("Storage", PostConfigure = nameof(NormalizePaths))]
+public partial class StorageOptions
+{
+    public string BasePath { get; set; } = string.Empty;
+    public string CachePath { get; set; } = string.Empty;
+
+    private static void NormalizePaths(StorageOptions options)
+    {
+        options.BasePath = EnsureTrailingSlash(options.BasePath);
+        options.CachePath = EnsureTrailingSlash(options.CachePath);
+    }
+
+    private static string EnsureTrailingSlash(string path)
+        => string.IsNullOrWhiteSpace(path) || path.EndsWith(Path.DirectorySeparatorChar)
+            ? path
+            : path + Path.DirectorySeparatorChar;
+}
+
+// Output with PostConfigure:
+services.AddOptions<StorageOptions>()
+    .Bind(configuration.GetSection("Storage"))
+    .PostConfigure(options => StorageOptions.NormalizePaths(options));
 ```
 
 **Smart Naming:**
@@ -438,6 +463,9 @@ services.AddOptionsFromDomain(configuration, "DataAccess", "Infrastructure");
 - `ATCOPT005` - OnChange not supported with named options (Error)
 - `ATCOPT006` - OnChange callback method not found (Error)
 - `ATCOPT007` - OnChange callback has invalid signature (Error)
+- `ATCOPT008` - PostConfigure not supported with named options (Error)
+- `ATCOPT009` - PostConfigure callback method not found (Error)
+- `ATCOPT010` - PostConfigure callback has invalid signature (Error)
 
 ### MappingGenerator
 

README.md

@@ -320,6 +320,7 @@ services.AddOptionsFromApp(configuration);
 - **🔒 Built-in Validation**: Integrated DataAnnotations validation (`ValidateDataAnnotations`) and startup validation (`ValidateOnStart`)
 - **🎯 Custom Validation**: Support for `IValidateOptions<T>` for complex business rules beyond DataAnnotations
 - **🔔 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)
 - **🎯 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"`)
@@ -422,6 +423,9 @@ public class MyService
 | ATCOPT005 | OnChange not supported with named options |
 | ATCOPT006 | OnChange callback method not found |
 | ATCOPT007 | OnChange callback has invalid signature |
+| ATCOPT008 | PostConfigure not supported with named options |
+| ATCOPT009 | PostConfigure callback method not found |
+| ATCOPT010 | PostConfigure callback has invalid signature |
 
 ---
 

docs/OptionsBindingGenerators-FeatureRoadmap.md

@@ -58,13 +58,14 @@ This roadmap is based on comprehensive analysis of:
 - **Named options** - Multiple configurations of the same options type with different names
 - **Error on missing keys** - `ErrorOnMissingKeys` fail-fast validation when configuration sections are missing
 - **Configuration change callbacks** - `OnChange` callbacks for Monitor lifetime (auto-generates IHostedService)
+- **Post-configuration support** - `PostConfigure` callbacks for normalizing/transforming values after binding (e.g., path normalization, URL lowercase)
 - **Nested subsection binding** - Automatic binding of complex properties to configuration subsections (e.g., `Storage:Database:Retry`)
 - **Lifetime selection** - Singleton (`IOptions`), Scoped (`IOptionsSnapshot`), Monitor (`IOptionsMonitor`)
 - **Multi-project support** - Assembly-specific extension methods with smart naming
 - **Transitive registration** - 4 overloads for automatic/selective assembly registration
 - **Partial class requirement** - Enforced at compile time
 - **Native AOT compatible** - Zero reflection, compile-time generation
-- **Compile-time diagnostics** - Validate partial class, section names, OnChange callbacks (ATCOPT001-007)
+- **Compile-time diagnostics** - Validate partial class, section names, OnChange/PostConfigure callbacks (ATCOPT001-010)
 
 ---
 
@@ -74,7 +75,7 @@ This roadmap is based on comprehensive analysis of:
 |:------:|---------|----------|
 | ✅ | [Custom Validation Support (IValidateOptions)](#1-custom-validation-support-ivalidateoptions) | 🔴 High |
 | ✅ | [Named Options Support](#2-named-options-support) | 🔴 High |
-| ❌ | [Post-Configuration Support](#3-post-configuration-support) | 🟡 Medium-High |
+| ✅ | [Post-Configuration Support](#3-post-configuration-support) | 🟡 Medium-High |
 | ✅ | [Error on Missing Configuration Keys](#4-error-on-missing-configuration-keys) | 🔴 High |
 | ✅ | [Configuration Change Callbacks](#5-configuration-change-callbacks) | 🟡 Medium |
 | ✅ | [Bind Configuration Subsections to Properties](#6-bind-configuration-subsections-to-properties) | 🟡 Medium |
@@ -249,7 +250,7 @@ public class DataService
 ### 3. Post-Configuration Support
 
 **Priority**: 🟡 **Medium-High**
-**Status**: ❌ Not Implemented
+**Status**: ✅ **Implemented**
 **Inspiration**: `IPostConfigureOptions<T>` pattern
 
 **Description**: Support post-configuration actions that run after binding and validation to apply defaults or transformations.
@@ -288,12 +289,28 @@ services.AddOptions<StorageOptions>()
     .PostConfigure(options => StorageOptions.NormalizePaths(options));
 ```
 
-**Implementation Notes**:
+**Implementation Details**:
+
+- ✅ Added `PostConfigure` property to `[OptionsBinding]` attribute
+- ✅ Generator calls `.PostConfigure()` method on the options builder
+- ✅ PostConfigure method must have signature: `static void MethodName(TOptions options)`
+- ✅ Runs after binding and validation
+- ✅ PostConfigure method can be `internal` or `public` (not `private`)
+- ⚠️ Cannot be used with named options
+- ✅ Comprehensive compile-time validation with 3 diagnostic codes (ATCOPT008-010)
+- ✅ Useful for normalization, defaults, computed properties
+
+**Diagnostics**:
+
+- **ATCOPT008**: PostConfigure callback not supported with named options
+- **ATCOPT009**: PostConfigure callback method not found
+- **ATCOPT010**: PostConfigure callback method has invalid signature
+
+**Testing**:
 
-- Add `PostConfigure` parameter pointing to static method
-- Method signature: `static void Configure(TOptions options)`
-- Runs after binding and validation
-- Useful for normalization, defaults, computed properties
+- ✅ Unit tests covering all scenarios and error cases
+- ✅ Sample project: StoragePathsOptions demonstrates path normalization (trailing slash)
+- ✅ PetStore.Api sample: ExternalApiOptions demonstrates URL normalization (lowercase + trailing slash removal)
 
 ---
 

docs/OptionsBindingGenerators.md

@@ -745,6 +745,7 @@ Console.WriteLine($"Other interval: {otherOptions.Value.RepeatIntervalInSeconds}
 - **🎯 Custom validation** - Support for `IValidateOptions<T>` for complex business rules beyond DataAnnotations
 - **🚨 Error on missing keys** - Fail-fast validation when configuration sections are missing (`ErrorOnMissingKeys`) to catch deployment issues at startup
 - **🔔 Configuration change callbacks** - Automatically respond to configuration changes at runtime with `OnChange` callbacks (requires Monitor lifetime)
+- **🔧 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)
 - **🎯 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"`)
@@ -1324,6 +1325,159 @@ The generator performs compile-time validation of OnChange callbacks:
 
 ---
 
+### 🔧 Post-Configuration Support
+
+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
+
+**Basic Example:**
+
+```csharp
+[OptionsBinding("Storage", PostConfigure = nameof(NormalizePaths))]
+public partial class StoragePathsOptions
+{
+    public string BasePath { get; set; } = string.Empty;
+    public string CachePath { get; set; } = string.Empty;
+    public string TempPath { get; set; } = string.Empty;
+
+    private static void NormalizePaths(StoragePathsOptions options)
+    {
+        // Ensure all paths end with directory separator
+        options.BasePath = EnsureTrailingSlash(options.BasePath);
+        options.CachePath = EnsureTrailingSlash(options.CachePath);
+        options.TempPath = EnsureTrailingSlash(options.TempPath);
+    }
+
+    private static string EnsureTrailingSlash(string path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return path;
+
+        return path.EndsWith(Path.DirectorySeparatorChar)
+            ? path
+            : path + Path.DirectorySeparatorChar;
+    }
+}
+```
+
+**Generated Code:**
+
+The generator automatically calls `.PostConfigure()` after binding:
+
+```csharp
+services.AddOptions<StoragePathsOptions>()
+    .Bind(configuration.GetSection("Storage"))
+    .PostConfigure(options => StoragePathsOptions.NormalizePaths(options));
+```
+
+**Usage Scenarios:**
+
+```csharp
+// Path normalization - ensure trailing slashes
+[OptionsBinding("Storage", PostConfigure = nameof(NormalizePaths))]
+public partial class StoragePathsOptions
+{
+    public string BasePath { get; set; } = string.Empty;
+    public string CachePath { get; set; } = string.Empty;
+
+    private static void NormalizePaths(StoragePathsOptions options)
+    {
+        options.BasePath = EnsureTrailingSlash(options.BasePath);
+        options.CachePath = EnsureTrailingSlash(options.CachePath);
+    }
+
+    private static string EnsureTrailingSlash(string path)
+        => string.IsNullOrWhiteSpace(path) || path.EndsWith(Path.DirectorySeparatorChar)
+            ? path
+            : path + Path.DirectorySeparatorChar;
+}
+
+// URL normalization - lowercase and remove trailing slashes
+[OptionsBinding("ExternalApi", PostConfigure = nameof(NormalizeUrls))]
+public partial class ExternalApiOptions
+{
+    public string BaseUrl { get; set; } = string.Empty;
+    public string CallbackUrl { get; set; } = string.Empty;
+
+    private static void NormalizeUrls(ExternalApiOptions options)
+    {
+        options.BaseUrl = NormalizeUrl(options.BaseUrl);
+        options.CallbackUrl = NormalizeUrl(options.CallbackUrl);
+    }
+
+    private static string NormalizeUrl(string url)
+    {
+        if (string.IsNullOrWhiteSpace(url))
+            return url;
+
+        // Lowercase and remove trailing slash
+        return url.ToLowerInvariant().TrimEnd('/');
+    }
+}
+
+// Combined with validation
+[OptionsBinding("Database",
+    ValidateDataAnnotations = true,
+    ValidateOnStart = true,
+    PostConfigure = nameof(ApplyDefaults))]
+public partial class DatabaseOptions
+{
+    [Required] public string ConnectionString { get; set; } = string.Empty;
+    public int CommandTimeout { get; set; }
+
+    private static void ApplyDefaults(DatabaseOptions options)
+    {
+        // Apply default timeout if not set
+        if (options.CommandTimeout <= 0)
+        {
+            options.CommandTimeout = 30;
+        }
+    }
+}
+```
+
+**Validation Errors:**
+
+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))]
+  public partial class EmailOptions { }
+  ```
+
+- **ATCOPT009**: PostConfigure callback method not found
+  ```csharp
+  // Error: Method 'ApplyDefaults' does not exist
+  [OptionsBinding("Settings", PostConfigure = "ApplyDefaults")]
+  public partial class Settings { }
+  ```
+
+- **ATCOPT010**: PostConfigure callback method has invalid signature
+  ```csharp
+  // Error: Must be static void with (TOptions) parameter
+  [OptionsBinding("Settings", PostConfigure = nameof(Configure))]
+  public partial class Settings
+  {
+      private void Configure() { }  // Wrong: not static, missing parameter
+  }
+  ```
+
+**Important Notes:**
+
+- PostConfigure runs **after** binding and validation
+- Callback method can be `internal` or `public` (not `private`)
+- Cannot be combined with named options (use manual `.PostConfigure()` if needed)
+- Perfect for normalizing user input, applying business rules, or computed properties
+- Order of execution: Bind → Validate → PostConfigure
+
+---
+
 ## 🔧 How It Works
 
 ### 1️⃣ Attribute Detection
@@ -1888,6 +2042,14 @@ public partial class DatabaseOptions  // ✅ Inferred as "Database"
 }
 ```
 
+### ❌ ATCOPT004-007: OnChange Callback Diagnostics
+
+See [Configuration Change Callbacks](#-configuration-change-callbacks) section for details.
+
+### ❌ ATCOPT008-010: PostConfigure Callback Diagnostics
+
+See [Post-Configuration Support](#-post-configuration-support) section for details.
+
 ---
 
 ## 🚀 Native AOT Compatibility

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

@@ -86,4 +86,4 @@ public class RetryPolicy
     public int DelayMilliseconds { get; set; } = 1000;
 
     public bool UseExponentialBackoff { get; set; } = true;
-}
+}

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

@@ -0,0 +1,52 @@
+namespace Atc.SourceGenerators.OptionsBinding.Options;
+
+/// <summary>
+/// Storage paths configuration options.
+/// Demonstrates Feature #7: Post-Configuration support for normalizing values after binding.
+/// The PostConfigure callback ensures all paths end with a directory separator,
+/// providing consistent path handling across the application.
+/// </summary>
+[OptionsBinding("StoragePaths", ValidateDataAnnotations = true, PostConfigure = nameof(NormalizePaths))]
+public partial class StoragePathsOptions
+{
+    [Required]
+    public string BasePath { get; set; } = string.Empty;
+
+    [Required]
+    public string CachePath { get; set; } = string.Empty;
+
+    [Required]
+    public string TempPath { get; set; } = string.Empty;
+
+    public string LogPath { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Post-configuration method to normalize all path values.
+    /// This ensures all paths end with a directory separator for consistent usage.
+    /// Signature: static void MethodName(TOptions options)
+    /// </summary>
+    internal static void NormalizePaths(StoragePathsOptions options)
+    {
+        // Normalize all paths to ensure they end with directory separator
+        options.BasePath = EnsureTrailingDirectorySeparator(options.BasePath);
+        options.CachePath = EnsureTrailingDirectorySeparator(options.CachePath);
+        options.TempPath = EnsureTrailingDirectorySeparator(options.TempPath);
+        options.LogPath = EnsureTrailingDirectorySeparator(options.LogPath);
+    }
+
+    /// <summary>
+    /// Ensures a path ends with a directory separator character.
+    /// </summary>
+    private static string EnsureTrailingDirectorySeparator(string path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return path;
+        }
+
+        return path.EndsWith(Path.DirectorySeparatorChar) ||
+               path.EndsWith(Path.AltDirectorySeparatorChar)
+            ? path
+            : path + Path.DirectorySeparatorChar;
+    }
+}