### Full OpenTelemetry Integration Setup

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/06-logging.md

Provides an example of setting up TracerProvider and MeterProvider with specific sources and meters, which are then automatically utilized by the Secrets Manager provider when logging is configured.

```csharp
var tracingOtel = new TracerProviderBuilder()
    .AddSource(SecretsManagerTelemetry.ActivitySourceName)
    .Build();

var metricsOtel = new MeterProviderBuilder()
    .AddMeter(SecretsManagerTelemetry.MeterName)
    .Build();

builder.AddSecretsManagerDiscovery(options =>
{
    options.UseLogging(logger);
    // Tracing and metrics are automatically collected
});
```

--------------------------------

### Production Configuration Setup with AWS Secrets Manager

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

This example demonstrates a robust production configuration setup using AWS Secrets Manager. It includes early logging, JSON file configuration, environment variables, and specific options for filtering secrets, handling duplicates, and setting reload intervals. Use this pattern for secure and dynamic configuration in production environments.

```csharp
using Kralizek.Extensions.Configuration;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

// Early logging setup
using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Information);
});

var logger = loggerFactory.CreateLogger("Configuration");

// Build configuration
var configBuilder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false)
    .AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")}.json", optional: true)
    .AddSecretsManagerDiscovery(options =>
    {
        // Filter to app-specific secrets
        options.SecretFilter = entry => 
            entry.Name.StartsWith($"myapp/{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")}");
        
        // Skip deleted secrets
        options.SecretFilter = entry => entry.DeletedDate == null;
        
        // Reload every 5 minutes
        options.ReloadInterval = TimeSpan.FromMinutes(5);
        
        // Use bootstrap logger
        options.UseBootstrapLogging(loggerFactory);
        
        // Fail on duplicate keys (indicates configuration error)
        options.DuplicateKeyHandling = DuplicateKeyHandling.Throw;
    })
    .AddEnvironmentVariables();

try
{
    var config = configBuilder.Build();
    logger.LogInformation("Configuration loaded successfully");
}
catch (Exception ex)
{
    logger.LogCritical(ex, "Failed to load configuration");
    throw;
}
```

--------------------------------

### Handling Duplicate Keys Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates strategies for handling duplicate keys when loading secrets. This example shows the 'LastWins' strategy.

```csharp
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var options = new SecretsManagerDiscoveryOptions
{
    DuplicateKeyHandling = DuplicateKeyHandling.LastWins
};

// ... configure secrets manager with these options
```

--------------------------------

### Start LocalStack Docker Container

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/CONTRIBUTING.md

Start a LocalStack Docker container for local AWS emulation. This is useful for integration testing.

```bash
docker run -d -p 4566:4566 localstack/localstack:latest
```

--------------------------------

### Logging Integration Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to integrate logging with Secrets Manager configuration. This is useful for monitoring and debugging.

```csharp
using Microsoft.Extensions.Logging;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
var logger = loggerFactory.CreateLogger("MySecretManagerApp");

var options = new SecretsManagerDiscoveryOptions
{
    // ... other options
};

options.UseLogging(logger);

// Or for bootstrap logging:
// options.UseBootstrapLogging(logger);

// ... configure secrets manager with these options
```

--------------------------------

### LocalStack Integration Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to configure the library to use LocalStack for local development and testing. This avoids hitting actual AWS services.

```csharp
using Amazon.Runtime;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var awsOptions = new ClientConfig
{
    ServiceURL = "http://localhost:4566"
};

var credentials = new BasicAWSCredentials("test", "test");

var secretsManagerOptions = new SecretsManagerOptions
{
    AwsOptions = awsOptions,
    Credentials = credentials
};

// ... configure secrets manager with these options
```

--------------------------------

### Bootstrap Logging During Startup Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to enable logging very early in the application startup process, before the main logging infrastructure is fully configured. This is useful for debugging startup issues.

```csharp
using Microsoft.Extensions.Logging;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var logger = LoggerFactory.Create(builder => builder.AddConsole()).CreateLogger("Bootstrap");

var configuration = new ConfigurationBuilder()
    .AddSecretsManager("MyApp/Settings", options =>
    {
        options.UseBootstrapLogging(logger);
    })
    .Build();
```

--------------------------------

### Target Section Organization Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Illustrates how to organize secrets into specific configuration sections. This helps in managing complex configurations and improving readability.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManager("MyApp/Database", options =>
    {
        options.TargetSection = "DatabaseSettings"; // Load into 'DatabaseSettings' section
    })
    .Build();
```

--------------------------------

### Custom Key Generation Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows how to implement custom logic for generating secret keys. This allows for dynamic key naming based on context.

```csharp
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var options = new SecretsManagerSecretKeyGeneratorOptions
{
    KeyGenerator = (context) =>
    {
        // Example: Append a timestamp to the key
        return $"{context.SecretName}-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}";
    }
};

// ... configure secrets manager with these options
```

--------------------------------

### Bootstrap Logging During Startup

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

Log provider activity before the Dependency Injection container is ready by using bootstrap logging. This example configures console logging with information level.

```csharp
using Kralizek.Extensions.Configuration;
using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(logging =>
{
    logging.AddConsole();
    logging.SetMinimumLevel(LogLevel.Information);
});

var builder = new ConfigurationBuilder();
builder.AddSecretsManagerDiscovery(options =>
{
    options.UseBootstrapLogging(loggerFactory);
});

