Opc.AwsSettings

A .NET library that simplifies loading configuration from AWS services including Parameter Store, Secrets Manager, and AppConfig into your application's configuration system.

Features

🔧 AWS Systems Manager Parameter Store - Load configuration from hierarchical parameters
🔐 AWS Secrets Manager - Securely load secrets into your configuration
⚙️ AWS AppConfig - Load feature flags and freeform configuration
🔄 Auto-reload - Optionally reload configuration at specified intervals
🎯 Easy Integration - Seamlessly integrates with .NET's IConfiguration system
🌍 Environment-aware - Support for environment-specific configurations

Installation

Install the NuGet package:

dotnet add package Opc.AwsSettings

Quick Start

Basic Usage with Host Builder

using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings() // Add AWS configuration sources
    .ConfigureServices(services =>
    {
        // Your service configuration
    })
    .Build();

await host.RunAsync();

Manual Configuration Builder Usage

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddAwsSettings() // Add AWS configuration sources
    .Build();

Configuration

Configure the library using the AwsSettings section in your appsettings.json:

{
  "AwsSettings": {
    "ReloadAfter": "00:05:00",
    "ParameterStore": {
      "Paths": ["/myapp/prod"],
      "Keys": []
    },
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [],
      "Prefix": null,
      "Optional": false
    },
    "AppConfig": {
      "ApplicationIdentifier": "my-app",
      "UseLambdaCacheLayer": false,
      "ConfigurationProfiles": []
    }
  }
}

Usage Examples

1. Parameter Store Configuration

Simple Path-Based Loading

Load all parameters under a specific path prefix:

{
  "AwsSettings": {
    "ParameterStore": {
      "Paths": ["/myservice"]
    }
  }
}

If your Parameter Store contains:

/myservice/Database/ConnectionString = "Server=..."
/myservice/Database/MaxPoolSize = "100"
/myservice/Api/Endpoint = "https://api.example.com"

They will be mapped to:

{
  "Database": {
    "ConnectionString": "Server=...",
    "MaxPoolSize": "100"
  },
  "Api": {
    "Endpoint": "https://api.example.com"
  }
}

Custom Key Mapping with Aliases

Use custom aliases to map Parameter Store keys to cleaner configuration names:

{
  "AwsSettings": {
    "ParameterStore": {
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/prod-db-credentials",
          "Alias": "Database:ConnectionString"
        },
        {
          "Path": "/myservice/config/api-key",
          "Alias": "ApiSettings:Key",
          "Optional": true
        }
      ]
    }
  }
}

Loading Secrets Manager via Parameter Store

Reference Secrets Manager values through Parameter Store:

{
  "AwsSettings": {
    "ParameterStore": {
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/my-secret",
          "Alias": "MySecret"
        }
      ]
    }
  }
}

2. Secrets Manager Configuration

Load All Secrets

Load all secrets from Secrets Manager:

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": true,
      "Optional": false
    }
  }
}

Load Specific Secrets by ARN

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/database",
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/api-keys"
      ]
    }
  }
}

Load Secrets with Prefix

Filter secrets by name prefix:

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": true,
      "Prefix": "prod/myapp/"
    }
  }
}

3. AppConfig Configuration

Load AppConfig Profiles

{
  "AwsSettings": {
    "AppConfig": {
      "ApplicationIdentifier": "my-application",
      "ConfigurationProfiles": [
        {
          "Identifier": "my-config-profile",
          "Optional": false
        },
        {
          "Identifier": "feature-flags",
          "Optional": true
        }
      ]
    }
  }
}

With Lambda Cache Layer

For AWS Lambda functions, enable the cache layer for improved performance:

{
  "AwsSettings": {
    "AppConfig": {
      "ApplicationIdentifier": "my-application",
      "UseLambdaCacheLayer": true,
      "ConfigurationProfiles": [
        {
          "Identifier": "my-config-profile"
        }
      ]
    }
  }
}

4. Auto-Reload Configuration

Enable automatic reloading of configuration at specified intervals:

{
  "AwsSettings": {
    "ReloadAfter": "00:05:00",  // Reload every 5 minutes
    "ParameterStore": {
      "Paths": ["/myapp"]
    }
  }
}

5. Environment-Specific Configuration

The library respects the ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT variables:

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings() // Automatically uses current environment
    .Build();

Or specify the environment explicitly:

var configuration = new ConfigurationBuilder()
    .AddAwsSettings(environmentName: "Production")
    .Build();

