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.
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,AddAWSServiceandAddKeyedAWSService, and explain what each overload does. - Read AWS settings (
Region,Profile,ServiceURL, retries) from theAWSconfiguration 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
IAmazonS3with NSubstitute, replace application services with fakes inWebApplicationFactorytests, and keep real-AWS tests behindRUN_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:
AddDefaultAWSOptionsstores one set of AWS settings (Region, profile, retry defaults). Usually you read them from theAWSsection of configuration.AddAWSService<IAmazonS3>()registers a factory. The first time something asks forIAmazonS3, the factory creates anAmazonS3Clientfrom those settings. Every later request gets the same instance.- 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 theAWSsection (or any section you name) into anAWSOptionsobject. Supported keys includeRegion,Profile,ProfilesLocation,ServiceURL,MaxErrorRetry,UseDualstackEndpoint,AuthenticationRegion,LogResponseand 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
HttpClientFactoryintegration per client. In v4,DefaultClientConfig.HttpClientFactorywas removed; set a custom factory globally withAWSConfigs.HttpClientFactoryif 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 equivalent | What'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 / Profile | AWS 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 singleton | AWS clients registered as singletons | Same rule, same reason: thread-safe, expensive, pooled connections |
Azurite for local Blob Storage (UseDevelopmentStorage=true) | ServiceURL override pointing at a local emulator | Only 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.2Put 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/statementsUse 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 tagsProject=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.jsonto 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-alexInfrastructure 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.
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).
{
"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"
}
}{
"AWS": {
"Profile": "learn-sandbox"
},
"AwsEu": {
"Profile": "learn-sandbox"
},
"Statements": {
"UkBucketName": "hl-m03-statements-uk-alex",
"EuBucketName": "hl-m03-statements-eu-alex"
}
}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;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();
}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).
<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>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
AddDefaultAWSOptions(builder.Configuration.GetAWSOptions())reads theAWSsection into anAWSOptionsobject and registers it. Every client created byAddAWSServicewithout its own options uses it. Because configuration is layered,appsettings.Development.jsoncan addProfileand an environment variable such asAWS__Regioncan override the Region, with no code change.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'sClientConfig. The second parameter is theIServiceProvider, in case the tuning depends on other services.AddKeyedAWSService<IAmazonS3>("eu", GetAWSOptions("AwsEu"))registers a secondIAmazonS3, distinguished by the key"eu", built from theAwsEusection. Without keys, a secondAddAWSService<IAmazonS3>would simply replace the first registration for constructor injection.Configure<StatementOptions>(...)is ordinary .NET options binding for your own settings. AWS clients and app settings are configured the same way.AddKeyedSingleton<IStatementStore>("uk", (sp, _) => ...)builds the UK store with the UK client and bucket. The EU registration does the same withGetRequiredKeyedService<IAmazonS3>("eu"). Keeping the client choice in one place (composition root) makes the residency rule easy to review.
StatementStore.cs
IStatementStoreis the seam for tests. Endpoints depend on it, not on S3.S3StatementStore(IAmazonS3 s3, ...)depends on the interfaceIAmazonS3, so a test can pass a substitute.CreateLinkedTokenSource(cancellationToken)+CancelAftercombines the request-aborted token from ASP.NET Core with your own deadline.- The
do ... while (response.IsTruncated == true)loop followsNextContinuationToken. It is written out (not a paginator) because mockingListObjectsV2Asyncis easy and mocking paginators is not. response.S3Objects ?? [],obj.Size ?? 0,obj.LastModified ?? DateTime.MinValueare the v4 nullable rules applied consistently.KeyPattern()is a source-generated regular expression. It filters out unexpected objects, such as a straynotes.txtin the prefix.GetPreSignedURLAsynccreates 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 atExpiresor when the signing credentials expire, whichever comes first. Role credentials therefore cap a link's lifetime.- 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
{entity:regex(^(uk|eu)$)}constrains the route, so/v1/us/...is a 404 before any code runs.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.TypedResults.Problem(...)returns RFC 9457 ProblemDetails, the Harbourline error convention.
Tests
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.S3Objects = nullreproduces the v4 behaviour that breaks v3-era code. Keep this test forever.Received(1).GetPreSignedURLAsync(Arg.Is(... r.Key == ...))proves the store built the key itself and rejected../../otherbefore signing anything.DependencyInjectionTestsuses 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.RemoveAllKeyed<IStatementStore>("uk")thenAddKeyedSingleton<IStatementStore, FakeStore>("uk")swaps the S3-backed stores for fakes insideWebApplicationFactory. The endpoint tests then exercise routing, validation and JSON without touching AWS.
Lifetimes: why singleton
| Lifetime | What happens with an AWS client | Verdict |
|---|---|---|
| Singleton (default) | One client and one connection pool per configuration; credentials refreshed in the background | ✅ Use this |
| Scoped | A new client per HTTP request: new handler, new credential provider, sockets not reused | ❌ Socket exhaustion and latency under load |
| Transient | A 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 = injectedClientis 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
| Environment | Where AWS settings come from | Credentials |
|---|---|---|
| Developer laptop | appsettings.Development.json (AWS:Profile = learn-sandbox) | SSO token cache via the profile |
| CI unit tests | No AWS settings needed; fakes and mocks | None (fake environment variables only where a real client is resolved) |
| CI integration tests | RUN_AWS_TESTS=1 plus OIDC-federated role | Pipeline role (Module 9) |
| ECS / Beanstalk / Lambda | appsettings.json plus environment variables (AWS__Region, Statements__UkBucketName) | Task, instance or function role through the default chain |
| Local emulator | AWS:ServiceURL in appsettings.Development.json only | Dummy 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
Profileinappsettings.jsonwould 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
AWSsection. 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.
ServiceURLoverrides are dangerous in production. A mis-setAWS__ServiceURLenvironment variable would send signed requests elsewhere. Fail startup ifServiceURLis 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
IAmazonS3for each legal entity, each pinned to its Region and resolved by key. - A singleton
IAmazonDynamoDBfor the document index, tuned withMaxErrorRetry = 2and a 2-second per-call deadline. The mobile app shows "try again" rather than spinning for 30 seconds. IStatementStoreandIDocumentIndexinterfaces, 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=1under 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 → injectIAmazonS3.- Two
AddAWSService<IAmazonS3>()calls for two Regions → the second silently wins for constructor injection → useAddKeyedAWSServiceor a dedicated wrapper type. AWS:Profileinappsettings.json→ works on every developer laptop → fails in ECS ("profile not found") → put it only inappsettings.Development.jsonorAWS_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
IAsyncEnumerablemocks → use an explicit loop in code you unit-test, or wrap the paginator behind your own interface. - Disposing an injected client →
ObjectDisposedExceptionon the next request → neverusingan injected client. - Using the generic overload
GetAWSOptions<T>()from v3 samples → it was removed in v4 → useGetAWSOptions()orGetAWSOptions("Section").
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
AmazonClientException: Failed to resolve AWS credentials on the first request | No profile locally, or no task role in AWS | Locally: 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 container | The 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 registered | AddAWSService<IAmazonS3>() missing, or only a keyed registration exists | Register the unkeyed client, or inject with [FromKeyedServices("eu")] |
| Requests go to the wrong Region | The AWS:Region key is misspelt (casing matters) or overridden by an environment variable | Log client.Config.RegionEndpoint at startup; check AWS__Region in the task definition |
| Profile works in the CLI but not in the app | AWSSDK.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 network | A class still creates new AmazonS3Client() itself | Inject the interface; grep for new Amazon in src/ |
ObjectDisposedException from an SDK client | Someone disposed an injected singleton | Remove 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"
doneIf 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 useServiceLifetime.Transientand add anAssert.NotSamevariant of the DI test to prove the lifetime changed. Change it back afterwards. - 🟡 Challenge: Add a startup guard: if
AWS:ServiceURLis set and the environment is notDevelopment, the application must refuse to start with a clear message. Write a test for it withWebApplicationFactoryandUseEnvironment("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
builder.Services.AddAWSService<IAmazonS3>((config, _) =>
{
config.MaxErrorRetry = 3;
config.ConnectTimeout = TimeSpan.FromSeconds(3);
}, ServiceLifetime.Transient);[Fact]
public void Transient_registration_creates_a_new_client_each_time()
{
Environment.SetEnvironmentVariable("AWS_ACCESS_KEY_ID", "AKIAFAKEFAKEFAKEFAKE");
Environment.SetEnvironmentVariable("AWS_SECRET_ACCESS_KEY", "fake-secret-for-unit-tests");
using var factory = new WebApplicationFactory<Program>();
Assert.NotSame(factory.Services.GetRequiredService<IAmazonS3>(), factory.Services.GetRequiredService<IAmazonS3>());
}Why: the test makes the lifetime an explicit, reviewed decision. Under load, each new client means a new HTTP handler and a new credential resolution, which is what caused the incident in the introduction.
// Program.cs, straight after CreateBuilder:
if (!builder.Environment.IsDevelopment() && !string.IsNullOrEmpty(builder.Configuration["AWS:ServiceURL"]))
{
throw new InvalidOperationException(
"AWS:ServiceURL is only allowed in Development. Remove it from this environment's configuration.");
}// Add `using Microsoft.AspNetCore.Hosting;` to the test file for UseEnvironment and UseSetting.
[Fact]
public void Refuses_to_start_with_a_service_url_outside_development()
{
using var factory = new WebApplicationFactory<Program>().WithWebHostBuilder(b =>
{
b.UseEnvironment("Production");
b.UseSetting("AWS:ServiceURL", "http://localhost:4566");
});
var ex = Assert.Throws<InvalidOperationException>(() => factory.CreateClient());
Assert.Contains("ServiceURL", ex.Message);
}Why: a ServiceURL sends signed requests to whatever host it names. In production that is either a misconfiguration or an attack. Failing fast turns it into a deployment failure instead of a data leak. UseSetting adds the key to host configuration, which the app's IConfiguration already contains when the guard runs. This test was run and passes alongside the others.
- Separate identities. Give the EU path its own IAM role whose policy allows
s3:GetObject/s3:ListBucketonly on the EU bucket. The UK role is denied the EU bucket by its policy and, more strongly, by an EU bucket policy that allows only the EU role's ARN (or only principals from the EU account, usingaws:PrincipalAccount). - Make the code use the right identity. Either run the EU API as a separate service (its own ECS task role: simplest and strongest), or build the keyed EU client with
AWSOptions.SessionRoleArnset to the EU role so it assumes that role. The task role is then allowed onlysts:AssumeRoleon it. - Better still: separate accounts. Put the EU workload and bucket in an EU account under an OU whose SCP denies non-EU Regions.
- Evidence: the bucket policy and role policies from IaC; an IAM Access Analyzer finding report showing no unintended access; a CloudTrail query showing every
GetObjecton the EU bucket came from the EU role; and an automated test in the integration suite that tries to read an EU object with the UK client and expectsAccessDenied.
Why: a routing bug in code is always possible. The compliance officer needs a control that holds even when the code is wrong, and only IAM and account boundaries provide that.
Knowledge check
Answer: Singleton. AWS service clients are thread-safe and relatively expensive to create (HTTP handler, connection pool, credential provider), so one per configuration is both faster and safer.
Answer: Register the default with AddAWSService<IAmazonS3>() and the second with AddKeyedAWSService<IAmazonS3>("eu", configuration.GetAWSOptions("AwsEu")), then resolve it with [FromKeyedServices("eu")] or GetRequiredKeyedService. Two unkeyed registrations would make the last one win.
Answer: Only in appsettings.Development.json or via AWS_PROFILE on a developer machine. In production the profile does not exist, so client creation fails; if a credentials file was baked into the image, it would be used instead of the task role.
Answer: The v4 client factory resolves credentials when it creates the client. With no credentials anywhere in the chain, resolving IAmazonS3 throws AmazonClientException. Fake variables satisfy the chain; no request is sent.
Answer: The service signs with its own (broad) permissions, so the caller could request any key the service can read, including other customers' statements. Build the key from validated, authorised parts instead.
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 inWebApplicationFactory. 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.DefaultClientConfigis no longer aClientConfigsubclass (soHttpClientFactorymoved toAWSConfigs). Client creation became Native AOT-safe on .NET 8+.
Certification practice
A .NET 10 API creates a new AmazonDynamoDBClient inside each controller action. Under load, latency rises and the container logs socket errors. What should the developer do?
A. Increase the task's memory.
B. Register IAmazonDynamoDB once with AddAWSService<IAmazonDynamoDB>() and inject it into the controllers.
C. Wrap each call in a new HttpClient.
D. Switch to DynamoDB Accelerator (DAX).
Answer: B. A singleton client reuses its connection pool and credential provider. More memory does not fix socket churn (A). HttpClient is not how the SDK is used (C). DAX is a cache for read-heavy workloads and does not fix client misuse (D).
A team's CI pipeline must run unit tests for code that writes to S3, without granting the pipeline any AWS access. Which approach is MOST appropriate?
A. Give the pipeline an IAM user with S3 access and store its keys as pipeline secrets.
B. Inject IAmazonS3 into the classes and replace it with a mock in unit tests; run real-AWS tests only in a separate, explicitly enabled job.
C. Point the SDK at a public test bucket.
D. Catch and ignore all AmazonServiceExceptions in tests.
Answer: B. Mocks need no credentials. Integration tests with real AWS run separately under a federated role. A adds long-term keys. C leaks data and still needs credentials. D hides real failures.
A bank's API serves customers of a UK entity and an EU subsidiary. EU customer documents must be accessible only to the EU workload. Which design provides the STRONGEST control?
A. Separate S3 prefixes in one bucket, chosen by application code. B. Separate buckets in the same account, both readable by one shared role. C. Separate accounts for each entity, each workload with its own role, bucket policies allowing only that role, and SCPs restricting the EU account to EU Regions. D. Encrypt EU objects with SSE-S3.
Answer: C. Account boundaries, role-scoped policies and SCPs enforce separation even if code is wrong. A and B rely on application logic. SSE-S3 encrypts at rest but does not restrict who can read through the service (D).
Completion checklist
- I can explain
AddDefaultAWSOptions,AddAWSServiceandAddKeyedAWSService - My tests pass with no AWS credentials on the machine
- I know why clients are singletons and never disposed by consumers
- I set
AWS:Profileonly for Development - I deleted any buckets I created and checked both Regions for leftovers
Key takeaways
- Configure once, inject everywhere:
AddDefaultAWSOptionsfrom theAWSsection,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
- Using AWSSDK.Extensions.NETCore.Setup and the IConfiguration interface
- Migrating to version 4 of the AWS SDK for .NET — section on
AWSSDK.Extensions.NETCore.Setup - Credential and profile resolution
- Previous: AWS SDK for .NET v4 in depth · Next: ASP.NET Core Web API on AWS: the baseline
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.
AWS SDK for .NET v4 in depth
Use the AWS SDK for .NET v4 the way production code should: explicit Regions, the credential provider chain, SSO profiles for local work, retries and deadlines, paginators, error handling and the v4 breaking changes that bite during upgrades.
Lab 3.1: an SDK v4 console app with SSO and dependency injection
Build a .NET 10 console app that registers AWS SDK v4 clients through dependency injection, signs in with the learn-sandbox SSO profile, calls STS GetCallerIdentity, lists S3 buckets page by page, and is unit tested with a mocked client.