var config = builder.Build();
```

--------------------------------

### Install AWS SDK for EKS IAM Roles for Service Accounts

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/README.md

This command installs the necessary AWS SDK package to enable authentication to AWS Secrets Manager using IAM roles for service accounts in EKS.

```bash
dotnet add package AWSSDK.SecurityToken
```

--------------------------------

### Install AWS Secrets Manager Configuration Extension

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/src/Kralizek.Extensions.Configuration.AWSSecretsManager/README.md

Add the NuGet package to your project using the dotnet CLI.

```bash
dotnet add package Kralizek.Extensions.Configuration.AWSSecretsManager
```

--------------------------------

### OpenTelemetry Observability Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows how to integrate OpenTelemetry for tracing and metrics with Secrets Manager operations. This enhances visibility into application performance and behavior.

```csharp
using OpenTelemetry.Trace;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

// Configure OpenTelemetry tracing
// ...

var options = new SecretsManagerOptions
{
    // Enable OpenTelemetry integration
    EnableOpenTelemetry = true
};

// ... configure secrets manager with these options
```

--------------------------------

### Combine Path Separator with Prefix Control Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows how to effectively use path separators and prefixes when discovering secrets. This helps in organizing and accessing secrets in a structured manner.

```csharp
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var options = new SecretsManagerDiscoveryOptions
{
    // Example: Use a prefix and a path separator to organize secrets
    Prefix = "MyApp/",
    PathSeparator = "/"
};

// ... configure secrets manager with these options
```

--------------------------------

### Handling Duplicate Keys - Throw Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to configure the library to throw an exception when duplicate keys are encountered during secret loading. This enforces data integrity.

```csharp
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var options = new SecretsManagerDiscoveryOptions
{
    DuplicateKeyHandling = DuplicateKeyHandling.Throw
};

// ... configure secrets manager with these options
```

--------------------------------

### Multiple Registrations with Precedence Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to register multiple Secrets Manager configurations with defined precedence. This allows for fallback mechanisms or environment-specific configurations.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configurationBuilder = new ConfigurationBuilder()
    .AddSecretsManager("PrimarySecretStore", options => options.Region = "us-east-1")
    .AddSecretsManager("FallbackSecretStore", options => {
        options.Region = "us-west-2";
        options.Credentials = new Amazon.Runtime.BasicAWSCredentials("fallback", "creds");
    });

var configuration = configurationBuilder.Build();
```

--------------------------------

### Secrets Scheduled for Deletion Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Illustrates how to handle secrets that are scheduled for deletion. This is important for graceful shutdown or cleanup processes.

```csharp
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var options = new SecretsManagerDiscoveryOptions
{
    // Example: Ignore secrets scheduled for deletion
    IgnoreSecretsScheduledForDeletion = true
};

// ... configure secrets manager with these options
```

--------------------------------

### UseBootstrapLogging Extension Method for SecretsManagerKnownSecretOptions

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/10-api-summary.md

Configures bootstrap logging for SecretsManagerKnownSecretOptions via a LoggerFactory. This is beneficial for initial configuration and setup logging.

```csharp
public static SecretsManagerKnownSecretOptions UseBootstrapLogging(
    this SecretsManagerKnownSecretOptions options,
    ILoggerFactory loggerFactory,
    string? categoryName = null)
```

--------------------------------

### Production Recommended Pattern Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Presents a recommended pattern for using Secrets Manager configuration in a production environment. This typically involves secure credential management and robust error handling.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManager(options =>
    {
        // Use IAM roles for credentials in production
        // Configure region and other necessary settings
        options.Region = "us-east-1";
        options.UseLogging(MyLoggerFactory.CreateLogger()); // Assuming MyLoggerFactory is configured
    })
    .Build();
```

--------------------------------

### Handling Ambiguous Partial ARNs Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Illustrates how to manage secrets with ambiguous or partial ARNs. This is useful when ARNs might not be fully qualified.

```csharp
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var options = new SecretsManagerDiscoveryOptions
{
    // Example: Specify a base ARN to resolve partial ARNs
    BaseArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:"
};

// ... configure secrets manager with these options
```

--------------------------------

### Error Handling and Logging Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows a pattern for handling exceptions during secret retrieval and logging relevant information. This is crucial for robust application behavior.

```csharp
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
using Kralizek.Extensions.Configuration.SecretsManager;
using System;

// ...

var logger = LoggerFactory.Create(builder => builder.AddConsole()).CreateLogger("ErrorHandling");

try
{
    var configuration = new ConfigurationBuilder()
        .AddSecretsManager("MyApp/Config", options =>
        {
            options.UseLogging(logger);
            options.ErrorHandling = SecretsManagerErrorHandling.Throw;
        })
        .Build();

    // Access configuration values
}
catch (Exception ex)
{
    logger.LogError(ex, "Failed to load secrets.");
    // Handle the error appropriately
}
```

--------------------------------

### Quick Start: Discovery Mode

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/src/Kralizek.Extensions.Configuration.AWSSecretsManager/README.md

Use discovery mode to automatically load secrets by calling ListSecrets and BatchGetSecretValue. Requires ListSecrets and BatchGetSecretValue IAM permissions.

```csharp
using Microsoft.Extensions.Configuration;

// Discovery: calls ListSecrets + BatchGetSecretValue
// IAM: secretsmanager:ListSecrets, secretsmanager:BatchGetSecretValue
var configuration = new ConfigurationBuilder()
    .AddSecretsManagerDiscovery()
    .Build();
