Modern Secrets for Legacy .NET: Building a Typed, Cached AWS Secrets Manager Library

David Gates — Thu, 16 Jul 2026 10:53:27 +0000

The Problem

If you're building on modern .NET, retrieving a secret from AWS Secrets Manager as a strongly typed, cached configuration value is pretty much turnkey. AWS's supporting NuGet packages handle TTL-based (time-to-live) caching out of the box, and let you bind secrets straight into IConfiguration with only a few lines of code.

If you're maintaining a .NET Framework 4.8 application — and there are more of these in production than any of us would like to admit — none of that tooling exists. The AWS SDK for .NET supports .NET Framework 4.8; you can certainly call AmazonSecretsManagerClient.GetSecretValueAsync from a Framework app today. What doesn't exist is the supporting ecosystem that modern .NET developers take for granted: no typed binding, no caching client, and nothing comparable to IConfiguration's abstraction over configuration sources. You're left hand-rolling JSON deserialization, deciding for yourself whether and how to cache secrets, and wiring the rest together by hand.

A lot of what's still running out there is classic ASP.NET MVC 5 — System.Web.Mvc, Global.asax-based startup, with no built-in dependency injection (DI). That's not a niche scenario; it's the reality for many enterprise applications across organizations of every size.

I ran into this gap firsthand when my organization decided to standardize on AWS Secrets Manager across both modern and legacy .NET applications. The modern apps were straightforward: install the packages, bind to IConfiguration, and you're done. The first .NET Framework 4.8 application was a different story. It needed the same typed retrieval, caching, and clean integration, but none of that infrastructure existed. Every legacy application in our portfolio would face the same challenge. I built DGates.AwsSecretsManager to solve it once, rather than repeating the same solution across every legacy application.

So the goal here wasn't to invent AWS Secrets Manager support for .NET Framework; that already existed. The goal was to close the ergonomics gap: build the kind of typed, cached, DI-friendly wrapper that modern .NET developers get for free today, in a form that a legacy .NET Framework app — including one with no DI container and no modern configuration pipeline — can actually adopt without a rewrite.

The source, NuGet package, and example applications are all available if you'd like to follow along.

Design Decisions & Trade-offs

This is the part of the library that matters — not "I called an AWS SDK method," but the decisions around how to expose it. Every decision came back to one constraint: the library had to feel natural in a .NET Framework 4.8 application, without requiring that application to become more "modern" to use it.

Typed retrieval, not string wrangling. The library's API centers on GetSecretAsync<T> — deliberately mirroring the typed configuration binding modern .NET developers already expect. Tell it what shape you expect back, and it hands you an object — not a JSON blob you deserialize yourself three call sites later. GetSecretStringAsync exists too, for the cases where a secret genuinely is just a string and wrapping it in a POCO (plain old CLR object) would be overkill. RefreshSecretAsync<T> and InvalidateCache round out the API — force a refresh when you know a secret rotated, or drop it from cache entirely without waiting for TTL expiry.

Caching: ConcurrentDictionary, not IMemoryCache. This one is a deliberate departure from what a lot of people would reach for first. Microsoft.Extensions.Caching.Memory is the obvious modern choice, but pulling it into a .NET Framework 4.8 library means dragging in a dependency chain built for a different runtime generation, plus the DI registration ceremony that comes with it. That's exactly the kind of friction we want to avoid with this library. A ConcurrentDictionary keyed by secret name, storing the value alongside its expiry, does everything needed here: thread-safe reads and writes, no extra package, no DI requirement. CacheTtl is exposed as a TimeSpan rather than an int, because "how long should this live" is a duration, and forcing a caller to remember whether an int means seconds or milliseconds is the kind of API ambiguity that causes production incidents at 2 a.m.

Resilience: Polly, scoped narrowly. Secrets Manager calls can fail transiently, and retrying blindly can be worse than not retrying at all if you're not careful about what you retry. Polly 8 wraps the AWS calls specifically for transient failure modes — throttling, temporary network failures, and similar conditions — not as a blanket "wrap everything and hope" policy. Non-transient failures, like invalid credentials or a secret that does not exist, surface immediately instead of being retried into a longer, more confusing failure.

DI-agnostic by design. This decision came directly from the target audience. A modern ASP.NET app has a DI container built in. A classic ASP.NET MVC 5 app, running through Global.asax, does not. Forcing a specific container (Autofac, Unity, whatever) onto a legacy app just to use this library would be limiting and defeat the purpose. Instead, SecretsManagerServiceFactory builds a configured SecretsManagerService directly, and SecretsManagerService itself is directly instantiable — no container required. Consumers who do have a DI container can register it as usual; consumers who don't can call the factory once at startup and hold the result in a static accessor. Both are first-class, not one blessed path and one workaround.

