Skip to Content
Cloud Engineering Academy
3. .NET Application Development on AWS

AWS clients and dependency injection

Register AWS SDK v4 clients in ASP.NET Core with AWSSDK.Extensions.NETCore.Setup: default options from configuration, per-client tuning, keyed clients for a second Region, correct lifetimes, per-environment settings, and tests that run without an AWS account.

intermediate⏱ 1 h 30 min🟢 FreeDVA-C03

Assumes: .NET 10 LTS · AWS SDK for .NET v4 (AWSSDK.Extensions.NETCore.Setup 4.1.0.2, AWSSDK.S3 4.1.1) · xUnit v3 4.0.3 · NSubstitute 6.2.0 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Register AWS service clients with AddDefaultAWSOptions, AddAWSService and AddKeyedAWSService, and explain what each overload does.
  • Read AWS settings (Region, Profile, ServiceURL, retries) from the AWS configuration section and vary them per environment without code changes.
  • Choose the right client lifetime (singleton) and explain what goes wrong with scoped or transient clients.
  • Register two clients for the same service in different Regions, for a UK bank and its EU subsidiary.
  • Know when the SDK resolves credentials for a DI-created client, and how that affects startup checks and tests.
  • Unit-test code that uses IAmazonS3 with NSubstitute, replace application services with fakes in WebApplicationFactory tests, and keep real-AWS tests behind RUN_AWS_TESTS=1.

Prerequisites

  • AWS SDK for .NET v4 in depth — clients, credential chain, retries
  • ASP.NET Core dependency injection and the options pattern (IOptions, IConfiguration)
  • Tools: .NET 10 SDK or Docker, AWS CLI v2 with learn-sandbox

Why this matters in banking

Harbourline's Payments team reviewed a production incident in which an API's p99 latency climbed from 40 ms to 3 seconds every afternoon. Profiling showed thousands of sockets in TIME_WAIT. A well-meant refactor had registered IAmazonDynamoDB as transient "so each request gets a fresh client". Every request built a new client, a new HTTP handler and a new credential resolver, and the container ran out of ephemeral ports under load.

A second team had the opposite problem: their tests could not run in CI because every class created its own new AmazonS3Client() internally. Nothing could be replaced with a fake, so the tests needed real AWS credentials. The pipeline was given a long-lived access key "temporarily", and an auditor found it eighteen months later.

Registering clients properly through dependency injection fixes both problems. You get one client per service and configuration, settings that come from configuration rather than code, and interfaces you can replace in tests.

The idea in plain language

ASP.NET Core already has a container that builds your services and hands them to the classes that need them. The AWSSDK.Extensions.NETCore.Setup package teaches that container how to build AWS clients:

  1. AddDefaultAWSOptions stores one set of AWS settings (Region, profile, retry defaults). Usually you read them from the AWS section of configuration.
  2. AddAWSService<IAmazonS3>() registers a factory. The first time something asks for IAmazonS3, the factory creates an AmazonS3Client from those settings. Every later request gets the same instance.
  3. Your classes ask for the interface (IAmazonS3) in their constructor. In tests you pass a mock or a fake instead.

Analogy: think of the DI container as the bank's stationery cupboard. Instead of every clerk printing their own letterhead (a new client per request), the cupboard keeps one pre-printed stack per branch (one client per Region). The cupboard manager reads the branch list from the head-office memo (configuration). Auditors can swap the stack for a "SPECIMEN" stack (a fake) without retraining the clerks.

What problem the setup package solves

Without it you would write a factory for each client, decide how to read the Region and profile from configuration, and make sure each client is created once. The package gives you:

  • Configuration binding. IConfiguration.GetAWSOptions() reads the AWS section (or any section you name) into an AWSOptions object. Supported keys include Region, Profile, ProfilesLocation, ServiceURL, MaxErrorRetry, UseDualstackEndpoint, AuthenticationRegion, LogResponse and others. Casing must match.
  • Client factories. AddAWSService<T> uses the service interface to create the right client. In v4, on .NET 8 and later, this uses static interface methods instead of reflection, so it works with Native AOT and trimming.
  • Sensible lifetime. Clients are registered as singletons by default, which is what AWS recommends: clients are thread-safe and expensive to build.
  • Overrides. Per-client options (AddAWSService<T>(options)), a configuration callback (Action<ClientConfig, IServiceProvider>), TryAdd... variants for libraries, and keyed registrations (AddKeyedAWSService<T>(key, ...)) for several clients of the same type.

What the package does not do:

  • It does not validate your configuration at startup. A missing Region or unusable credentials surface when the client is first resolved, which may be the first HTTP request.
  • It does not register your own application services or options. You still write Configure<StatementOptions>(...).
  • It does not handle HttpClientFactory integration per client. In v4, DefaultClientConfig.HttpClientFactory was removed; set a custom factory globally with AWSConfigs.HttpClientFactory if you really need one.

When are credentials resolved?

This matters more than it sounds. In v4, the DI factory resolves credentials when it creates the client, that is, the first time the container hands out IAmazonS3. We observed this while writing the tests for this lesson: resolving the client in a container with no credentials threw

