Developer Guide

Configuring the AWS SDK for .NET with .NET Core

One of the biggest changes in .NET Core is the removal of ConfigurationManager and the standard app.config and web.config files that were used ubiquitously with .NET Framework and ASP.NET applications. For traditional .NET applications, the AWS SDK for .NET uses this configuration system to set things like AWS credentials and region so that you don't have to do this in code.

The configuration system in .NET Core allows any type of input source from any location. Also, the configuration object isn't a global singleton like the ConfigurationManager in standard .NET applications, so the AWS SDK for .NET doesn't have access to read settings from it.


For background on the .NET Core configuration system, read the Configuration topic in the .NET Core documentation.

To make it easy to use the AWS SDK for .NET with .NET Core, you can use the AWSSDK.Extensions.NETCore.Setup NuGet package. Like many .NET Core libraries, it adds extension methods to the IConfiguration interface to make getting the AWS configuration seamless.

Using AWSSDK.Extensions.NETCore.Setup

When you create an ASP.NET Core MVC application in Visual Studio, the constructor for Startup.cs handles configuration by reading in various input sources, using the ConfigurationBuilder and setting the Configuration property to the built IConfiguration object.

public Startup(IHostingEnvironment env) { var builder = new ConfigurationBuilder() .SetBasePath(env.ContentRootPath) .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true) .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true) .AddEnvironmentVariables(); Configuration = builder.Build(); }

To use the Configuration object to get the AWS options, first add the AWSSDK.Extensions.NETCore.Setup NuGet package. Then, add your options to the configuration file. Notice one of the files added to the ConfigurationBuilder is called $"appsettings.{env.EnvironmentName}.json". If you look at the Debug tab in your project's properties, you can see this file is set to Development. This works great for local testing because you can put your configuration in the appsettings.Development.json file, which is read-only during local testing. When you deploy an Amazon EC2 instance that has EnvironmentName set to Production, this file is ignored and the AWS SDK for .NET falls back to the IAM credentials and region configured for the Amazon EC2 instance.

The configuration below shows an example of the values you can add in the appsettings.Development.json file in your project to supply AWS settings.

{ "AWS": { "Profile": "local-test-profile", "Region": "us-west-2" } }

To access the AWS options set in the file from code, call the GetAWSOptions extension method added on IConfiguration. To construct a service client from these options, call CreateServiceClient. The following example code shows how to create an Amazon S3 service client.

var options = Configuration.GetAWSOptions(); IAmazonS3 client = options.CreateServiceClient<IAmazonS3>();

Allowed Values in appsettings File

The following app configuration values can be set in the appsettings.Development.json file. The field names must use the casing shown in the list below. For details on these settings, refer to the AWS.Runtime.ClientConfg class.

  • Region

  • Profile

  • ProfilesLocation

  • SignatureVersion

  • RegionEndpoint

  • UseHttp

  • ServiceURL

  • AuthenticationRegion

  • AuthenticationServiceName

  • MaxErrorRetry

  • LogResponse

  • BufferSize

  • ProgressUpdateInterval

  • ResignRetries

  • AllowAutoRedirect

  • LogMetrics

  • DisableLogging

  • UseDualstackEndpoint

ASP.NET Core Dependency Injection

The AWSSDK.Extensions.NETCore.Setup NuGet package also integrates with a new dependency injection system in ASP.NET Core. The ConfigureServices method in Startup is where the MVC services are added. If the application is using Entity Framework, this is also where that is initialized.

public void ConfigureServices(IServiceCollection services) { // Add framework services. services.AddMvc(); }


Background on dependency injection in .NET Core is available on the .NET Coredocumentation site.

The AWSSDK.Extensions.NETCore.Setup NuGet package adds new extension methods to IServiceCollection that you can use to add AWS services to the dependency injection. The following code shows how to add the AWS options that are read from IConfiguration to add Amazon S3 and DynamoDB to our list of services.

public void ConfigureServices(IServiceCollection services) { // Add framework services. services.AddMvc(); services.AddDefaultAWSOptions(Configuration.GetAWSOptions()); services.AddAWSService<IAmazonS3>(); services.AddAWSService<IAmazonDynamoDB>(); }

Now, if your MVC controllers use either IAmazonS3 or IAmazonDynamoDB as parameters in their constructors, the dependency injection system passes in those services.

public class HomeController : Controller { IAmazonS3 S3Client { get; set; } public HomeController(IAmazonS3 s3Client) { this.S3Client = s3Client; } ... }