6. Using Configuration in Your Application

Bind to Strongly-Typed Options

public class DatabaseSettings
{
    public string ConnectionString { get; set; }
    public int MaxPoolSize { get; set; }
}

// In Program.cs
services.Configure<DatabaseSettings>(
    configuration.GetSection("Database")
);

// In your service
public class MyService
{
    private readonly DatabaseSettings _settings;
    
    public MyService(IOptions<DatabaseSettings> options)
    {
        _settings = options.Value;
    }
}

Direct Configuration Access

var connectionString = configuration["Database:ConnectionString"];
var apiEndpoint = configuration["Api:Endpoint"];

Using GetSettings Extension Method

var awsSettings = configuration.GetSettings<AwsSettings>();

7. With Logging

Enable logging to see what configuration is being loaded:

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder => 
{
    builder.AddConsole();
});

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

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings(logger)
    .Build();

Complete Example

Here's a complete example combining multiple AWS configuration sources:

{
  "AwsSettings": {
    "ReloadAfter": "00:10:00",
    "ParameterStore": {
      "Paths": ["/myapp/prod"],
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/db-connection",
          "Alias": "Database:ConnectionString"
        }
      ]
    },
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:api-keys"
      ]
    },
    "AppConfig": {
      "ApplicationIdentifier": "myapp",
      "ConfigurationProfiles": [
        {
          "Identifier": "application-config"
        },
        {
          "Identifier": "feature-flags"
        }
      ]
    }
  }
}

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        config.AddJsonFile("appsettings.json");
        config.AddAwsSettings(context.HostingEnvironment.EnvironmentName);
    })
    .ConfigureServices((context, services) =>
    {
        // Configure your services using the loaded configuration
        services.Configure<DatabaseSettings>(
            context.Configuration.GetSection("Database")
        );
        services.Configure<ApiSettings>(
            context.Configuration.GetSection("Api")
        );
    })
    .Build();

await host.RunAsync();

AWS Permissions Required

Ensure your application has the necessary AWS IAM permissions:

Parameter Store

{
  "Effect": "Allow",
  "Action": [
    "ssm:GetParameter",
    "ssm:GetParameters",
    "ssm:GetParametersByPath"
  ],
  "Resource": "arn:aws:ssm:*:*:parameter/myapp/*"
}

Secrets Manager

{
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue",
    "secretsmanager:ListSecrets"
  ],
  "Resource": "arn:aws:secretsmanager:*:*:secret:*"
}

AppConfig

{
  "Effect": "Allow",
  "Action": [
    "appconfig:GetConfiguration",
    "appconfig:StartConfigurationSession"
  ],
  "Resource": "*"
}

Best Practices

Use Parameter Store paths for hierarchical configuration - Organize your parameters by environment and service
Use Secrets Manager for sensitive data - Store passwords, API keys, and certificates in Secrets Manager
Enable auto-reload for dynamic configuration - Set appropriate ReloadAfter intervals for configuration that changes
Use AppConfig for feature flags - Leverage AppConfig for runtime feature toggles
Set optional flags appropriately - Mark non-critical configuration as optional to prevent startup failures
Use environment-specific prefixes - Organize parameters like /myapp/prod/... and /myapp/dev/...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source. Please check the repository for license details.

Opc.AwsSettings

An opinionated .NET Standard 2.0 library that provides support for all AWS settings options including Parameter Store, Secrets Manager, AppConfig Freeform and AppConfig Feature Flags.

Opc.AwsSettings

A .NET library that simplifies loading configuration from AWS services including Parameter Store, Secrets Manager, and AppConfig into your application's configuration system.

Features

🔧 AWS Systems Manager Parameter Store - Load configuration from hierarchical parameters
🔐 AWS Secrets Manager - Securely load secrets into your configuration
⚙️ AWS AppConfig - Load feature flags and freeform configuration
🔄 Auto-reload - Optionally reload configuration at specified intervals
🎯 Easy Integration - Seamlessly integrates with .NET's IConfiguration system
🌍 Environment-aware - Support for environment-specific configurations

Installation

Install the NuGet package:

dotnet add package Opc.AwsSettings

Quick Start

Basic Usage with Host Builder

using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings() // Add AWS configuration sources
    .ConfigureServices(services =>
    {
        // Your service configuration
    })
    .Build();

await host.RunAsync();

Manual Configuration Builder Usage

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddAwsSettings() // Add AWS configuration sources
    .Build();