```

--------------------------------

### Discovery Mode - Load All Secrets Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to configure the library to discover and load all secrets from AWS Secrets Manager. This is useful for applications that need access to a large number of secrets.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManagerDiscovery(options =>
    {
        // Configure discovery options as needed
        options.Prefix = "MyApp/";
    })
    .Build();
```

--------------------------------

### Filter Secrets by Pattern Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to filter secrets based on a pattern during discovery. This allows you to load only the secrets that match specific criteria.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManagerDiscovery(options =>
    {
        options.Prefix = "MyApp/";
        options.SecretFilter = "Database*"; // Load secrets starting with 'Database'
    })
    .Build();
```

--------------------------------

### Dependency Injection with Options Pattern Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to use dependency injection to access Secrets Manager configuration options within an application. This follows the standard .NET options pattern.

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

public class MyService
{
    private readonly SecretsManagerOptions _options;

    public MyService(IOptions<SecretsManagerOptions> options)
    {
        _options = options.Value;
    }

    // ... use _options
}

// In Startup.cs or Program.cs:
// services.AddSecretsManager(options => {
//     // Configure options here
// });
```

--------------------------------

### UseBootstrapLogging Extension Method for SecretsManagerDiscoveryOptions

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/10-api-summary.md

Configures the SecretsManagerDiscoveryOptions to use bootstrap logging with a LoggerFactory. This is helpful for logging during the initial setup phase.

```csharp
public static SecretsManagerDiscoveryOptions UseBootstrapLogging(
    this SecretsManagerDiscoveryOptions options,
    ILoggerFactory loggerFactory,
    string? categoryName = null)
```

--------------------------------

### Configure AWS Region Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows how to specify the AWS region for Secrets Manager operations. This is essential for targeting the correct AWS endpoint.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManager("MyApp/Settings", options =>
    {
        options.Region = "us-west-2"; // Specify the desired AWS region
    })
    .Build();
```

--------------------------------

### ASP.NET Core Integration Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows how to integrate Secrets Manager configuration into an ASP.NET Core application using the options pattern. This allows secrets to be loaded as configuration values.

```csharp
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Hosting;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var builder = WebApplication.CreateBuilder(args);

// Add Secrets Manager configuration provider
builder.Configuration.AddSecretsManager("MySecretPrefix");

// ... rest of the ASP.NET Core setup
```

--------------------------------

### Known Secrets - Fixed List Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows how to configure the library to load a specific, predefined list of secrets. This is useful when the exact secrets required by the application are known in advance.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManagerKnownSecrets(new[] { "MyApp/Database", "MyApp/ApiKey" }, options =>
    {
        // Configure options as needed
    })
    .Build();
```

--------------------------------

### Reload Secrets Periodically Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Shows how to configure automatic reloading of secrets at a specified interval. This ensures that the application uses the latest secret values.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManager("MyApp/Config", options =>
    {
        options.ReloadInterval = TimeSpan.FromMinutes(5); // Reload every 5 minutes
    })
    .Build();
```

--------------------------------

### Single Secret with JSON Flattening Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Demonstrates how to load a single secret and flatten its JSON content into the configuration. This is useful for accessing nested configuration values within a secret.

```csharp
using Microsoft.Extensions.Configuration;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var configuration = new ConfigurationBuilder()
    .AddSecretsManager("MyApp/Config", options =>
    {
        options.JsonValueDelimiter = ":"; // Or other delimiter
        options.FlattenJson = true;
    })
    .Build();
```

--------------------------------

### JSON Secret Flattening Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/README.md

Demonstrates how JSON secrets are flattened into key-value pairs. A colon is used as the separator, and the flattened keys are rooted at the secret's name.

```text
myapp/database:Host = db.example.com
myapp/database:Port = 5432
```

--------------------------------

### Multiple Registrations Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/src/Kralizek.Extensions.Configuration.AWSSecretsManager/README.md

Combine different AWS Secrets Manager registration modes and apply filters or custom key generators. Later registrations take precedence for duplicate keys.

```csharp
builder
    .AddSecretsManagerDiscovery(options => { options.SecretFilter = e => e.Name.StartsWith("shared/"); })
    .AddSecretsManagerKnownSecret("myapp/high-privilege-secret");
```

--------------------------------

### Custom Key Generation with SecretKeyGeneratorContext

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/07-types-and-enums.md

Example of implementing a custom `KeyGenerator` delegate using `SecretKeyGeneratorContext`. This logic differentiates between JSON-derived keys and scalar secrets, applying different naming conventions.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.KeyGenerator = context =>
    {
        if (context.HasJsonPath)
        {
            // Custom handling for JSON properties
            return $"Nested:{context.DefaultKey}";
        }
        else
        {
            // Scalar secret — use name as-is
            return context.SecretName;
        }
    };
});
```

--------------------------------

### Customizing Log Event Handling

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/06-logging.md

Example of how to configure a custom handler for log events generated by the Secrets Manager discovery process. This allows for custom logging logic, such as writing to the console.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.LogEvent = logEvent =>
    {
        Console.WriteLine($"[{logEvent.Level}] {logEvent.EventId.Name}: {logEvent.Message}");
        if (logEvent.Exception != null)
        {
            Console.WriteLine($"Exception: {logEvent.Exception}");
        }
    };
});
```

--------------------------------

### Quick Start: KnownSecrets Mode

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/src/Kralizek.Extensions.Configuration.AWSSecretsManager/README.md

Use KnownSecrets mode to load a predefined list of secrets by calling BatchGetSecretValue. This mode avoids calling ListSecrets. Requires BatchGetSecretValue IAM permission.

```csharp
using Microsoft.Extensions.Configuration;

