DEV Community: Prune

The .NET Options pattern: a practical field guide

Prune — Thu, 10 Sep 2026 17:26:47 +0000

Every ASP.NET Core service binds configuration. Far fewer get the lifetime, the validation, and the reload story right. Here is the whole surface in one page, with the traps marked.

TL;DR

IOptions<T> = singleton, bound once, no reload, no named options.
IOptionsSnapshot<T> = scoped, rebound per request, reloads, cannot go in a singleton.
IOptionsMonitor<T> = singleton, live value + OnChange, works everywhere.
Add ValidateOnStart() or your validation runs late, inside a request.
OnChange fires multiple times per file save - debounce and dispose it.

The pattern in one screen

Bind a section, validate it, and register it - all through OptionsBuilder<T>:

public sealed class SmtpOptions
{
    public const string Section = "Smtp";

    [Required] public string Host { get; init; } = "";
    [Range(1, 65535)] public int Port { get; init; } = 25;
    public bool UseStartTls { get; init; } = true;
    public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(30);
}

builder.Services
    .AddOptions<SmtpOptions>()
    .Bind(builder.Configuration.GetSection(SmtpOptions.Section))
    .ValidateDataAnnotations()
    .Validate(o => !o.UseStartTls || o.Port != 25, "StartTLS on port 25 is almost never right.")
    .ValidateOnStart();

That is the whole happy path. Everything below is about the decisions this snippet hides.

Three interfaces, one table

Interface	DI lifetime	Sees reload	Named options	Inject into singleton	Cost per resolve
`IOptions<T>`	Singleton	No	No	Yes	Bound once, then a field read
`IOptionsSnapshot<T>`	Scoped	Yes, per request	Yes, `.Get(name)`	No	Re-binds + re-validates each scope
`IOptionsMonitor<T>`	Singleton	Yes, live	Yes, `.Get(name)`	Yes	Cached; recomputed only on change

The mechanical differences drive every recommendation. IOptionsSnapshot<T> re-binds the section and re-runs validation on every scope, so a heavy graph (large collections, decryption, remote lookups in a validator) is paid per request. IOptionsMonitor<T> caches in IOptionsMonitorCache<T> and only rebuilds when a change token fires.

Choosing, concretely

A typed settings object read inside a controller or handler → IOptionsSnapshot<T>. One consistent value for the request, reload between requests.
A singleton client, background service, or anything in Program.cs wiring → IOptionsMonitor<T>. It is the only reloadable one you can put there.
A value that genuinely never changes at runtime (feature-shaped constants, framework glue) → IOptions<T>. Cheapest, and honest about intent.

Named options

builder.Services.Configure<SmtpOptions>("primary",
    builder.Configuration.GetSection("Smtp:Primary"));
builder.Services.Configure<SmtpOptions>("backup",
    builder.Configuration.GetSection("Smtp:Backup"));

public sealed class MailSender(IOptionsMonitor<SmtpOptions> monitor)
{
    private SmtpOptions Primary => monitor.Get("primary");
    private SmtpOptions Backup  => monitor.Get("backup");
}

Trap: IOptions<T>.Value is hard-wired to Options.DefaultName (the empty string). Inject IOptions<SmtpOptions> against the setup above and you get an unconfigured object with no error. Named options exist only on IOptionsSnapshot<T> and IOptionsMonitor<T>.

Validation, done properly

Three layers, roughly in order of power:

.ValidateDataAnnotations() - attributes on the options type.
.Validate(predicate, message) - quick cross-field rules inline.
IValidateOptions<T> - a real class when rules get involved or need dependencies.

public sealed class SmtpOptionsValidator : IValidateOptions<SmtpOptions>
{
    public ValidateOptionsResult Validate(string? name, SmtpOptions o)
    {
        var failures = new List<string>();
        if (o.Timeout < TimeSpan.FromSeconds(1))
            failures.Add("Smtp:Timeout must be at least 1 second.");
        if (o.Host.EndsWith(".local", StringComparison.OrdinalIgnoreCase))
            failures.Add("Smtp:Host looks like a dev value.");
        return failures.Count > 0
            ? ValidateOptionsResult.Fail(failures)
            : ValidateOptionsResult.Success;
    }
}

builder.Services.AddSingleton<IValidateOptions<SmtpOptions>, SmtpOptionsValidator>();

The line people forget: ValidateOnStart

Without it, none of the above runs until the first read of .Value / .CurrentValue / .Get(). In a web app that is usually mid-request, so a bad deploy looks like a 500 to a user instead of a failed boot in your pipeline.