Configuration

Configure the library using the AwsSettings section in your appsettings.json:

{
  "AwsSettings": {
    "ReloadAfter": "00:05:00",
    "ParameterStore": {
      "Paths": ["/myapp/prod"],
      "Keys": []
    },
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [],
      "Prefix": null,
      "Optional": false
    },
    "AppConfig": {
      "ApplicationIdentifier": "my-app",
      "UseLambdaCacheLayer": false,
      "ConfigurationProfiles": []
    }
  }
}

Usage Examples

1. Parameter Store Configuration

Simple Path-Based Loading

Load all parameters under a specific path prefix:

{
  "AwsSettings": {
    "ParameterStore": {
      "Paths": ["/myservice"]
    }
  }
}

If your Parameter Store contains:

/myservice/Database/ConnectionString = "Server=..."
/myservice/Database/MaxPoolSize = "100"
/myservice/Api/Endpoint = "https://api.example.com"

They will be mapped to:

{
  "Database": {
    "ConnectionString": "Server=...",
    "MaxPoolSize": "100"
  },
  "Api": {
    "Endpoint": "https://api.example.com"
  }
}

Custom Key Mapping with Aliases

Use custom aliases to map Parameter Store keys to cleaner configuration names:

{
  "AwsSettings": {
    "ParameterStore": {
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/prod-db-credentials",
          "Alias": "Database:ConnectionString"
        },
        {
          "Path": "/myservice/config/api-key",
          "Alias": "ApiSettings:Key",
          "Optional": true
        }
      ]
    }
  }
}

Loading Secrets Manager via Parameter Store

Reference Secrets Manager values through Parameter Store:

{
  "AwsSettings": {
    "ParameterStore": {
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/my-secret",
          "Alias": "MySecret"
        }
      ]
    }
  }
}

2. Secrets Manager Configuration

Load All Secrets

Load all secrets from Secrets Manager:

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": true,
      "Optional": false
    }
  }
}

Load Specific Secrets by ARN

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/database",
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/api-keys"
      ]
    }
  }
}

Load Secrets with Prefix

Filter secrets by name prefix:

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": true,
      "Prefix": "prod/myapp/"
    }
  }
}

3. AppConfig Configuration

Load AppConfig Profiles

{
  "AwsSettings": {
    "AppConfig": {
      "ApplicationIdentifier": "my-application",
      "ConfigurationProfiles": [
        {
          "Identifier": "my-config-profile",
          "Optional": false
        },
        {
          "Identifier": "feature-flags",
          "Optional": true
        }
      ]
    }
  }
}

With Lambda Cache Layer

For AWS Lambda functions, enable the cache layer for improved performance:

{
  "AwsSettings": {
    "AppConfig": {
      "ApplicationIdentifier": "my-application",
      "UseLambdaCacheLayer": true,
      "ConfigurationProfiles": [
        {
          "Identifier": "my-config-profile"
        }
      ]
    }
  }
}

4. Auto-Reload Configuration

Enable automatic reloading of configuration at specified intervals:

{
  "AwsSettings": {
    "ReloadAfter": "00:05:00",  // Reload every 5 minutes
    "ParameterStore": {
      "Paths": ["/myapp"]
    }
  }
}

5. Environment-Specific Configuration

The library respects the ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT variables:

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings() // Automatically uses current environment
    .Build();

Or specify the environment explicitly:

var configuration = new ConfigurationBuilder()
    .AddAwsSettings(environmentName: "Production")
    .Build();

6. Using Configuration in Your Application

Bind to Strongly-Typed Options

public class DatabaseSettings
{
    public string ConnectionString { get; set; }
    public int MaxPoolSize { get; set; }
}

// In Program.cs
services.Configure<DatabaseSettings>(
    configuration.GetSection("Database")
);

// In your service
public class MyService
{
    private readonly DatabaseSettings _settings;
    
    public MyService(IOptions<DatabaseSettings> options)
    {
        _settings = options.Value;
    }
}

Direct Configuration Access

var connectionString = configuration["Database:ConnectionString"];
var apiEndpoint = configuration["Api:Endpoint"];

Using GetSettings Extension Method

var awsSettings = configuration.GetSettings<AwsSettings>();

7. With Logging

Enable logging to see what configuration is being loaded:

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder => 
{
    builder.AddConsole();
});

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

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings(logger)
    .Build();

Complete Example

Here's a complete example combining multiple AWS configuration sources:

{
  "AwsSettings": {
    "ReloadAfter": "00:10:00",
    "ParameterStore": {
      "Paths": ["/myapp/prod"],
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/db-connection",
          "Alias": "Database:ConnectionString"
        }
      ]
    },
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:api-keys"
      ]
    },
    "AppConfig": {
      "ApplicationIdentifier": "myapp",
      "ConfigurationProfiles": [
        {
          "Identifier": "application-config"
        },
        {
          "Identifier": "feature-flags"
        }
      ]
    }
  }
}

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        config.AddJsonFile("appsettings.json");
        config.AddAwsSettings(context.HostingEnvironment.EnvironmentName);
    })
    .ConfigureServices((context, services) =>
    {
        // Configure your services using the loaded configuration
        services.Configure<DatabaseSettings>(
            context.Configuration.GetSection("Database")
        );
        services.Configure<ApiSettings>(
            context.Configuration.GetSection("Api")
        );
    })
    .Build();

await host.RunAsync();

AWS Permissions Required

Ensure your application has the necessary AWS IAM permissions:

Parameter Store

{
  "Effect": "Allow",
  "Action": [
    "ssm:GetParameter",
    "ssm:GetParameters",
    "ssm:GetParametersByPath"
  ],
  "Resource": "arn:aws:ssm:*:*:parameter/myapp/*"
}

Secrets Manager

{
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue",
    "secretsmanager:ListSecrets"
  ],
  "Resource": "arn:aws:secretsmanager:*:*:secret:*"
}

AppConfig

{
  "Effect": "Allow",
  "Action": [
    "appconfig:GetConfiguration",
    "appconfig:StartConfigurationSession"
  ],
  "Resource": "*"
}

Best Practices

Use Parameter Store paths for hierarchical configuration - Organize your parameters by environment and service
Use Secrets Manager for sensitive data - Store passwords, API keys, and certificates in Secrets Manager
Enable auto-reload for dynamic configuration - Set appropriate ReloadAfter intervals for configuration that changes
Use AppConfig for feature flags - Leverage AppConfig for runtime feature toggles
Set optional flags appropriately - Mark non-critical configuration as optional to prevent startup failures
Use environment-specific prefixes - Organize parameters like /myapp/prod/... and /myapp/dev/...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source. Please check the repository for license details.

Opc.AwsSettings

An opinionated .NET Standard 2.0 library that provides support for all AWS settings options including Parameter Store, Secrets Manager, AppConfig Freeform and AppConfig Feature Flags.

olavocastro/Opc.AwsSettingsv1.2.3

Get Started

Readme

Opc.AwsSettings

Features

Installation

Quick Start

Basic Usage with Host Builder

Manual Configuration Builder Usage

Configuration

Usage Examples

1. Parameter Store Configuration

Simple Path-Based Loading

Custom Key Mapping with Aliases

Loading Secrets Manager via Parameter Store

2. Secrets Manager Configuration

Load All Secrets

Load Specific Secrets by ARN

Load Secrets with Prefix

3. AppConfig Configuration

Load AppConfig Profiles

With Lambda Cache Layer

4. Auto-Reload Configuration

5. Environment-Specific Configuration

6. Using Configuration in Your Application

Bind to Strongly-Typed Options

Direct Configuration Access

Using GetSettings Extension Method

7. With Logging

Complete Example

AWS Permissions Required

Parameter Store

Secrets Manager

AppConfig

Best Practices

Contributing

License

Links

Opc.AwsSettings

olavocastro/Opc.AwsSettingsv1.2.3

Get Started

Readme

Opc.AwsSettings

Features

Installation

Quick Start

Basic Usage with Host Builder

Manual Configuration Builder Usage

Configuration

Usage Examples

1. Parameter Store Configuration

Simple Path-Based Loading

Custom Key Mapping with Aliases

Loading Secrets Manager via Parameter Store

2. Secrets Manager Configuration

Load All Secrets

Load Specific Secrets by ARN

Load Secrets with Prefix

3. AppConfig Configuration

Load AppConfig Profiles

With Lambda Cache Layer

4. Auto-Reload Configuration

5. Environment-Specific Configuration

6. Using Configuration in Your Application

Bind to Strongly-Typed Options

Direct Configuration Access

Using GetSettings Extension Method

7. With Logging

Complete Example

AWS Permissions Required

Parameter Store

Secrets Manager

AppConfig

Best Practices

Contributing

License

Links

Opc.AwsSettings