// KnownSecrets: calls BatchGetSecretValue for a fixed list — no ListSecrets
// IAM: secretsmanager:BatchGetSecretValue
var configuration = new ConfigurationBuilder()
    .AddSecretsManagerKnownSecrets(new[] { "my-app/db", "my-app/api-key" })
    .Build();
```

--------------------------------

### Run Sample App

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/CONTRIBUTING.md

Navigate to the sample application directory and run it. Samples demonstrate different loading modes and verify end-to-end behavior.

```bash
cd samples/Sample1
dotnet run
```

--------------------------------

### Run Sample Applications

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/AGENTS.md

After making changes, run the corresponding sample application to verify functionality. Navigate to the specific sample directory and execute the run command.

```bash
# For Discovery mode changes
cd samples/Sample1
dotnet run

# For KnownSecrets mode changes
cd samples/Sample2
dotnet run

# For KnownSecret mode changes
cd samples/Sample3
dotnet run

# For web integration
cd samples/SampleWeb
dotnet run
```

--------------------------------

### Enable Bootstrap Logging During Startup

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/README.md

Integrate bootstrap logging to capture early-stage configuration loading messages from Secrets Manager. Requires a LoggerFactory instance.

```csharp
using var factory = LoggerFactory.Create(b => b.AddConsole());
builder.AddSecretsManagerDiscovery(options =>
{
    options.UseBootstrapLogging(factory);
});
```

--------------------------------

### Error Handling

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Reference for exceptions and error conditions, including trigger conditions, recovery strategies, and example handling.

```APIDOC
## Exceptions

### MissingSecretValueException

#### Description
Thrown when a required secret value cannot be retrieved.

#### Trigger Conditions
- [Table of conditions]

#### Properties and Constructor
- [Details provided]

#### Recovery Strategies
- [Strategies described]

#### Example Handling Code
- [Code examples]

#### Related Log Events
- [Event IDs]

### InvalidOperationException

#### Description
Thrown when an operation is attempted in an invalid state or configuration.

#### Trigger Conditions
- [Table of conditions]

#### Properties and Constructor
- [Details provided]

#### Recovery Strategies
- [Strategies described]

#### Example Handling Code
- [Code examples]

#### Related Log Events
- [Event IDs]

### ArgumentNullException

#### Description
Thrown when a required method argument is null.

#### Trigger Conditions
- [Table of conditions]

#### Properties and Constructor
- [Details provided]

#### Recovery Strategies
- [Strategies described]

#### Example Handling Code
- [Code examples]

#### Related Log Events
- [Event IDs]

### ArgumentException

#### Description
Thrown when a method argument is invalid.

#### Trigger Conditions
- [Table of conditions]

#### Properties and Constructor
- [Details provided]

#### Recovery Strategies
- [Strategies described]

#### Example Handling Code
- [Code examples]

#### Related Log Events
- [Event IDs]

### AmazonSecretsManagerException

#### Description
Base exception for AWS SDK-related errors when interacting with Secrets Manager.

#### Trigger Conditions
- [Table of conditions]

#### Properties and Constructor
- [Details provided]

#### Recovery Strategies
- [Strategies described]

#### Example Handling Code
- [Code examples]

#### Related Log Events
- [Event IDs]

## Patterns

- Fail-fast in production
- Pre-validation
- IAM error retry logic
- Fallback strategies
```

--------------------------------

### Customize AWS API Request

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

Customize how AWS API requests are made, for example, to request a specific version stage.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.UseBatchFetch = false;  // Use individual calls
    
    options.ConfigureSecretValueRequest = (request, context) =>
    {
        // Request a specific version stage
        if (context.VersionsToStages.ContainsKey("MYSTAGE"))
        {
            request.VersionStage = "MYSTAGE";
        }
    };
});
```

--------------------------------

### Configure Custom Secret Value Request

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/04-known-secret-options.md

Customize the request for a secret value, for example, to specify a particular version stage.

```csharp
// Request a specific version stage of the secret
builder.AddSecretsManagerKnownSecret("prod-secret", options =>
{
    options.ConfigureSecretValueRequest = (request, context) =>
    {
        request.VersionStage = "PRODUCTION";
    };
});
```

--------------------------------

### Build Project Locally

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/CONTRIBUTING.md

Build the project locally. This command enforces `--warnaserror`, ensuring zero warnings are expected.

```bash
dotnet build --no-incremental -warnaserror
```

--------------------------------

### Filter Secrets by Prefix

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

Load only secrets that start with a specific prefix. You can also add conditions to skip secrets scheduled for deletion.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.SecretFilter = entry => entry.Name.StartsWith("myapp/");
    
    // Also skip secrets scheduled for deletion
    options.SecretFilter = entry => 
        entry.Name.StartsWith("myapp/") && entry.DeletedDate == null;
});
```

--------------------------------

### Filter Secrets by Name Pattern

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/02-discovery-options.md

Use SecretFilter to include only secrets whose names start with a specific pattern. This is a client-side filter.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.SecretFilter = entry => entry.Name.StartsWith("myapp/");
});
```

--------------------------------

### With Logging and Error Handling

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/05-known-secrets-options.md

Configure logging and specify how to handle duplicate keys during secret registration. Set a reload interval for automatic secret updates.