Amazon.Runtime.AmazonClientException : Failed to resolve AWS credentials. The credential providers used to search
for credentials returned the following errors:
  Exception 1 of 4: The environment variables AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN were not set...
  ...
   at Amazon.Extensions.NETCore.Setup.ClientFactory`1.CreateServiceClient(IServiceProvider provider)

Consequences:

  • Production: if the task role is missing, the failure appears on the first request that needs the client, not at startup. Add a readiness check that touches the dependency (see Health checks) so the load balancer never routes traffic to a broken task.
  • Tests: a test that resolves the real client needs some credentials, even fake ones. Set obviously fake environment variables in that test, or override AWSOptions.Credentials. Tests that replace the client or the service using it need nothing.
  • The credentials themselves are still temporary and refreshed in the background. Resolving the provider once at startup is not the same as freezing the keys.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Microsoft.Extensions.Azure → services.AddAzureClients(b => b.AddBlobServiceClient(...))AWSSDK.Extensions.NETCore.Setup → services.AddAWSService<IAmazonS3>()Azure binds per-client sections; AWS binds one default AWS section plus optional per-client AWSOptions
builder.UseCredential(new DefaultAzureCredential())Default credential chain, or AWSOptions.Credentials / ProfileAWS reads the profile name from configuration; no credential object is needed in the normal case
Named clients via IAzureClientFactory<T>.CreateClient("name")Keyed services: AddKeyedAWSService<IAmazonS3>("eu", ...) + [FromKeyedServices("eu")]AWS uses the standard .NET 8+ keyed DI feature rather than a custom factory
BlobServiceClient registered as a singletonAWS clients registered as singletonsSame rule, same reason: thread-safe, expensive, pooled connections
Azurite for local Blob Storage (UseDevelopmentStorage=true)ServiceURL override pointing at a local emulatorOnly in appsettings.Development.json. Check the emulator's licence terms before relying on it
Mocking BlobContainerClient (virtual methods)Mocking IAmazonS3 (an interface)AWS exposes interfaces for every client, so mocks are straightforward

Architecture

Security-boundary view. The UK and EU stores use different clients, Regions and buckets. In production, the EU path would normally run under a different IAM role, often in a different account, so a bug in routing cannot read the other entity's data. DI keeps those clients separate. IAM and account boundaries make the separation enforceable.

Step-by-step implementation

Create the API and add packages

dotnet new web -n Harbourline.Statements.Api -f net10.0
cd Harbourline.Statements.Api
dotnet add package AWSSDK.Extensions.NETCore.Setup --version 4.1.0.2
dotnet add package AWSSDK.S3 --version 4.1.1
dotnet add package AWSSDK.SSO --version 4.1.0.2
dotnet add package AWSSDK.SSOOIDC --version 4.1.0.2

Put AWS settings in configuration, per environment

appsettings.json holds what is true everywhere: the Regions and bucket names. appsettings.Development.json adds the SSO profile, which is used only on your laptop. In AWS, the environment is Production, no profile is set, and the default chain finds the task role.

Register the clients and your services

Call AddDefaultAWSOptions once, then AddAWSService for each client. Register the EU client with a key and its own AWSOptions. Your own services get the clients through their constructors.

Write tests that need no AWS account

Unit-test S3StatementStore with a mocked IAmazonS3. Test the endpoints with WebApplicationFactory and replace the stores with fakes. Add one test that proves the DI wiring: singleton lifetime and the right Region per client.

Run it against the sandbox (optional)

Create the two buckets from the IaC section, upload a fictional PDF to statements/ACC-0000000001/2026-10.pdf, then:

aws sso login --profile learn-sandbox
dotnet run --environment Development
curl http://localhost:5000/v1/uk/accounts/ACC-0000000001/statements

Use the port your app prints at startup.

AWS Console instructions

  • Console → S3 → Buckets → Create bucket. Create hl-m03-statements-uk-<yourname> in US East (N. Virginia). Keep Block all public access on, and default encryption SSE-S3. Add tags Project=cea-lab, Lab=m03-di, Environment=learn, Owner=<you>.
  • Repeat for hl-m03-statements-eu-<yourname> in Europe (Ireland) eu-west-1.
  • Bucket → Objects → Upload. Upload any small PDF as statements/ACC-0000000001/2026-10.pdf. Use a fictional document, never a real statement.
  • Update the bucket names in appsettings.Development.json to match yours (bucket names are global).

AWS CLI

# Create the two buckets (names are global: add your own suffix).
aws s3api create-bucket --bucket hl-m03-statements-uk-alex --region us-east-1 --profile learn-sandbox
aws s3api create-bucket --bucket hl-m03-statements-eu-alex --region eu-west-1 \
  --create-bucket-configuration LocationConstraint=eu-west-1 --profile learn-sandbox

# Tag them for cleanup.
for b in hl-m03-statements-uk-alex hl-m03-statements-eu-alex; do
  aws s3api put-bucket-tagging --bucket "$b" --profile learn-sandbox --tagging \
    'TagSet=[{Key=Project,Value=cea-lab},{Key=Lab,Value=m03-di},{Key=Environment,Value=learn},{Key=Owner,Value=alex}]'
done

# Upload a fictional statement.
aws s3 cp ./sample-statement.pdf s3://hl-m03-statements-uk-alex/statements/ACC-0000000001/2026-10.pdf --profile learn-sandbox

# Override configuration from the environment: double underscore = section separator.
# This is how ECS task definitions and Beanstalk set the same keys.
export AWS__Region=us-east-1
export Statements__UkBucketName=hl-m03-statements-uk-alex

Infrastructure as Code

Two private, encrypted, versioned buckets: one per legal entity and Region. In a real organisation these would live in different accounts. Here they share the sandbox.

StatementBucketsApp.cs
using Amazon.CDK;
using Amazon.CDK.AWS.S3;
using Constructs;

namespace Harbourline.Learn.Infra;

public sealed class StatementBucketStack : Stack
{
    public StatementBucketStack(Construct scope, string id, string bucketName, IStackProps props) : base(scope, id, props)
    {
        _ = new Bucket(this, "Statements", new BucketProps
        {
            BucketName = bucketName,
            BlockPublicAccess = BlockPublicAccess.BLOCK_ALL,
            Encryption = BucketEncryption.S3_MANAGED,
            EnforceSSL = true,                     // deny plain-HTTP requests in the bucket policy
            Versioned = true,
            ObjectOwnership = ObjectOwnership.BUCKET_OWNER_ENFORCED,
            // ⚠ Learning shortcut: destroy with the stack. Production statements: RETAIN, plus Object Lock if required.
            RemovalPolicy = RemovalPolicy.DESTROY,
            AutoDeleteObjects = true,
        });

        Amazon.CDK.Tags.Of(this).Add("Project", "cea-lab");
        Amazon.CDK.Tags.Of(this).Add("Lab", "m03-di");
        Amazon.CDK.Tags.Of(this).Add("Environment", "learn");
    }
}

public static class StatementBucketsApp
{
    public static void Main()
    {
        var app = new App();
        var account = System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT");
        _ = new StatementBucketStack(app, "hl-m03-statements-uk", "hl-m03-statements-uk-alex",
            new StackProps { Env = new Amazon.CDK.Environment { Account = account, Region = "us-east-1" } });
        _ = new StatementBucketStack(app, "hl-m03-statements-eu", "hl-m03-statements-eu-alex",
            new StackProps { Env = new Amazon.CDK.Environment { Account = account, Region = "eu-west-1" } });
        app.Synth();
    }
}

Complete code

The full project compiles with TreatWarningsAsErrors and all tests below pass with no AWS account (verified with dotnet test in the mcr.microsoft.com/dotnet/sdk:10.0 container).

appsettings.json
{
  "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } },
  "AllowedHosts": "*",
  "AWS": {
    "Region": "us-east-1"
  },
  "AwsEu": {
    "Region": "eu-west-1"
  },
  "Statements": {
    "UkBucketName": "hl-m03-statements-uk",
    "EuBucketName": "hl-m03-statements-eu",
    "UrlLifetime": "00:05:00",
    "CallTimeout": "00:00:05"
  }
}
appsettings.Development.json
{
  "AWS": {
    "Profile": "learn-sandbox"
  },
  "AwsEu": {
    "Profile": "learn-sandbox"
  },
  "Statements": {
    "UkBucketName": "hl-m03-statements-uk-alex",
    "EuBucketName": "hl-m03-statements-eu-alex"
  }
}
Program.cs
using Amazon.S3;
using Harbourline.Statements.Api;
using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);

// 1. Default AWS settings for every client: the "AWS" section (Region; Profile only in Development).
builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions());

// 2. The UK client uses the defaults plus client-specific tuning. Singleton is the default lifetime.
builder.Services.AddAWSService<IAmazonS3>((config, _) =>
{
    config.MaxErrorRetry = 3;
    config.ConnectTimeout = TimeSpan.FromSeconds(3);
});

// 3. A second S3 client for the EU subsidiary, pinned to an EU Region and resolved by key.
builder.Services.AddKeyedAWSService<IAmazonS3>("eu", builder.Configuration.GetAWSOptions("AwsEu"));

// 4. Application services: one store per legal entity, each with its own client and bucket.
builder.Services.Configure<StatementOptions>(builder.Configuration.GetSection(StatementOptions.SectionName));
builder.Services.AddKeyedSingleton<IStatementStore>("uk", (sp, _) =>
{
    var options = sp.GetRequiredService<IOptions<StatementOptions>>();
    return new S3StatementStore(sp.GetRequiredService<IAmazonS3>(), options.Value.UkBucketName, options);
});
builder.Services.AddKeyedSingleton<IStatementStore>("eu", (sp, _) =>
{
    var options = sp.GetRequiredService<IOptions<StatementOptions>>();
    return new S3StatementStore(sp.GetRequiredKeyedService<IAmazonS3>("eu"), options.Value.EuBucketName, options);
});

builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.MapStatementEndpoints();
app.Run();

public partial class Program;
StatementStore.cs
using System.Globalization;
using System.Text.RegularExpressions;
using Amazon.S3;
using Amazon.S3.Model;
using Microsoft.Extensions.Options;

namespace Harbourline.Statements.Api;

/// <summary>Settings bound from the "Statements" configuration section.</summary>
public sealed class StatementOptions
{
    public const string SectionName = "Statements";
    public string UkBucketName { get; set; } = "";
    public string EuBucketName { get; set; } = "";
    public TimeSpan UrlLifetime { get; set; } = TimeSpan.FromMinutes(5);
    public TimeSpan CallTimeout { get; set; } = TimeSpan.FromSeconds(5);
}

public sealed record StatementInfo(string AccountId, string Period, long SizeBytes, DateTime LastModifiedUtc);

/// <summary>What the endpoints depend on. Tests replace it with a fake; production uses S3.</summary>
public interface IStatementStore
{
    Task<IReadOnlyList<StatementInfo>> ListAsync(string accountId, CancellationToken cancellationToken);
    Task<Uri?> GetDownloadUrlAsync(string accountId, string period, CancellationToken cancellationToken);
}

/// <summary>Monthly PDF statements stored as statements/{accountId}/{yyyy-MM}.pdf, one bucket per legal entity.</summary>
public sealed partial class S3StatementStore(IAmazonS3 s3, string bucketName, IOptions<StatementOptions> options) : IStatementStore
{
    private readonly StatementOptions _options = options.Value;

    public async Task<IReadOnlyList<StatementInfo>> ListAsync(string accountId, CancellationToken cancellationToken)
    {
        // Per-call deadline that also respects the caller's token (e.g. the HTTP request being aborted).
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        cts.CancelAfter(_options.CallTimeout);

        var request = new ListObjectsV2Request { BucketName = bucketName, Prefix = $"statements/{accountId}/" };
        var results = new List<StatementInfo>();
        ListObjectsV2Response response;
        do
        {
            // A loop rather than a paginator, so unit tests can mock ListObjectsV2Async directly.
            response = await s3.ListObjectsV2Async(request, cts.Token);
            foreach (var obj in response.S3Objects ?? []) // SDK v4: null when there are no objects
            {
                var match = KeyPattern().Match(obj.Key);
                if (match.Success)
                {
                    results.Add(new StatementInfo(
                        accountId,
                        match.Groups["period"].Value,
                        obj.Size ?? 0,                          // v4: long? instead of long
                        obj.LastModified ?? DateTime.MinValue)); // v4: DateTime? instead of DateTime
                }
            }
            request.ContinuationToken = response.NextContinuationToken;
        }
        while (response.IsTruncated == true); // v4: bool? instead of bool

        return [.. results.OrderByDescending(s => s.Period, StringComparer.Ordinal)];
    }

    public async Task<Uri?> GetDownloadUrlAsync(string accountId, string period, CancellationToken cancellationToken)
    {
        if (!DateOnly.TryParseExact(period + "-01", "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out _))
        {
            return null;
        }

        // The key is built from validated parts and never taken from the caller, so a client
        // cannot ask for another customer's object (an insecure direct object reference).
        var url = await s3.GetPreSignedURLAsync(new GetPreSignedUrlRequest
        {
            BucketName = bucketName,
            Key = $"statements/{accountId}/{period}.pdf",
            Verb = HttpVerb.GET,
            Expires = DateTime.UtcNow.Add(_options.UrlLifetime),
        });
        return new Uri(url);
    }

    [GeneratedRegex(@"^statements/ACC-\d{10}/(?<period>\d{4}-\d{2})\.pdf$")]
    private static partial Regex KeyPattern();
}
StatementEndpoints.cs
using System.Text.RegularExpressions;
using Microsoft.AspNetCore.Http.HttpResults;

namespace Harbourline.Statements.Api;

public static partial class StatementEndpoints
{
    public static IEndpointRouteBuilder MapStatementEndpoints(this IEndpointRouteBuilder app)
    {
        // entity is "uk" (Harbourline Bank) or "eu" (the EU subsidiary); each entity's data stays in its own Region.
        var group = app.MapGroup("/v1/{entity:regex(^(uk|eu)$)}/accounts/{accountId}/statements");
        group.MapGet("/", ListAsync);
        group.MapGet("/{period}/download-url", DownloadUrlAsync);
        return app;
    }

    internal static async Task<Results<Ok<IReadOnlyList<StatementInfo>>, ProblemHttpResult>> ListAsync(
        string entity, string accountId, IServiceProvider services, CancellationToken ct)
    {
        if (!AccountId().IsMatch(accountId)) return BadAccountId();
        var store = services.GetRequiredKeyedService<IStatementStore>(entity);
        return TypedResults.Ok(await store.ListAsync(accountId, ct));
    }

    internal static async Task<Results<Ok<DownloadLink>, ProblemHttpResult>> DownloadUrlAsync(
        string entity, string accountId, string period, IServiceProvider services, CancellationToken ct)
    {
        if (!AccountId().IsMatch(accountId)) return BadAccountId();
        var store = services.GetRequiredKeyedService<IStatementStore>(entity);
        var url = await store.GetDownloadUrlAsync(accountId, period, ct);
        return url is null
            ? TypedResults.Problem(statusCode: 400, title: "Invalid period", detail: "Use yyyy-MM, for example 2026-10.")
            : TypedResults.Ok(new DownloadLink(url));
    }

    private static ProblemHttpResult BadAccountId() =>
        TypedResults.Problem(statusCode: 400, title: "Invalid account id", detail: "Account ids look like ACC-0000000001.");

    [GeneratedRegex(@"^ACC-\d{10}$")]
    private static partial Regex AccountId();
}

public sealed record DownloadLink(Uri Url);

The test project uses xUnit v3 on Microsoft.Testing.Platform, exactly as the module labs do (OutputType Exe, no Microsoft.NET.Test.Sdk, and global.json selecting the MTP runner).

tests/Harbourline.Statements.Api.Tests/Harbourline.Statements.Api.Tests.csproj
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <IsPackable>false</IsPackable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="xunit.v3" Version="4.0.3" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.15" />
    <PackageReference Include="NSubstitute" Version="6.2.0" />
  </ItemGroup>
  <ItemGroup>
    <Using Include="Xunit" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\..\src\Harbourline.Statements.Api\Harbourline.Statements.Api.csproj" />
  </ItemGroup>
</Project>
tests/Harbourline.Statements.Api.Tests/StatementTests.cs
using System.Net;
using System.Net.Http.Json;
using Amazon;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;
using Harbourline.Statements.Api;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Options;
using NSubstitute;

namespace Harbourline.Statements.Api.Tests;

public class S3StatementStoreTests
{
    private static CancellationToken Ct => TestContext.Current.CancellationToken;
    private readonly IAmazonS3 _s3 = Substitute.For<IAmazonS3>();
    private readonly S3StatementStore _store;

    public S3StatementStoreTests() =>
        _store = new S3StatementStore(_s3, "hl-m03-statements-uk", Options.Create(new StatementOptions()));

    [Fact]
    public async Task Follows_continuation_tokens_and_ignores_unexpected_keys()
    {
        _s3.ListObjectsV2Async(Arg.Is<ListObjectsV2Request>(r => r.ContinuationToken == null), Arg.Any<CancellationToken>())
            .Returns(new ListObjectsV2Response
            {
                S3Objects = [Obj("statements/ACC-0000000001/2026-09.pdf"), Obj("statements/ACC-0000000001/notes.txt")],
                IsTruncated = true,
                NextContinuationToken = "page-2",
            });
        _s3.ListObjectsV2Async(Arg.Is<ListObjectsV2Request>(r => r.ContinuationToken == "page-2"), Arg.Any<CancellationToken>())
            .Returns(new ListObjectsV2Response { S3Objects = [Obj("statements/ACC-0000000001/2026-10.pdf")], IsTruncated = false });

        var result = await _store.ListAsync("ACC-0000000001", Ct);

        Assert.Equal(["2026-10", "2026-09"], result.Select(s => s.Period));
    }

    [Fact]
    public async Task Returns_empty_list_when_sdk_v4_returns_null_collection()
    {
        _s3.ListObjectsV2Async(Arg.Any<ListObjectsV2Request>(), Arg.Any<CancellationToken>())
            .Returns(new ListObjectsV2Response { S3Objects = null, IsTruncated = false });

        Assert.Empty(await _store.ListAsync("ACC-0000000002", Ct));
    }

    [Fact]
    public async Task Builds_the_presigned_key_itself_and_rejects_bad_periods()
    {
        _s3.GetPreSignedURLAsync(Arg.Any<GetPreSignedUrlRequest>()).Returns("https://example.com/signed");

        Assert.Null(await _store.GetDownloadUrlAsync("ACC-0000000001", "../../other", Ct));
        Assert.NotNull(await _store.GetDownloadUrlAsync("ACC-0000000001", "2026-10", Ct));
        await _s3.Received(1).GetPreSignedURLAsync(Arg.Is<GetPreSignedUrlRequest>(r =>
            r.Key == "statements/ACC-0000000001/2026-10.pdf" && r.Verb == HttpVerb.GET));
    }

    private static S3Object Obj(string key) => new() { Key = key, Size = 52_000, LastModified = new DateTime(2026, 11, 1, 0, 0, 0, DateTimeKind.Utc) };
}

public class DependencyInjectionTests
{
    [Fact]
    public void Clients_are_singletons_and_the_eu_client_uses_the_eu_region()
    {
        // The DI factory resolves credentials when it builds the client, so give it obviously fake
        // ones. Nothing is sent to AWS in this test.
        Environment.SetEnvironmentVariable("AWS_ACCESS_KEY_ID", "AKIAFAKEFAKEFAKEFAKE");
        Environment.SetEnvironmentVariable("AWS_SECRET_ACCESS_KEY", "fake-secret-for-unit-tests");

        using var factory = new WebApplicationFactory<Program>();
        var services = factory.Services;

        var uk1 = services.GetRequiredService<IAmazonS3>();
        var uk2 = services.GetRequiredService<IAmazonS3>();
        var eu = services.GetRequiredKeyedService<IAmazonS3>("eu");

        Assert.Same(uk1, uk2);
        Assert.Equal(RegionEndpoint.USEast1, uk1.Config.RegionEndpoint);
        Assert.Equal(RegionEndpoint.EUWest1, eu.Config.RegionEndpoint);
        Assert.Equal(3, uk1.Config.MaxErrorRetry);
        Assert.Equal(RequestRetryMode.Standard, eu.Config.RetryMode);
    }
}

public class EndpointTests
{
    private static CancellationToken Ct => TestContext.Current.CancellationToken;

    private sealed class FakeStore : IStatementStore
    {
        public Task<IReadOnlyList<StatementInfo>> ListAsync(string accountId, CancellationToken cancellationToken) =>
            Task.FromResult<IReadOnlyList<StatementInfo>>([new(accountId, "2026-10", 1024, DateTime.UnixEpoch)]);

        public Task<Uri?> GetDownloadUrlAsync(string accountId, string period, CancellationToken cancellationToken) =>
            Task.FromResult<Uri?>(new Uri($"https://example.com/{accountId}/{period}"));
    }

    private static WebApplicationFactory<Program> CreateFactory() =>
        new WebApplicationFactory<Program>().WithWebHostBuilder(b => b.ConfigureServices(services =>
        {
            // Replace the S3-backed stores with fakes: no AWS account or network needed.
            services.RemoveAllKeyed<IStatementStore>("uk");
            services.RemoveAllKeyed<IStatementStore>("eu");
            services.AddKeyedSingleton<IStatementStore, FakeStore>("uk");
            services.AddKeyedSingleton<IStatementStore, FakeStore>("eu");
        }));

    [Fact]
    public async Task Lists_statements_for_a_valid_account()
    {
        using var factory = CreateFactory();
        var client = factory.CreateClient();

        var list = await client.GetFromJsonAsync<List<StatementInfo>>("/v1/uk/accounts/ACC-0000000001/statements", Ct);

        Assert.Equal("2026-10", Assert.Single(list!).Period);
    }

    [Theory]
    [InlineData("/v1/uk/accounts/not-an-id/statements", HttpStatusCode.BadRequest)]
    [InlineData("/v1/us/accounts/ACC-0000000001/statements", HttpStatusCode.NotFound)]
    public async Task Rejects_bad_input(string path, HttpStatusCode expected)
    {
        using var factory = CreateFactory();
        var response = await factory.CreateClient().GetAsync(path, Ct);
        Assert.Equal(expected, response.StatusCode);
    }
}

Run the tests from the solution folder with dotnet test --solution <Name>.slnx. To run them without installing .NET, use the Docker command from CONVENTIONS.md.

Code explained line by line

Program.cs

  1. AddDefaultAWSOptions(builder.Configuration.GetAWSOptions()) reads the AWS section into an AWSOptions object and registers it. Every client created by AddAWSService without its own options uses it. Because configuration is layered, appsettings.Development.json can add Profile and an environment variable such as AWS__Region can override the Region, with no code change.
  2. AddAWSService<IAmazonS3>((config, _) => { ... }) registers the UK client as a singleton (the default lifetime). The callback runs once, when the client is created, and lets you tune that client's ClientConfig. The second parameter is the IServiceProvider, in case the tuning depends on other services.
  3. AddKeyedAWSService<IAmazonS3>("eu", GetAWSOptions("AwsEu")) registers a second IAmazonS3, distinguished by the key "eu", built from the AwsEu section. Without keys, a second AddAWSService<IAmazonS3> would simply replace the first registration for constructor injection.
  4. Configure<StatementOptions>(...) is ordinary .NET options binding for your own settings. AWS clients and app settings are configured the same way.
  5. AddKeyedSingleton<IStatementStore>("uk", (sp, _) => ...) builds the UK store with the UK client and bucket. The EU registration does the same with GetRequiredKeyedService<IAmazonS3>("eu"). Keeping the client choice in one place (composition root) makes the residency rule easy to review.

StatementStore.cs

  1. IStatementStore is the seam for tests. Endpoints depend on it, not on S3.
  2. S3StatementStore(IAmazonS3 s3, ...) depends on the interface IAmazonS3, so a test can pass a substitute.
  3. CreateLinkedTokenSource(cancellationToken) + CancelAfter combines the request-aborted token from ASP.NET Core with your own deadline.
  4. The do ... while (response.IsTruncated == true) loop follows NextContinuationToken. It is written out (not a paginator) because mocking ListObjectsV2Async is easy and mocking paginators is not.
  5. response.S3Objects ?? [], obj.Size ?? 0, obj.LastModified ?? DateTime.MinValue are the v4 nullable rules applied consistently.
  6. KeyPattern() is a source-generated regular expression. It filters out unexpected objects, such as a stray notes.txt in the prefix.
  7. GetPreSignedURLAsync creates a time-limited download link locally by signing it with the client's current credentials. No call is made to S3. The link carries the signer's permissions and expires at Expires or when the signing credentials expire, whichever comes first. Role credentials therefore cap a link's lifetime.
  8. The key is assembled from a validated account ID and period. Never accept a raw object key from a client. That is how one customer downloads another customer's statement.

StatementEndpoints.cs

  1. {entity:regex(^(uk|eu)$)} constrains the route, so /v1/us/... is a 404 before any code runs.
  2. services.GetRequiredKeyedService<IStatementStore>(entity) picks the store by key at request time. In a controller you could use [FromKeyedServices("eu")] on a constructor parameter when the key is fixed.
  3. TypedResults.Problem(...) returns RFC 9457 ProblemDetails, the Harbourline error convention.

Tests

  1. Substitute.For<IAmazonS3>() creates a mock of the whole client interface. Arg.Is<ListObjectsV2Request>(r => r.ContinuationToken == null) lets two calls return two different pages.
  2. S3Objects = null reproduces the v4 behaviour that breaks v3-era code. Keep this test forever.
  3. Received(1).GetPreSignedURLAsync(Arg.Is(... r.Key == ...)) proves the store built the key itself and rejected ../../other before signing anything.
  4. DependencyInjectionTests uses the real container. It sets fake credentials because, as shown above, the factory resolves credentials when it creates the client. It asserts the lifetime (Assert.Same), each client's Region and the per-client retry setting.
  5. RemoveAllKeyed<IStatementStore>("uk") then AddKeyedSingleton<IStatementStore, FakeStore>("uk") swaps the S3-backed stores for fakes inside WebApplicationFactory. The endpoint tests then exercise routing, validation and JSON without touching AWS.

Lifetimes: why singleton

LifetimeWhat happens with an AWS clientVerdict
Singleton (default)One client and one connection pool per configuration; credentials refreshed in the background✅ Use this
ScopedA new client per HTTP request: new handler, new credential provider, sockets not reused❌ Socket exhaustion and latency under load
TransientA new client every time one is injected, possibly several per request❌ Worse than scoped

Two related rules:

  • Never dispose an injected client (using var s3 = injectedClient is a bug). The container owns it and will dispose it at shutdown.
  • Singleton services may hold singleton clients. A scoped service may also depend on a singleton client. The reverse (a singleton depending on a scoped service) is the classic captive-dependency bug, unrelated to AWS but common in the same code.

Per-environment settings without code

EnvironmentWhere AWS settings come fromCredentials
Developer laptopappsettings.Development.json (AWS:Profile = learn-sandbox)SSO token cache via the profile
CI unit testsNo AWS settings needed; fakes and mocksNone (fake environment variables only where a real client is resolved)
CI integration testsRUN_AWS_TESTS=1 plus OIDC-federated rolePipeline role (Module 9)
ECS / Beanstalk / Lambdaappsettings.json plus environment variables (AWS__Region, Statements__UkBucketName)Task, instance or function role through the default chain
Local emulatorAWS:ServiceURL in appsettings.Development.json onlyDummy credentials accepted by the emulator

Gating real-AWS tests

Integration tests that call real AWS should skip themselves unless RUN_AWS_TESTS=1 is set. The lab labs/m03-accounts-api/tests/Harbourline.Accounts.Api.Tests/AwsSmokeTests.cs shows the pattern. CI runs the unit tests on every push, and the integration tests only in a job that has a federated role.

Security considerations

⚠ Learning shortcut — not for production

Both buckets live in the same sandbox account and your SSO role can read both. In production, each legal entity's data would live in its own account. Each workload role could read only its own entity's bucket, and an SCP would restrict the EU account to EU Regions. DI keeps the code tidy; IAM and account boundaries enforce the separation.

  • Profiles only in Development. A Profile in appsettings.json would be shipped to production, where it does not exist. Worse, a credentials file baked into an image would be used instead of the role.
  • No secrets in the AWS section. It holds Regions and profile names, never keys. For application secrets, use Secrets Manager (later in this module).
  • Presigned URLs are bearer tokens. Anyone holding the link can download the file until it expires. Keep lifetimes short (five minutes here), never log full URLs, and return them only to an authenticated customer for their own account.
  • Validate before you sign. The store builds the object key from validated parts. This prevents insecure direct object references, the most common bug in statement-download features.
  • ServiceURL overrides are dangerous in production. A mis-set AWS__ServiceURL environment variable would send signed requests elsewhere. Fail startup if ServiceURL is set outside Development (see the challenge exercise).

Banking use case

Harbourline's Customer Documents API serves statements, tax certificates and letters to the mobile app. It uses exactly this pattern:

  • One IAmazonS3 for each legal entity, each pinned to its Region and resolved by key.
  • A singleton IAmazonDynamoDB for the document index, tuned with MaxErrorRetry = 2 and a 2-second per-call deadline. The mobile app shows "try again" rather than spinning for 30 seconds.
  • IStatementStore and IDocumentIndex interfaces, so the 400 unit tests run in under ten seconds on every pull request with no AWS access at all.
  • A nightly integration test job, run with RUN_AWS_TESTS=1 under an OIDC-federated role, that creates a test object, presigns it, downloads it over HTTPS and deletes it.

Data-protection reviewers check the composition root (Program.cs) to confirm which Region each entity uses. The decision about where the EU subsidiary's data may be stored belongs to Harbourline's legal and compliance teams. The code makes it visible and testable.

Common mistakes

  • Registering clients as scoped or transient → "fresh client per request feels safer" → socket exhaustion, slow requests → keep the singleton default.
  • new AmazonS3Client() inside a service → it is quick to write → untestable code and hidden configuration → inject IAmazonS3.
  • Two AddAWSService<IAmazonS3>() calls for two Regions → the second silently wins for constructor injection → use AddKeyedAWSService or a dedicated wrapper type.
  • AWS:Profile in appsettings.json → works on every developer laptop → fails in ECS ("profile not found") → put it only in appsettings.Development.json or AWS_PROFILE.
  • Expecting a startup failure for missing credentials → nothing happens until the first request → add a readiness check, or resolve critical clients during startup in a hosted service.
  • Mocking the paginator → hours of fighting IAsyncEnumerable mocks → use an explicit loop in code you unit-test, or wrap the paginator behind your own interface.
  • Disposing an injected client → ObjectDisposedException on the next request → never using an injected client.
  • Using the generic overload GetAWSOptions<T>() from v3 samples → it was removed in v4 → use GetAWSOptions() or GetAWSOptions("Section").

Troubleshooting

SymptomLikely causeFix
AmazonClientException: Failed to resolve AWS credentials on the first requestNo profile locally, or no task role in AWSLocally: aws sso login and check AWS:Profile. In AWS: attach a task role. In tests: fake environment variables or replace the client
Unable to get IAM security credentials from EC2 Instance Metadata Service in a containerThe chain fell through to IMDS: no task role, or the role is set on the wrong field (execution role only)Set the task role (taskRoleArn), not just the execution role
InvalidOperationException: No service for type 'Amazon.S3.IAmazonS3' has been registeredAddAWSService<IAmazonS3>() missing, or only a keyed registration existsRegister the unkeyed client, or inject with [FromKeyedServices("eu")]
Requests go to the wrong RegionThe AWS:Region key is misspelt (casing matters) or overridden by an environment variableLog client.Config.RegionEndpoint at startup; check AWS__Region in the task definition
Profile works in the CLI but not in the appAWSSDK.SSO/AWSSDK.SSOOIDC missing, or the app runs as a different OS user (for example, IIS)Add the packages; run under your own user, or use AWS:ProfilesLocation
Unit tests hit the networkA class still creates new AmazonS3Client() itselfInject the interface; grep for new Amazon in src/
ObjectDisposedException from an SDK clientSomeone disposed an injected singletonRemove the using; let the container own client lifetime

Cost and cleanup

  • Local tests: free. No AWS calls are made.
  • Optional sandbox run: two S3 buckets holding a few small PDFs cost well under one US cent per month. Presigning has no charge; downloads are GET requests and a few KB of data transfer.
# Empty and delete both buckets (versioned buckets: remove all versions first, or use the IaC destroy).
aws s3 rm s3://hl-m03-statements-uk-alex --recursive --profile learn-sandbox
aws s3api delete-bucket --bucket hl-m03-statements-uk-alex --profile learn-sandbox
aws s3 rm s3://hl-m03-statements-eu-alex --recursive --profile learn-sandbox --region eu-west-1
aws s3api delete-bucket --bucket hl-m03-statements-eu-alex --profile learn-sandbox --region eu-west-1

# Or, if you used IaC:
cdk destroy --all --profile learn-sandbox     # or: terraform destroy

# Confirm nothing tagged for this lesson remains, in both Regions.
for r in us-east-1 eu-west-1; do
  aws resourcegroupstaggingapi get-resources --tag-filters Key=Lab,Values=m03-di \
    --region "$r" --profile learn-sandbox --query "ResourceTagMappingList[].ResourceARN"
done

If delete-bucket fails with BucketNotEmpty on a versioned bucket, delete the object versions in the console (Bucket → Empty) or use the IaC destroy, which handles it.

Exercises

  • 🟢 Guided: Build the project and run the tests. Then change AddAWSService<IAmazonS3>(...) to use ServiceLifetime.Transient and add an Assert.NotSame variant of the DI test to prove the lifetime changed. Change it back afterwards.
  • 🟡 Challenge: Add a startup guard: if AWS:ServiceURL is set and the environment is not Development, the application must refuse to start with a clear message. Write a test for it with WebApplicationFactory and UseEnvironment("Production").
  • 🔴 Live problem: The EU subsidiary's compliance officer asks: "Can you prove the API cannot read EU statements with the UK client, even if a developer makes a routing bug?" Today both clients use the same task role. Propose a design and the evidence you would provide.

Assignment

Extend the Statements API with a DELETE /v1/{entity}/accounts/{accountId}/statements/{period} endpoint for the operations team (GDPR erasure workflow). Include: a new IStatementStore.DeleteAsync method, an S3 implementation, unit tests with NSubstitute (including "object does not exist"), an endpoint test with a fake, and a short note on why a versioned bucket needs extra steps for true erasure. Commit it to your portfolio repository.

Solutions

Knowledge check

Interview questions

  • "How do you register AWS clients in ASP.NET Core?" — AddDefaultAWSOptions(configuration.GetAWSOptions()) once, AddAWSService<T>() per client, keyed registrations for a second Region or account, singleton lifetime, settings from configuration so environments differ only in configuration.
  • "How do you unit-test code that uses S3?" — Depend on IAmazonS3, or better on your own interface around it. Mock the low-level calls with NSubstitute. Use explicit pagination loops so they are mockable. Replace application services with fakes in WebApplicationFactory. Gate real-AWS integration tests behind an environment variable.
  • "What is a presigned URL and what are its risks?" — A URL signed with the service's credentials that grants time-limited access to one object operation. It is a bearer token: keep lifetimes short, never log it, only issue it after authorisation, and remember it stops working when the signing credentials expire.
  • "What did you change when moving the setup package to v4?" — Generic GetAWSOptions<T> overloads are gone. DefaultClientConfig is no longer a ClientConfig subclass (so HttpClientFactory moved to AWSConfigs). Client creation became Native AOT-safe on .NET 8+.

Certification practice

Completion checklist

  • I can explain AddDefaultAWSOptions, AddAWSService and AddKeyedAWSService
  • My tests pass with no AWS credentials on the machine
  • I know why clients are singletons and never disposed by consumers
  • I set AWS:Profile only for Development
  • I deleted any buckets I created and checked both Regions for leftovers

Key takeaways

  • Configure once, inject everywhere: AddDefaultAWSOptions from the AWS section, AddAWSService<T> per client, keyed clients for additional Regions or accounts.
  • Singletons, always. Never create clients per request, and never dispose an injected client.
  • Environments differ only in configuration. Profiles are for Development; roles and environment variables are for AWS.
  • Credentials resolve when the client is first resolved. Plan readiness checks and tests around that.
  • Depend on interfaces and test with fakes. Keep real-AWS tests behind RUN_AWS_TESTS=1.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page