builder.Services.AddOptions<SmtpOptions>()
    .Bind(builder.Configuration.GetSection(SmtpOptions.Section))
    .ValidateDataAnnotations()
    .ValidateOnStart();          // .NET 6+

builder.Services.AddOptionsWithValidateOnStart<SmtpOptions>()
    .Bind(builder.Configuration.GetSection(SmtpOptions.Section))
    .ValidateDataAnnotations();  // .NET 8+ shorthand

Trimming / AOT: annotate a partial validator with [OptionsValidator] (.NET 8+) and the source generator writes the Validate body for you - no reflection, no ValidateDataAnnotations runtime cost.

Configure, PostConfigure, and stacking

Every Configure<T> call for a given name is additive and runs in registration order. PostConfigure<T> runs after all of them - the place to enforce an invariant or apply an override that must win:

builder.Services.Configure<SmtpOptions>(config.GetSection("Smtp"));   // 1
builder.Services.Configure<SmtpOptions>(o => o.Timeout = Clamp(o.Timeout)); // 2

builder.Services.PostConfigure<SmtpOptions>(o =>
{
    if (builder.Environment.IsDevelopment())
        o = o with { Host = "localhost" };   // last word, regardless of file
});

Gotchas grab-bag

Captive dependency. IOptionsSnapshot<T> (scoped) in a singleton constructor throws under the default scope validation. In middleware, put it on the InvokeAsync parameters; in a hosted service, inject IOptionsMonitor<T> and read CurrentValue.
OnChange double-fires. One save, several FS events. Debounce (e.g. drop events within ~250 ms) and keep the returned IDisposable - unregister it in Dispose so the callback dies with its owner.
CurrentValue in a hot loop. It is a property that may allocate on rebuild. Read it once into a local at the top of the operation instead of per iteration.
A bad reload can take everything down. If a reloaded value fails validation, CurrentValue throws OptionsValidationException on every access until the file is fixed. Reload is not free of blast radius.
Kubernetes ConfigMaps. They mount as a swapped ..data symlink, and the physical-file watcher frequently misses that. Test reload in-cluster; fall back to a rollout restart if it does not fire.
Unknown keys are silent. A misspelled key in appsettings.json binds to nothing and says nothing. On .NET 8+ pass o => o.ErrorOnUnknownConfiguration = true to Bind to catch it.
GetSection().Get<T>() is not the Options pattern. It is a one-shot manual bind: no DI, no reload, no validation. Fine for values you need before the container exists; wrong for everything after.

Testing options

// IOptions<T>
var opts = Options.Create(new SmtpOptions { Host = "smtp.test", Port = 587 });
var sut  = new MailSender(opts);

// IOptionsMonitor<T> - tiny fake, no package needed
public sealed class StaticMonitor<T>(T value) : IOptionsMonitor<T>
{
    public T CurrentValue => value;
    public T Get(string? name) => value;
    public IDisposable OnChange(Action<T, string?> _) => NullDisposable.Instance;
}

Cheat sheet

Default to IOptionsMonitor<T> in infra code, IOptionsSnapshot<T> in request code, IOptions<T> for static settings.
Always chain ValidateOnStart() (or AddOptionsWithValidateOnStart).
Never inject IOptionsSnapshot<T> into a singleton or a middleware constructor.
Debounce and dispose every OnChange registration.
Use .Get(name) for named options; IOptions<T> can't see them.
Reserve configuration.Get<T>() for pre-container bootstrap only.

Five registries, one prompt: Polish accounting firm's AML/KYC checks - KRS, CEIDG, CRBR, and sanctions screening - in one prompt.

Prune — Thu, 27 Aug 2026 20:00:00 +0000

How an AI assistant can check a client against Poland's company register, VAT list, beneficial-owner registry, and sanctions lists - and hand you a ready-to-file compliance document before your coffee gets cold.


5	registries and lists to check by hand for every new client
~60–90 min	what a thorough manual check of one company usually takes
1	prompt to an AI assistant to get a finished risk card

An obligation nobody enjoys

Under Polish AML law, an accounting firm is an "obligated institution" - the same legal category as banks and notaries, just a lot smaller - regardless of whether it serves a one-person business or a company with foreign shareholders.

In practice that means mandatory customer due diligence before you can even start working with a client: identify the entity, establish its beneficial owner, screen it against sanctions and PEP lists, and produce a documented risk assessment.

Done by hand, that looks like: one tab for the court register (KRS), a second for the VAT payer list, a third for the beneficial-owners registry - which happens to sit behind a CAPTCHA — a fourth for some sanctions list, and a fifth: a blank document where all of it has to be stitched into something coherent. At ten new clients a month, that's realistically a full day of work that is neither bookkeeping nor advisory — it's just copying data between
systems.

