.NET Core configuration provider for AWS Systems Manager

Today, we released a new NuGet package, Amazon.Extensions.Configuration.SystemsManager. This NuGet package simplifies how your application loads the application configuration settings in the AWS Systems Manager Parameter Store into the .NET Core configuration system.

Configuration in .NET Core is quite different from what we’re used to in the .NET Framework. With the .NET Framework, we had only app.config/web.config as our configuration source and, for any other sources, we had to create our custom configuration solution.

The .NET Core configuration system was built to be extensible. For example, when you create an ASP.NET Core application, by default it pulls configuration information from your appsettings.json file, command line arguments, and environment variables. You can also plug in other configuration source providers and then let your application access the configuration with the same interface.

AWS Systems Manager Parameter Store provides secure hierarchical storage for configuration data management and secrets management. Using Parameter Store, you can safely store application configurations separately from your application’s code.

Let’s look at how you can start using Amazon.Extensions.Configuration.SystemsManager.

Getting started

To get started, let’s first add some configuration data. To do that, log in to the Parameter store console and choose Create Parameter to create our first application configuration value.

Here you can see we created a new config parameter for a database connection string stored as a secure string by using AWS Key Management Service (AWS KMS). Notice the prefix to the parameter name is /myapplication. When we configure Parameter Store for our .NET Core application, we’ll have all the parameters that start with /myapplication added to the application’s configuration.

To get this configuration data into our application we next need to add the Amazon.Extensions.Configuration.SystemsManager NuGet package. This package is a configuration provider for the .NET Core configuration system.

Then, we need to enable this new configuration provider in our code. For an ASP.NET Core application, you can do this in the Program.cs file and edit the creation of the WebHost to call ConfigureAppConfiguration to add configuration providers.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration(builder =>
        {
            builder.AddSystemsManager("/myapplication");
        })
        .UseStartup<Startup>();

Here, we add all of the parameters from Parameter Store starting with /myapplication, which includes the database connection string we added earlier, into the .NET Core configuration system.

Advanced settings

We just saw the easy way to add parameters from Parameter Store into .NET Core’s configuration system. You can also use one of the overloads for AddSystemManager to configure the frequency to reload the configuration data, to determine how to handle errors getting the configuration data, and to specify what AWS credentials and AWS Region to use when calling the Systems Manager Parameter Store.

The following snippet shows how you could set these parameters.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration(builder =>
        {
            builder.AddSystemsManager(configureSource =>
            {
                // Parameter Store prefix to pull configuration data from.
                configureSource.Path = "/myapplication";

                // Reload configuration data every 5 minutes.
                configureSource.ReloadAfter = TimeSpan.FromMinutes(5);

                // Use custom logic to set AWS credentials and Region. Otherwise, the AWS SDK for .NET's default logic
                // will be used find credentials.
                configureSource.AwsOptions = awsOptions;

                // Configure if the configuration data is optional.
                configureSource.Optional = true;

                configureSource.OnLoadException += exceptionContext =>
                {
                    // Add custom error handling. For example, look at the exceptionContext.Exception and decide
                    // whether to ignore the error or tell the provider to attempt to reload.
                };

                // Implement custom parameter process, which transforms Parameter Store names into
                // names for the .NET Core configuration system.
                configureSource.ParameterProcessor = customerProcess;
            });
        })
        .UseStartup<Startup>();

Feedback

This library was created by Ken Hundley from the AWS .NET open source community. He has graciously donated this library to the AWS .NET team to own and maintain. Thanks to Ken for helping us make AWS and .NET work great together.

You can find the GitHub repository here, https://github.com/aws/aws-dotnet-extensions-configuration. We appreciate hearing the community’s feedback.