English for .NET Minimal API Developers

ASP.NET Core’s Minimal API style strips away controller boilerplate, but the underlying vocabulary — the request pipeline, dependency injection scopes, and endpoint filters — is unchanged from full ASP.NET Core, and precise about lifetimes and ordering. This guide covers the English used when discussing .NET Minimal API code with a team.

Key Vocabulary

Endpoint — a mapped route and handler defined with methods like MapGet or MapPost, the Minimal API equivalent of a controller action. “Let’s extract these related endpoints into an endpoint group with MapGroup instead of repeating the /api/orders prefix on each one.”

Dependency injection (DI) scope — the lifetime a registered service is resolved with: singleton, scoped, or transient, controlling whether an instance is shared across a request, the app, or created fresh each time. “That DbContext is registered as scoped, but you’re injecting it into a singleton service — that’s a captive dependency and it’ll throw at runtime.”

Middleware pipeline — the ordered sequence of components (UseAuthentication, UseRouting, custom middleware) a request passes through before reaching an endpoint. “Authentication middleware needs to run before authorization in the pipeline — right now they’re in the wrong order and every request is being rejected.”

Endpoint filter — a Minimal API feature for running logic (like validation or logging) before or after an endpoint’s handler, without wrapping the whole pipeline in middleware. “Instead of duplicating this validation in every handler, add it as an endpoint filter so it runs consistently across the group.”

Options pattern — binding a configuration section to a strongly-typed class via IOptions<T>, rather than reading raw configuration strings scattered through the code. “Don’t call Configuration["Smtp:Host"] directly in the service — bind it to a typed SmtpOptions class with the options pattern so it’s validated and testable.”

Captive dependency — a bug where a longer-lived service (like a singleton) holds a reference to a shorter-lived one (like a scoped service), causing the shorter-lived instance to outlive its intended scope. “That’s a captive dependency — the singleton cached the scoped repository from its first resolution, so every request after the first is using stale, disposed data.”

Common Phrases

• “What lifetime is this service registered with — singleton, scoped, or transient?”
• “Is this middleware ordered correctly relative to authentication and authorization?”
• “Could this validation be an endpoint filter instead of duplicated per handler?”
• “Are we reading configuration directly, or is this bound with the options pattern?”
• “Is there a captive dependency here — is a singleton holding a scoped service?”

Example Sentences

Reviewing a pull request: “This handler injects IHttpContextAccessor into a singleton service to read the current user — that pattern is fragile, let’s pass the user explicitly as a parameter instead.”

Explaining a design decision: “We grouped the order endpoints with MapGroup and applied a shared authorization filter, so adding a new order endpoint automatically inherits the access control.”

Describing a bug: “The intermittent ‘disposed context’ exception was a captive dependency — a singleton had cached a scoped DbContext from its very first request.”

Professional Tips

• Say “scoped,” “singleton,” or “transient” explicitly when discussing DI lifetimes — “it’s registered as a service” is too vague to reason about correctness.
• When reviewing pipeline configuration, ask “what order do these run in?” — middleware order bugs are common and English reviewers frame them as “runs before/after.”
• Use “captive dependency” as the precise term for a longer-lived service holding a shorter-lived one — it’s immediately recognized by experienced .NET reviewers.
• Distinguish “endpoint filter” (Minimal API-specific, per-endpoint) from “middleware” (pipeline-wide) when proposing where cross-cutting logic should live.

Practice Exercise

1. Explain in two sentences what a captive dependency is and why it’s dangerous.
2. Write a one-sentence code review comment recommending an endpoint filter instead of duplicated validation.
3. Describe, in your own words, the difference between scoped and singleton service lifetimes.