The same restraint applies to authentication. SecretsManagerSettings accepts an explicit AccessKey and SecretKey for the cases that genuinely need them, but when those values are omitted, the library defers to the AWS SDK's standard credential chain — environment variables, an .aws/credentials profile, or an IAM role. Rather than inventing its own authentication model, the library relies on the one AWS developers already know and expect.

Local development without AWS. None of the above matters much if testing it locally means burning AWS API calls against a real Secrets Manager instance every time you hit F5, or requiring an AWS account just to try the library out. The library ships with a docker-compose.yml that spins up LocalStack and a seed script that populates it with test secrets, so a fresh checkout can run the integration tests against a fully local AWS emulation with a single command: no AWS account, no manual setup. The examples repo follows the same pattern.

For environments where Docker isn't available — nested VMs without virtualization passthrough are a common setup in practice — there's a LocalJsonFallbackPath that reads secrets from a local JSON file instead. It's not a mock; it's a genuine fallback path, wired the same way the real client is, so switching between "talk to LocalStack," "talk to real AWS," and "read a local file" is a configuration change, not a code change. (To be clear: this fallback is a local development and testing convenience, not something intended for production use.)

Proving It in a Real App: MvcExample

Could every application implement this itself? Absolutely — the AWS SDK makes that possible, if not particularly pleasant. But once you're standardizing Secrets Manager across dozens of legacy applications, the problem isn't writing another JSON deserializer. It's making sure every application gets the same caching behavior, retry policy, configuration model, and local development experience — instead of a dozen slightly different, independently maintained versions of the same idea.

A library intended for ASP.NET MVC 5 isn't really proven by a console sample alone. To validate DGates.AwsSecretsManager in the kind of environment it was actually built for, I created a classic ASP.NET MVC 5 application — MvcExample — where a user enters a city, the app retrieves an OpenWeatherMap API key from Secrets Manager, geocodes the city, and fetches live weather. A "how this worked" panel shows the secret name, the retrieved URL, and which backend served the request — real AWS, LocalStack, or the JSON fallback.

Startup integration is a single factory call — no DI container required:

// Global.asax.cs — Application_Start
var secrets = SecretsManagerServiceFactory.Create(new SecretsManagerSettings
{
    Region = "us-west-2",
    CacheTtl = TimeSpan.FromMinutes(15),
    LocalJsonFallbackPath = Server.MapPath("~/App_Data/secrets.local.json")
});

Retrieval is one typed call — the secret comes back as a POCO, already deserialized, already cached:

var secret = await secrets.GetSecretAsync<OpenWeatherMapSecret>("dev/MvcExample/OpenWeatherMap");

That's the ergonomics gap from the start of this post, closed: typed, cached, and wired into a Global.asax-era app without a rewrite.

In MvcExample, both calls live behind a small static accessor class: it reads the settings from Web.config instead of hardcoding them, guards initialization so the service is built exactly once, and wraps retrieval results with the metadata the "how this worked" panel displays. None of that is required by the library itself — it's the app's own glue — but the pattern is worth copying if you want environment-specific configuration without a recompile. See SecretsManagerAccessor.cs for the full version.

Legacy packaging friction. MVC5 projects use packages.config, and DGates.AwsSecretsManager brings the AWS SDK's sizeable transitive dependency tree with it — something you do not want to manage through hand-wired HintPath entries. The long-term solution is to convert the legacy project's packages to PackageReference and isolate all library-facing code in a small SDK-style project — in this case, MvcExample.Infrastructure. The web project references that project through ProjectReference, letting MSBuild resolve the full dependency graph while the legacy project never has to know the AWS SDK exists. As a bonus, the conversion also enables dotnet restore, making clean command-line and CI builds possible without relying on Visual Studio.

Two operational lessons. First, Application_Start runs eagerly — so an unreachable Secrets Manager at startup meant a crashed app pool, not an error page. Initialization is now handled defensively, surfacing failures as an in-page message at first real use instead. Second, LocalJsonFallbackPath isn't automatic — if you want the fallback, it has to be wired explicitly at the consumer's configuration call site. It was missing entirely from MvcExample's initial setup, a reminder that it needs to be verified in every new consumer, not assumed from the README.