```csharp
builder.AddSecretsManagerKnownSecrets(secretIds, options =>
{
    options.UseLogging(logger);
    options.DuplicateKeyHandling = DuplicateKeyHandling.Throw;
    options.ReloadInterval = TimeSpan.FromMinutes(10);
});
```

--------------------------------

### Run Tests

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/CONTRIBUTING.md

Execute all unit and integration tests for the project. Ensure all tests pass before submitting changes.

```bash
dotnet test
```

--------------------------------

### Implement Error Handling and Logging

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

Implement comprehensive error handling and logging for configuration loading. Catch specific exceptions like MissingSecretValueException and log critical errors. Ensure exceptions are re-thrown after logging.

```csharp
var logger = loggerFactory.CreateLogger("Configuration");

try
{
    builder.AddSecretsManagerDiscovery(options =>
    {
        options.UseLogging(logger);
        options.DuplicateKeyHandling = DuplicateKeyHandling.Throw;
    });
    
    var config = builder.Build();
    logger.LogInformation("Configuration loaded successfully");
}
catch (MissingSecretValueException ex)
{
    logger.LogError(ex, 
        "Failed to load secret '{SecretName}'", ex.SecretName);
    throw;
}
catch (Exception ex)
{
    logger.LogCritical(ex, "Configuration load failed");
    throw;
}
```

--------------------------------

### Entry Point Pattern for Configuration

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/10-api-summary.md

Demonstrates the fluent API pattern for adding AWS Secrets Manager configuration to a builder. Use this to configure discovery, known secrets, and known secret lists.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    // Configure options here
    options.ReloadInterval = TimeSpan.FromMinutes(5);
    options.UseLogging(logger);
})
.AddSecretsManagerKnownSecret("secret-id", options =>
{
    options.KeyMapping.TargetSection = "MySection";
})
.AddSecretsManagerKnownSecrets(secretIds);
```

--------------------------------

### Console Logging During Startup

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/06-logging.md

Demonstrates how to configure the AWS Secrets Manager provider to use console logging during application startup by setting up a LoggerFactory and passing it via options.

```csharp
using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Information);
});

var configBuilder = new ConfigurationBuilder();
configBuilder.AddSecretsManagerDiscovery(options =>
{
    options.UseBootstrapLogging(loggerFactory);
});

var config = configBuilder.Build();
```

--------------------------------

### Project File Organization

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

This snippet shows the directory structure of the documentation files for the Kralizek.Extensions.Configuration.AWSSecretsManager package.

```markdown
/workspace/home/output/
├── README.md                          # Master index
├── MANIFEST.md                        # This file
├── 01-extension-methods.md            # Entry point methods
├── 02-discovery-options.md            # Discovery provider config
├── 03-key-mapping-options.md          # Key transformation
├── 04-known-secret-options.md         # Single-secret config
├── 05-known-secrets-options.md        # Multiple-secrets config
├── 06-logging.md                      # Logging and telemetry
├── 07-types-and-enums.md              # Core types and enums
├── 08-errors.md                       # Exception handling
├── 09-quick-start-examples.md         # Usage examples (20+)
└── 10-api-summary.md                  # Complete API reference
```

--------------------------------

### Custom Request Modification Example

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

Illustrates how to intercept and modify AWS SDK requests before they are sent to Secrets Manager. This is useful for adding custom headers or parameters.

```csharp
using Amazon.SecretsManager.Model;
using Kralizek.Extensions.Configuration.SecretsManager;

// ...

var options = new SecretsManagerOptions
{
    RequestModifier = (request) =>
    {
        // Example: Add a custom header
        request.AddHeader("X-Custom-Header", "MyValue");
        return Task.CompletedTask;
    }
};

// ... configure secrets manager with these options
```

--------------------------------

### Server-Side Filtering with ListSecretsFilters

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/02-discovery-options.md

Apply server-side filters to the ListSecrets API call to reduce the result set at the AWS server. This example filters secrets by name.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.ListSecretsFilters.Add(new Filter
    {
        Key = FilterNameStringType.Name,
        Values = new List<string> { "myapp/" }
    });
});
```

--------------------------------

### Enable Bootstrap Logging for Secrets Manager Discovery

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/README.md

Attach a logger during the application startup phase, before the dependency injection container is fully built. This is useful for debugging early configuration loading issues.

```csharp
using var loggerFactory = LoggerFactory.Create(b => b.AddConsole());

builder.AddSecretsManagerDiscovery(options =>
{
    options.UseBootstrapLogging(loggerFactory);
});
```

--------------------------------

### Migrate CreateClient and ConfigureSecretsManagerConfig hooks

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/MIGRATION.md

The CreateClient factory and ConfigureSecretsManagerConfig callback are removed. Pass a fully configured IAmazonSecretsManager client using the overload instead.

```csharp
// Before
builder.AddSecretsManager(options =>
{
    options.ConfigureSecretsManagerConfig = config =>
    {
        config.ServiceURL = "http://localhost:4566";
        config.Timeout = TimeSpan.FromSeconds(5);
    };
});

// After
var config = new AmazonSecretsManagerConfig
{
    ServiceURL = "http://localhost:4566",
    Timeout = TimeSpan.FromSeconds(5)
};
var client = new AmazonSecretsManagerClient(credentials, config);
builder.AddSecretsManagerDiscovery(client, options => { ... });
```

--------------------------------

### Structured Logging with Serilog

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/06-logging.md