And if the regulator's audit turns up a missing or incomplete file, the Act allows administrative fines of up to EUR 1,000,000. In practice, small firms typically see something closer to PLN 15,000–25,000 (roughly EUR 3,500–6,000) - plus something that stings more than the fine itself: the firm's name published in the public register of violations.

One conversation instead of five tabs

AML Poland MCP connects an AI assistant — Claude, for instance — directly to the registries you already have to use. Instead of clicking through pages, you just ask.

Under the hood, it's an implementation of MCP (Model Context Protocol), the open standard that lets a language model reach for real data instead of guessing. This particular server gives an assistant four concrete tools:

Tool	What it does
`verify_company_basic`	Registry status (court register or sole-trader register), legal form, address, board members, VAT payer status, and reported bank accounts.
`fetch_crbr_beneficiaries`	Beneficial owners from Poland's Central Register of Beneficial Owners — name, citizenship, and the nature of their control.
`screen_sanctions_and_pep`	Screens a person against EU/UN/OFAC sanctions lists and the Polish national list, plus PEP (politically exposed person) status.
`generate_aml_risk_card`	Ties all of the above together, computes the risk level and required procedure (standard or enhanced diligence), and generates the finished document — Markdown or PDF.

In a conversation, it looks roughly like this:

> Check client NIP 7740001454 for AML and generate a risk card.

Checking the court register, the VAT list, the beneficial-owners
registry, and sanctions lists. Here's the summary:

  Name              ORLEN SPÓŁKA AKCYJNA
  Registry status   Active
  VAT status        Active payer
  Beneficial owners manual check required (CAPTCHA)

  Risk level        Medium
  Procedure         Standard
  Document          risk_card.pdf

That's not a made-up example - it's the exact result the server returns for a real NIP, checked live against the public registries while this tool was being tested.

What happens under the hood

No database of its own, no middleman that could go stale. Every query goes straight to the official source.

Accounting firm
      │
      ▼
AI assistant  (Claude + MCP)
      │
      ▼
KRS / CEIDG · VAT White List · CRBR (UBO) · Sanctions & PEP
      │
      ▼
Risk card  (PDF / Markdown)

Four tools reach into five official sources — the Ministry of Justice (the KRS company register), the Ministry of Finance (the VAT White List and the CRBR beneficial-owners registry), Poland's Ministry of Interior (its national sanctions list), and the OpenSanctions aggregator (EU/UN/OFAC sanctions plus global PEP data) - and a risk engine combines the results into one assessment, following the Act's own thresholds: any sanctions or PEP hit automatically raises the risk to high and triggers enhanced due diligence.

What this tool does not pretend to do

Public registries have real limitations - and we'd rather the tool say so plainly than quietly skip a step.

CRBR — The public beneficial-owners search is protected by an invisible Google CAPTCHA. This tool does not attempt to bypass it - instead it clearly reports that a given entity needs manual verification, with a link to the official search UI.
KRS — The public company-register API masks board members' personal data (e.g. J*****). Full identification still has to rest on the representative's ID document anyway — the tool flags this itself instead of falsely reporting "all clear."
CEIDG — The sole-trader register requires its own API token (free after registration). Without it, company checks work normally and the sole-trader check is simply skipped — with a clear note explaining why.

A finished document, not raw data

Every check ends in a Client AML Risk Assessment Card - the exact document a firm has to keep on file anyway, just already written.

Markdown - to paste into an internal system, edit further, or feed into your own automation. Plain text, no locked-in format.
PDF - to sign, print, and send to the client. Full Polish diacritics render correctly - even inside the bank-account table.

The document defaults to Polish, since that's the language a Polish firm's records are kept in, but every tool takes a language parameter - switch it to English with a single word if a client or auditor needs that. The server itself stores nothing: no client database, no query history beyond your own environment. The five-year retention duty stays exactly where it should: with the firm.

Who this is for

An independent accounting firm - install it once in Claude Desktop or Claude Code, and from then on every new client is one prompt, not thirty minutes of clicking through registries.
An accounting-software vendor - the code is open (MIT license) and embeddable as an integration inside a platform like Comarch Optima, inFakt, or wFirma - an AML module as a built-in feature, not one more browser tab.

Five registries. One prompt. The rest is coffee.

The source is fully open on GitHub — browse it, run it locally, or self-host it so client data never leaves your own infrastructure except for calls to the official registries.

→ View the repository on GitHub

MIT License · Python + FastMCP · data from KRS, CEIDG, the Finance Ministry's White List, CRBR, OpenSanctions, and the MSWiA list.

AML Poland MCP is an open tool for accounting firms. It does not replace the judgment of a designated AML/compliance officer.