What the panel doesn't show. The "how this worked" panel doesn't display a cache-hit indicator, and that's deliberate. Building one would have meant inferring the library's internal cache state from the outside rather than reporting something real — false precision dressed up as telemetry. Better to show nothing than something that looks like data but isn't.

Building & Publishing

A .NET Framework 4.8 library in 2026 raises an immediate CI question: what does the pipeline even run on? GitHub Actions' Windows runners are the obvious answer, but LocalStack ships as a Linux container and isn't supported under Windows containers. The library is built and tested on ubuntu-latest instead, using Mono to run the .NET Framework test suite. Linux runners also spin up faster, and keeping the pipeline on one OS keeps it simple — the same environment builds the library, runs the tests against LocalStack, and packs the NuGet package.

There's one hard limit to know about: this works for building .NET Framework code, not running classic ASP.NET on Linux. Compiling the MVC 5 example app on ubuntu-latest works fine; hosting it does not — Mono's xsp4 web host is broken and unmaintained. Build on Linux, run on Windows via IIS Express. That boundary is worth knowing before you design a pipeline around either assumption.

Two principles shaped the rest of the pipeline:

No NuGet API keys, anywhere. Publishing uses NuGet's Trusted Publishing — the workflow authenticates via OIDC (OpenID Connect), meaning NuGet.org trusts a short-lived token issued by GitHub Actions for this specific repository and workflow, rather than a long-lived API key stored as a repository secret. There is nothing to leak, rotate, or accidentally commit. For a library whose entire purpose is keeping secrets out of the wrong places, publishing it with a static credential would have been a little too ironic.

Integration tests run against real (local) infrastructure. The same docker-compose.yml and seed script that power local development spin up LocalStack in CI, so the integration tests exercise genuine Secrets Manager API behavior on every push — not mocks. The local-dev investment from earlier paid for itself here: CI didn't need its own separate test infrastructure, because the local story already was one.

Lessons Learned

Three things stand out looking back at this project — none of them about AWS or Secrets Manager specifically.

Local development isn't an afterthought. The LocalStack setup and the JSON fallback path took real time to build — time that could have gone toward features. It was worth it twice over. During development, the zero-dependency local story meant every design decision could be exercised immediately, in environments ranging from a full Docker setup to a locked-down VM with nothing on it. Then it paid off again in CI: the same docker-compose.yml and seed script that power local development became the integration test infrastructure, with no separate CI-only setup to build or maintain. Investment in the development experience compounds; it isn't overhead.

Design for the audience you actually have. It would have been easier to build this with the newest patterns available: a modern DI container, IOptions-style configuration, the latest caching abstractions. The applications that need this library can't use any of that. Every design decision in this post traces back to accepting that constraint instead of fighting it: the DI-agnostic factory exists because the target apps have no container, converting package management is a much smaller step than rewriting the project around an SDK-style project model, and configuration flows through Web.config because that's where these apps keep it. Meeting legacy applications where they are is what makes incremental modernization possible at all.

Consistency scales; convenience doesn't. Any individual application could hand-roll its own Secrets Manager integration in an afternoon. Taken once, that's perfectly reasonable. Taken a dozen times across a portfolio, it produces a dozen slightly different caching policies, retry behaviors, and configuration conventions, each independently maintained, each evolving in slightly different directions. A shared library means one implementation to test, one set of behaviors to reason about, and one place to fix a bug that would otherwise be a dozen tickets. The value isn't that it saved anyone from writing a JSON deserializer — it's that nobody has to wonder which version of the pattern any given app is running.

Final Thoughts

The surprising part of this project wasn't the implementation itself. It was realizing that the hardest problems weren't making it work — they were making it fit. Legacy applications aren't difficult because they're old; they're difficult because they're valuable enough to keep running while the world around them changes.

That's ultimately what DGates.AwsSecretsManager aims to provide: not new capabilities, but modern ergonomics for software that's still doing real work.

If this library helps even a handful of teams modernize legacy applications incrementally instead of rewriting them all at once, it will have done exactly what it was built to do.

What's Next

The library is currently in beta. Before a stable 1.0 release, I want to focus on two areas: structured logging and deeper documentation of the design decisions covered here. Beyond that are ideas like cache stampede protection, serializer abstraction, and rotation handling — but roadmaps change, so the issue tracker remains the source of truth for what's actually planned.

If you're maintaining .NET Framework applications and this problem looks familiar, I'd love to hear how you're solving it — or whether DGates.AwsSecretsManager helps. Feedback from real legacy codebases is worth more than any roadmap.

DEV Community: David Gates