Illustrates integrating the Secrets Manager provider with Serilog for structured logging by creating a Serilog logger and passing it to the provider's options.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    var logger = LoggerFactory
        .Create(b => b.AddSerilog())
        .CreateLogger("SecretsManager");
    
    options.UseLogging(logger);
});
```

--------------------------------

### Custom Separator for Secret Naming Convention

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/03-key-mapping-options.md

Allows defining a custom separator for secret names, enabling support for different naming conventions. This example uses a double-dash separator.

```csharp
// Handle secrets named with double-dash separator
builder.AddSecretsManagerDiscovery(options =>
{
    options.KeyMapping.SecretNamePathSeparator = "--";
});
// Secret: app--db--host becomes: app:db:host
```

--------------------------------

### Configure Duplicate Key Handling

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/02-discovery-options.md

Set the policy for handling duplicate configuration keys when loading secrets. Options include LastWins, FirstWins, or Throw to raise an exception on duplicates.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.DuplicateKeyHandling = DuplicateKeyHandling.Throw;
});
```

--------------------------------

### Configure Secrets Manager logging

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/MIGRATION.md

A new structured logging pipeline is available. Use options.UseLogging(ILogger) for convenience or options.UseBootstrapLogging(ILoggerFactory) for bootstrapping before DI is ready.

```csharp
// Example usage of logging options (specific code not provided in source)
// options.UseLogging(ILogger);
// options.UseBootstrapLogging(ILoggerFactory);
```

--------------------------------

### Production Configuration with Filtering and Reloading

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/README.md

A recommended pattern for production environments. Filters secrets by name prefix, sets a reload interval for dynamic updates, specifies duplicate key handling, and enables bootstrap logging.

```csharp
builder.AddSecretsManagerDiscovery(options =>
{
    options.SecretFilter = e => e.Name.StartsWith("app/");
    options.ReloadInterval = TimeSpan.FromMinutes(5);
    options.DuplicateKeyHandling = DuplicateKeyHandling.Throw;
    options.UseBootstrapLogging(factory);
});
```

--------------------------------

### UseBootstrapLogging Extension Method for SecretsManagerKnownSecretsOptions

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/10-api-summary.md

Sets up bootstrap logging for SecretsManagerKnownSecretsOptions using a LoggerFactory. This is useful for logging during the early stages of application startup.

```csharp
public static SecretsManagerKnownSecretsOptions UseBootstrapLogging(
    this SecretsManagerKnownSecretsOptions options,
    ILoggerFactory loggerFactory,
    string? categoryName = null)
```

--------------------------------

### AddSecretsManagerDiscovery with Pre-Built Client

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/01-extension-methods.md

Adds a discovery-based configuration provider using a pre-configured IAmazonSecretsManager client. Optional configuration of provider options is supported.

```csharp
public static IConfigurationBuilder AddSecretsManagerDiscovery(
    this IConfigurationBuilder builder,
    IAmazonSecretsManager client,
    Action<SecretsManagerDiscoveryOptions>? configure = null)
```

```csharp
var client = new AmazonSecretsManagerClient(new AmazonSecretsManagerConfig
{
    ServiceURL = "http://localhost:4566"  // LocalStack
});
builder.AddSecretsManagerDiscovery(client);
```

--------------------------------

### AddSecretsManagerDiscovery (Using a Pre-Built Client)

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/01-extension-methods.md

Adds a discovery-based configuration provider using a pre-configured IAmazonSecretsManager client, useful for scenarios like using LocalStack.

```APIDOC
## AddSecretsManagerDiscovery (Using a Pre-Built Client)

### Description
Adds a discovery-based configuration provider that discovers secrets via `ListSecrets` and fetches their values using `BatchGetSecretValue` (by default) or individual `GetSecretValue` calls, using a provided `IAmazonSecretsManager` client.

### Method
Extension Method

### Signature
```csharp
public static IConfigurationBuilder AddSecretsManagerDiscovery(
    this IConfigurationBuilder builder,
    IAmazonSecretsManager client,
    Action<SecretsManagerDiscoveryOptions>? configure = null)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| builder | IConfigurationBuilder | Yes | — | The configuration builder. Throws `ArgumentNullException` if null. |
| client | IAmazonSecretsManager | Yes | — | A configured Secrets Manager client. Throws `ArgumentNullException` if null. |
| configure | Action<SecretsManagerDiscoveryOptions>? | No | null | Optional callback to configure provider options. |

### Request Example
```csharp
var client = new AmazonSecretsManagerClient(new AmazonSecretsManagerConfig
{
    ServiceURL = "http://localhost:4566"  // LocalStack
});
builder.AddSecretsManagerDiscovery(client);
```

### Response
#### Success Response
Returns the same builder instance for method chaining.

#### Response Example
`IConfigurationBuilder`
```

--------------------------------

### Quick Start: KnownSecret Mode

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/src/Kralizek.Extensions.Configuration.AWSSecretsManager/README.md

Use KnownSecret mode to load exactly one secret by calling GetSecretValue. This mode avoids ListSecrets and BatchGetSecretValue calls. Requires GetSecretValue IAM permission.

```csharp
using Microsoft.Extensions.Configuration;

// KnownSecret: calls GetSecretValue for exactly one secret — no ListSecrets, no Batch
// IAM: secretsmanager:GetSecretValue
var configuration = new ConfigurationBuilder()
    .AddSecretsManagerKnownSecret("my-app/prod")
    .Build();
```

--------------------------------

### Configure Secret Reload Interval

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/04-known-secret-options.md

Sets the interval for polling AWS Secrets Manager for updated secret values. A null interval means the secret is loaded only once at startup. Examples show setting a 5-minute interval and a 30-second interval.

```csharp
builder.AddSecretsManagerKnownSecret("api-key", options =>
{
    // Reload every 5 minutes
    options.ReloadInterval = TimeSpan.FromMinutes(5);
});

// Reload every 30 seconds
options.ReloadInterval = TimeSpan.FromSeconds(30);

// Disable reload (one-time load at startup)
options.ReloadInterval = null;  // Default
```

--------------------------------

### AddSecretsManagerDiscovery with AWSOptions

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/01-extension-methods.md

Adds a discovery-based configuration provider using specified AWSOptions for credentials and region. Allows configuration of provider options.

```csharp
public static IConfigurationBuilder AddSecretsManagerDiscovery(
    this IConfigurationBuilder builder,
    AWSOptions awsOptions,
    Action<SecretsManagerDiscoveryOptions>? configure = null)
```

```csharp
var awsOptions = new AWSOptions { Region = RegionEndpoint.EUWest1 };
builder.AddSecretsManagerDiscovery(awsOptions, options =>
{
    options.UseBatchFetch = true;
});
```

--------------------------------

### Configure Discovery Options with Bootstrap Logging

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/06-logging.md

Configures SecretsManagerDiscoveryOptions to use a logger created from an ILoggerFactory, suitable for early startup phases before the DI container is available. Specify a custom category name if needed.

```csharp
public static SecretsManagerDiscoveryOptions UseBootstrapLogging(
    this SecretsManagerDiscoveryOptions options,
    ILoggerFactory loggerFactory,
    string? categoryName = null)
```

```csharp
using var loggerFactory = LoggerFactory.Create(b => b.AddConsole());

builder.AddSecretsManagerDiscovery(options =>
{
    options.UseBootstrapLogging(loggerFactory);
});
```

--------------------------------

### Comprehensive API Reference Summary

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/MANIFEST.md

A structured overview of all exported public APIs, including namespaces, extension methods, options classes, enumerations, context types, and exceptions.

```APIDOC
## Exported Namespaces Overview

- [List of exported namespaces and their purpose]

## Extension Methods

- [Signatures and descriptions for all 9 extension methods]

## Options Classes

- [Documentation for all options classes and their properties]

## Enumerations

- [Documentation for all enumerations, including `DuplicateKeyHandling`]

## Context and Data Types

- [Documentation for context and data types like `SecretKeyGeneratorContext`, `SecretValueContext`, `SecretsManagerLogEvent`]

## Exception Types

- [Documentation for all exception types, including `MissingSecretValueException`, `InvalidOperationException`, `ArgumentNullException`, `ArgumentException`, `AmazonSecretsManagerException`]

## Logging and Telemetry Classes

- [Documentation for logging and telemetry classes like `SecretsManagerLogging`, `SecretsManagerLogEvent`, `SecretsManagerTelemetry`]

## Type Hierarchy Diagram

- [Visual representation of type relationships]

## Namespace Organization

- [Description of how namespaces are organized]

## Source File Overview

- [Information about the source files]

## Version Compatibility

- [Notes on version compatibility]

## Content Details

- All method signatures in code blocks.
- Complete property tables with descriptions.
- Type relationships.
- Thread safety notes.
- Null safety notes.
```

--------------------------------

### Enable OpenTelemetry Observability

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

Configure OpenTelemetry for distributed tracing and metrics collection. Spans and metrics are automatically emitted.

```csharp
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenTelemetry.Metrics;
using Kralizek.Extensions.Configuration;

var tracingOtel = new TracerProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("my-app"))
    .AddSource(SecretsManagerTelemetry.ActivitySourceName)
    .AddConsoleExporter()
    .Build();

var metricsOtel = new MeterProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("my-app"))
    .AddMeter(SecretsManagerTelemetry.MeterName)
    .AddConsoleExporter()
    .Build();

builder.AddSecretsManagerDiscovery();
// Spans and metrics are automatically emitted
```

--------------------------------

### Handle MissingSecretValueException

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/07-types-and-enums.md

Demonstrates how to catch and handle a MissingSecretValueException when building configuration.

```csharp
try
{
    var config = builder.Build();
}
catch (MissingSecretValueException ex)
{
    Console.WriteLine($"Could not load secret: {ex.SecretName}");
    Console.WriteLine($"ARN: {ex.SecretArn}");
    Console.WriteLine($"Inner error: {ex.InnerException?.Message}");
}
```

--------------------------------

### Configure Known Secret Options with Bootstrap Logging

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/06-logging.md

Configures SecretsManagerKnownSecretOptions to use a logger created from an ILoggerFactory for early startup logging. This is useful when the DI container is not yet available.

```csharp
builder.AddSecretsManagerKnownSecret("my-secret", options =>
{
    options.UseBootstrapLogging(loggerFactory);
});
```

--------------------------------

### Dependency Injection with Options Pattern using Secrets Manager

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

Configure dependency injection with the options pattern to bind secrets to strongly-typed objects. Use `AddSecretsManagerKnownSecret` to load specific secrets and `Configure` to bind them to your options class. Ensure the `KeyMapping.PrefixJsonKeysWithSecretName` is set appropriately if your secret keys do not match the JSON structure.

```csharp
using Microsoft.Extensions.Options;

public class ApiSettings
{
    public string ApiKey { get; set; }
    public string ApiUrl { get; set; }
}

// In Program.cs
builder.AddSecretsManagerKnownSecret("api-settings", options =>
{
    options.KeyMapping.PrefixJsonKeysWithSecretName = false;
});

var config = builder.Build();

builder.Services.Configure<ApiSettings>(config.GetSection("ApiSettings"));

// In a service
public class ApiService
{
    private readonly ApiSettings _settings;
    
    public ApiService(IOptions<ApiSettings> options)
    {
        _settings = options.Value;
    }
}

```

--------------------------------

### Connect to LocalStack for Local Development

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/09-quick-start-examples.md

Configure the Secrets Manager client to connect to a LocalStack instance for local testing. Set the ServiceURL to your LocalStack endpoint. LocalStack may have quirks with batch fetch, so consider disabling it.

```csharp
var client = new Amazon.SecretsManager.AmazonSecretsManagerClient(
    new Amazon.SecretsManager.AmazonSecretsManagerConfig
    {
        ServiceURL = "http://localhost:4566",
        AuthenticationRegion = "us-east-1"
    });

builder.AddSecretsManagerDiscovery(client, options =>
{
    options.UseBatchFetch = false;  // LocalStack may have quirks with batch fetch
});
```

--------------------------------

### Run Repository Root Validations

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/AGENTS.md

Execute all required checks from the repository root before finalizing work. This includes format validation, build, testing, and code analysis.

```bash
# 1. Format validation
dotnet format --verify-no-changes

# 2. Build — warnings are treated as errors
dotnet build --no-incremental -warnaserror

# 3. All tests
dotnet test

# 4. Check code analysis (optional, if enabled)
dotnet analyze
```

--------------------------------

### Configure Key Mapping for Known Secrets

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/05-known-secrets-options.md

Customize how secret names and values are mapped to .NET configuration keys using KeyMapping options. This includes setting the path separator, whether to prefix JSON keys, and the target section.

```csharp
builder.AddSecretsManagerKnownSecrets(new[] { "db", "api" }, options =>
{
    options.KeyMapping.SecretNamePathSeparator = "-";
    options.KeyMapping.PrefixJsonKeysWithSecretName = false;
    options.KeyMapping.TargetSection = "Secrets";
});
```

--------------------------------

### AddSecretsManagerDiscovery with Ambient Credentials

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/01-extension-methods.md

Adds a discovery-based configuration provider using ambient AWS credentials. Configure provider options via a callback.

```csharp
public static IConfigurationBuilder AddSecretsManagerDiscovery(
    this IConfigurationBuilder builder,
    Action<SecretsManagerDiscoveryOptions>? configure = null)
```

```csharp
var builder = new ConfigurationBuilder();
builder.AddSecretsManagerDiscovery();
var config = builder.Build();
```

--------------------------------

### Options and Types Namespace

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/README.md

Imports for configuration options and types used within the Secrets Manager extensions.

```csharp
using Kralizek.Extensions.Configuration;
// SecretsManagerDiscoveryOptions, DuplicateKeyHandling, etc.
```

--------------------------------

### Configure Options with New Classes

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/MIGRATION.md

SecretsManagerConfigurationProviderOptions has been replaced by three separate options classes: SecretsManagerDiscoveryOptions, SecretsManagerKnownSecretsOptions, and SecretsManagerKnownSecretOptions. Options are configured via lambda overloads of each method.

```csharp
// Before
builder.AddSecretsManager(options =>
{
    options.KeyGenerator = context => context.DefaultKey.ToUpper();
    options.PollingInterval = TimeSpan.FromMinutes(5);
});

// After
builder.AddSecretsManagerDiscovery(options =>
{
    options.KeyGenerator = context => context.DefaultKey.ToUpper();
    options.ReloadInterval = TimeSpan.FromMinutes(5);
});
```

--------------------------------

### Configure Options: Secret Filtering and Key Generation

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/src/Kralizek.Extensions.Configuration.AWSSecretsManager/README.md

Customize the discovery mode by filtering secrets based on their names and transforming the secret key names using a custom generator.

```csharp
var configuration = new ConfigurationBuilder()
    .AddSecretsManagerDiscovery(options =>
    {
        options.SecretFilter = entry => entry.Name.StartsWith("myapp/");
        options.KeyGenerator = context => context.DefaultKey.Replace("/", ":");
    })
    .Build();
```

--------------------------------

### Set Duplicate Key Handling Strategy

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/04-known-secret-options.md

Configures the policy for handling duplicate configuration keys generated from a single JSON secret. Use 'Throw' to raise an exception on the first duplicate key encountered.

```csharp
builder.AddSecretsManagerKnownSecret("app-config", options =>
{
    options.DuplicateKeyHandling = DuplicateKeyHandling.Throw;
});
```

--------------------------------

### Individual Fetches with Custom Per-Secret Configuration

Source: https://github.com/kralizek/awssecretsmanagerconfigurationextensions/blob/master/_autodocs/05-known-secrets-options.md

Fetch secrets individually and customize each fetch request based on the secret name. Useful for applying different configurations like VersionStage.

```csharp
builder.AddSecretsManagerKnownSecrets(secretIds, options =>
{
    options.UseBatchFetch = false;  // Fetch individually
    options.ConfigureSecretValueRequest = (request, context) =>
    {
        // Customize each fetch based on secret name
        if (context.Name.StartsWith("prod"))
        {
            request.VersionStage = "PRODUCTION";
        }
        else
        {
            request.VersionStage = "DEVELOPMENT";
        }
    };
});
```