# .NET and C# recipes

URL: https://developertoolkit.ai/en/cookbook/backend-recipes/dotnet-patterns/
Description: Agent recipes for ASP.NET Core, EF Core and xUnit v3 — one AGENTS.md, test-first loops on real Postgres, and analyzers that fail the build, not the review.

.NET and C# recipes for AI coding agents are a repository setup plus prompts that make Claude Code, Codex and Cursor ship trustworthy ASP.NET Core and EF Core changes: one `AGENTS.md` with the exact `dotnet` commands, xUnit v3 tests written before the code and run against real PostgreSQL, and Roslyn analyzers configured so a bad pattern fails the build.

This page is for C# developers who already let an agent write most of a service. The situation it fixes: the agent's pull request compiles and its tests are green, but the tests use the EF Core in-memory provider, the new migration drops a column it meant to rename, a `.Result` blocks a thread in the middle of a request, and a fresh `#pragma warning disable` hides the one analyzer warning that would have caught it. C# gives you a compiler and an analyzer pipeline that most languages lack. The recipes below make the agent run into them on every turn, so you review evidence instead of diffs. If the repository has no `AGENTS.md` or CI gate yet, start with [Agent-ready codebase](/en/workflows/harness/agent-ready-codebase/).

## What you'll walk away with from these .NET recipes

- A `Directory.Build.props` and `global.json` that turn nullable warnings, code-quality rules and code style into build errors, and pin the SDK and test runner the agent uses.
- An `AGENTS.md` for a .NET solution, wired into Claude Code, Codex and Cursor.
- A test-first loop for an ASP.NET Core endpoint: acceptance criteria, failing xUnit v3 tests on a Testcontainers PostgreSQL database, then the implementation.
- A Claude Code `Stop` hook that refuses "done" until `dotnet build` and `dotnet test` pass, and the Codex and Cursor fallbacks: a Codex `Stop` hook or a scripted `codex exec` run, and the CI gate.
- An EF Core migration recipe with a drift check and a human sign-off on destructive changes.
- A banned-API list, an architecture test and a mutation-testing run that catch what agents get wrong in C#.
- The failure modes specific to .NET agent work, with the prompt that recovers from each.

## Which .NET, EF Core and xUnit versions do these recipes assume?

Agents are trained on years of .NET samples, so they mix APIs from different major versions. Tell the agent the versions, and pin them in the repository so it cannot drift. These were current on 2026-09-26:

| Component | Version | Source (checked 2026-09-26) |
| --- | --- | --- |
| .NET (LTS) | .NET 10, runtime 10.0.12, SDK 10.0.401; supported until 2028-11-14 | `dotnet/core` releases index |
| .NET 11 | Release candidate 1 (2026-09-08), standard-term support | `dotnet/core` releases index |
| .NET 8 and .NET 9 | Both reach end of support on 2026-11-10 | `dotnet/core` releases index |
| EF Core, `dotnet-ef`, `Microsoft.AspNetCore.Mvc.Testing` | 10.0.12 | NuGet |
| `Npgsql.EntityFrameworkCore.PostgreSQL` | 10.0.3 | NuGet |
| xUnit.net v3 core framework (`xunit.v3`) | 4.0.1 (published 2026-09-12) | NuGet |
| `Testcontainers.PostgreSql` | 4.15.0 | NuGet |

The recipes target .NET 10. If you are still on .NET 8 or 9, the upgrade is the first agent task worth running, because both lose support in November.

Stay on your tool's default model for this work and raise effort before switching models. Current defaults and prices are on the [AI models hub](/en/ecosystem/models/).

## How do you make a .NET solution agent-ready?

Put the gates in MSBuild, not in a prompt. An instruction such as "write clean code" is forgotten by the next session. A property in `Directory.Build.props` applies to every project, every session and every CI run. Three files at the solution root do most of the work.

`Directory.Build.props` turns warnings into errors and raises the analyzer bar:

```xml
<!-- Directory.Build.props: applies to every project under this folder -->
<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  </PropertyGroup>
</Project>
```

`AnalysisLevel` set to `latest-recommended` enables the recommended set of CA code-quality rules. `EnforceCodeStyleInBuild` makes the IDE code-style rules that your `.editorconfig` sets to `warning` or `error` run on `dotnet build`, so they reach the agent's terminal and not only the IDE. `RestorePackagesWithLockFile` writes `packages.lock.json`, which lets CI restore with `--locked-mode` and fail when the agent changes a dependency without committing the lock file.

`global.json` pins the SDK and puts `dotnet test` on Microsoft Testing Platform (MTP), the mode xUnit v3's documentation describes for .NET SDK 10 and later:

```json
{
  "sdk": { "version": "10.0.401", "rollForward": "latestFeature" },
  "test": { "runner": "Microsoft.Testing.Platform" }
}
```

A local tool manifest gives the agent the same `dotnet ef` version as CI, instead of whatever is installed globally:

```bash
# terminal, at the solution root
dotnet new tool-manifest
dotnet tool install dotnet-ef
dotnet new install xunit.v3.templates   # adds the xunit3 project template
```

In MTP mode, `dotnet test` takes a project with `--project` and a solution with `--solution` instead of a bare path, and xUnit v3 filters become options such as `--filter-class`. Agents trained on VSTest-era samples write `dotnet test MyProject.csproj --filter …`, so put the new spelling in `AGENTS.md`.

## What goes in AGENTS.md for a .NET repository?

Write the commands the agent must run, in the order it must run them, and the few rules a generic C# model gets wrong in your codebase. Keep it short; everything that MSBuild already enforces stays out.

```markdown title="AGENTS.md"
# Orders service (.NET 10, ASP.NET Core minimal APIs, EF Core 10, PostgreSQL)

## Commands (run from the repo root)
- Restore: `dotnet restore --locked-mode` (commit packages.lock.json if you add a package)
- Build: `dotnet build --no-restore` (warnings are errors; fix the code, never add NoWarn or #pragma)
- Test all: `dotnet test --no-build` (needs Docker: integration tests start PostgreSQL with Testcontainers)
- Test one class: `dotnet test --project tests/Orders.Api.Tests --filter-class Orders.Api.Tests.CreateOrderTests`
- Format: `dotnet format --verify-no-changes`
- Migration drift: `dotnet ef migrations has-pending-model-changes --project src/Orders.Infrastructure --startup-project src/Orders.Api`

## Definition of done
Build, tests, format and the drift check all pass. Report the commands you ran and their result.

## Rules
- Tests are the specification. If a test fails, fix src/, not tests/. Ask before changing an assertion.
- Integration tests use the ApiFactory fixture (real PostgreSQL). Never use the EF Core in-memory provider.
- Package versions live in Directory.Packages.props. Never put Version= on a PackageReference.
- Time comes from TimeProvider, never DateTime.Now or DateTime.UtcNow.
- async all the way down: no .Result, .Wait() or GetAwaiter().GetResult().
- Read-only queries use AsNoTracking(). Queries that Include two or more collections use AsSplitQuery().
- Never edit an existing migration. Add a new one.
```

Each tool loads the same file differently:

**Claude Code**

    Create a `CLAUDE.md` whose first line imports the shared file, then add any Claude-only lines below it:

    ```markdown title="CLAUDE.md"
    @AGENTS.md
    ```

    Claude Code 2.1.277 and later also read `AGENTS.md` directly when a project has no `CLAUDE.md` (v2.1.281 on Bedrock, Google Cloud, Foundry and LLM gateways; both release channels on 2026-10-12). The import works on every version and channel. For code navigation, add the C# language server plugin described in [How do you give the agent current .NET docs and code navigation?](#how-do-you-give-the-agent-current-net-docs-and-code-navigation).

**Codex**

    Codex reads `AGENTS.md` before it starts work. Run `/init` in the TUI to draft one, then replace the draft with the file above. Since codex-cli 0.150.0, a project Codex does not trust does not supply its `AGENTS.md`, so trust the repository when Codex asks.

**Cursor**

    Add a project rule (Cursor's **Rules** feature, stored under `.cursor/rules/`) that applies to every agent request and tells the agent to follow `AGENTS.md`, or paste the Commands and Rules sections into it. Commit the rule with the repository. [Cursor project rules](/en/cursor-ide/quick-start/project-rules/) covers the file format and how to make a rule apply to every request.

**Copy-paste prompt: draft AGENTS.md from an existing .NET solution**

```text
Read the .sln or .slnx file, every .csproj, Directory.Build.props, Directory.Packages.props, global.json and .config/dotnet-tools.json. Write AGENTS.md with: (1) a one-line description of the solution and its target framework; (2) the exact restore, build, test, single-test-class, format and EF Core migration-drift commands for THIS repo, using `dotnet test --project ... --filter-class ...` if global.json selects Microsoft.Testing.Platform; (3) a "Definition of done" line; (4) at most eight rules, each one a convention you can see this codebase follows and a generic C# model would get wrong. Do not restate anything Directory.Build.props already enforces. Run every command you list and tell me which ones failed.
```

[Shared agent rules](/en/cto-scorecard-guide/shared-agent-rules/) explains how to keep one source of truth when a team uses all three tools.

## How do you run a test-first loop for an ASP.NET Core endpoint?

Specify the behaviour, have the agent write failing tests, check that they fail for the right reason, and only then let it write the implementation. The tests become the oracle you trust, so they must hit the same database engine as production. EF Core's in-memory provider does not enforce unique indexes, foreign keys or transactions, so a test on it proves nothing about the behaviour you care about most.

1. **Write the acceptance criteria.** Three to six observable behaviours, each one a sentence a test can check. [Acceptance criteria an agent can verify](/en/workflows/plan/acceptance-criteria/) shows the format.

2. **Ask for failing tests only.** Use the first prompt below. Stop the agent after the tests compile and fail.

3. **Read the failures, not the code.** Each test should fail on its assertion (for example, `404` instead of `201`), not on a missing class or a container error. A test that fails for the wrong reason will pass for the wrong reason too.

4. **Ask for the implementation.** Use the second prompt. The loop ends when the full gate passes, not when the agent says it is done.

5. **Check test strength.** Run mutation testing on the changed code (see [Which analyzers and tests turn review comments into build failures?](#which-analyzers-and-tests-turn-review-comments-into-build-failures)).

**Copy-paste prompt: failing xUnit v3 tests for an idempotent POST endpoint**

```text
We are adding POST /orders to src/Orders.Api (minimal APIs, EF Core 10, PostgreSQL). Acceptance criteria:
1. A valid order returns 201 with a Location header and the order id in the body.
2. A second request with the same Idempotency-Key header returns 200 with the SAME order id, and only one row exists.
3. The same Idempotency-Key with a different body returns 422.
4. A missing or empty customerId returns 400 with a ProblemDetails body naming the field.
5. Two concurrent requests with the same Idempotency-Key create exactly one order.

Write ONLY tests, in tests/Orders.Api.Tests, with xUnit v3. Use the existing ApiFactory fixture (WebApplicationFactory<Program> plus a Testcontainers PostgreSQL container); if it does not exist, create it with `new PostgreSqlBuilder("postgres:17-alpine")` (use the PostgreSQL major version you run in production) and apply migrations in InitializeAsync. Pass TestContext.Current.CancellationToken to every async call. Do not create or change anything under src/. Then run `dotnet test --project tests/Orders.Api.Tests --filter-class Orders.Api.Tests.CreateOrderTests` and show me each failure message. Stop there.
```

Check the fixture the agent writes against this shape. xUnit v3 changed `IAsyncLifetime` to `ValueTask`, and Testcontainers 4.x marks the parameterless builder constructor obsolete, so older patterns fail the build here. Set the image tag to the PostgreSQL major version you run in production; `postgres:17-alpine` is only the example:

```csharp
// tests/Orders.Api.Tests/ApiFactory.cs
public sealed class ApiFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
    private readonly PostgreSqlContainer _db = new PostgreSqlBuilder("postgres:17-alpine").Build();

    public async ValueTask InitializeAsync()
    {
        await _db.StartAsync();
        using var scope = Services.CreateScope();
        await scope.ServiceProvider.GetRequiredService<OrdersDbContext>().Database.MigrateAsync();
    }

    protected override void ConfigureWebHost(IWebHostBuilder builder) =>
        builder.UseSetting("ConnectionStrings:Orders", _db.GetConnectionString());

    public override async ValueTask DisposeAsync()
    {
        await _db.DisposeAsync();
        await base.DisposeAsync();
    }
}
```

The fixture applies your real migrations, so every integration run also proves that the migrations apply to an empty database. If the test project cannot see `Program`, the agent may add `public partial class Program;` at the end of `Program.cs`; that is the only change to `src/` the test step should make.

**Copy-paste prompt: implement until the gate is green**

```text
Implement POST /orders in src/Orders.Api and src/Orders.Infrastructure so that every test in CreateOrderTests passes. Enforce idempotency with a unique index on (IdempotencyKey) and handle the unique-violation from PostgreSQL (PostgresException with SqlState 23505) so criterion 5 holds without a lock. Store a SHA-256 hash of the canonical request body next to the key; on a 23505 conflict, return 422 if the stored hash differs, else 200 with the existing order. Add an EF Core migration named AddOrderIdempotencyKey. Do not modify any file under tests/. When you think you are done, run in order: `dotnet build --no-restore`, `dotnet test --no-build`, `dotnet format --verify-no-changes`, and the migration drift check from AGENTS.md. Paste the last lines of each. If a test still fails, tell me which acceptance criterion the code violates instead of changing the test.
```

[Protect the oracle](/en/workflows/test/protect-the-oracle/) explains why the "do not modify tests" instruction needs a mechanical backstop as well, which the next section adds.

## How do you stop the agent from declaring done before the build is green?

An instruction in `AGENTS.md` is advice. A hook or a CI check is a gate. Each tool gives you a different way to make the gate run on every turn.

**Claude Code**

    A `Stop` hook runs when Claude finishes responding. Exit code 2 prevents the stop and shows the hook's stderr to Claude, which then keeps working. Claude Code overrides the block after eight consecutive continuations, so a loop cannot run forever; the `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` environment variable sets that cap (default 8; checked against Claude Code 2.1.283, still present in 2.1.286).

    ```bash title=".claude/hooks/dotnet-gate.sh"
    #!/usr/bin/env bash
    # Refuse "done" until the solution builds without warnings and the tests pass.
    cd "$CLAUDE_PROJECT_DIR" || exit 0
    # Skip turns that changed no C#, project or gate files (a question, a plan).
    [ -z "$(git status --porcelain -- '*.cs' '*.csproj' '*.props' '*.targets' '*.sln' '*.slnx' '.editorconfig' 'BannedSymbols.txt' 'global.json' 'packages.lock.json')" ] && exit 0
    if ! out=$(dotnet build --no-restore 2>&1); then
      echo "dotnet build failed. Fix the code; do not add NoWarn or #pragma." >&2
      echo "If the error is NETSDK1004 or NU1xxx, run 'dotnet restore --locked-mode' (or update packages.lock.json) first." >&2
      echo "$out" | grep -E ": (error|warning) " | sort -u | head -30 >&2
      exit 2
    fi
    if ! out=$(dotnet test --no-build 2>&1); then
      echo "dotnet test failed. Fix src/, never tests/:" >&2
      echo "$out" | tail -40 >&2
      exit 2
    fi
    exit 0
    ```

    The skip test looks at uncommitted changes only: if the agent commits during the turn the gate does not run, so tell it not to commit (or compare against the session's starting HEAD). A tree that was already dirty runs the full gate on every turn, including pure questions.

    Register it in the project settings and make the script executable (`chmod +x`):

    ```json title=".claude/settings.json"
    {
      "hooks": {
        "Stop": [
          {
            "hooks": [
              { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/dotnet-gate.sh", "timeout": 600 }
            ]
          }
        ]
      }
    }
    ```

    The script deliberately ignores `stop_hook_active`, the field Claude Code sets in the hook input once a stop has already been blocked. Exiting 0 whenever it is true would let the second attempt through with the build still red; the eight-block cap is the loop guard instead, so a stubborn failure can cost about nine build and test runs before Claude Code stops anyway.

    The hook costs a full build and test run on every turn that changed C# or project files, including Testcontainers, so keep Docker running during the session. If that is too slow locally, run only the tests that need no Docker and leave the full suite to CI. Under MTP the VSTest `--filter` spelling does not apply; use an xUnit v3 trait filter instead. Tag each integration test class with `[Trait("Category", "Integration")]`, then change the test line in `dotnet-gate.sh`:

    ```bash
    if ! out=$(dotnet test --no-build --filter-not-trait "Category=Integration" 2>&1); then
    ```

    [Hooks automation](/en/claude-code/automate/hooks-automation/) covers the other events.

**Codex**

    NuGet restore needs the network, and the `workspace-write` sandbox has no network access unless you enable it. Restore first, outside the agent, then run the loop without network:

    ```bash
    dotnet restore --locked-mode
    codex exec --sandbox workspace-write "Implement POST /orders so every test in CreateOrderTests passes. Do not modify tests/. Finish only when 'dotnet build --no-restore' and 'dotnet test --no-build' both pass; print the last lines of each."
    ```

    If the agent must add a package, enable network for that run only with `-c sandbox_workspace_write.network_access=true`. This uses the legacy `--sandbox` system; if your config sets `default_permissions`, the two do not compose, so pick one (checked against codex-cli 0.157.1). Testcontainers also needs access to the Docker socket; if the sandbox blocks it, run the integration tests in CI and give the local loop the unit tests only.

    For an interactive session, Codex 0.157.1 also has a `Stop` hook event; [Codex automation](/en/codex/automate/) covers hook registration and trust.

**Cursor**

    Paste the implementation prompt into the agent, in Plan Mode first if the change spans several projects. Put the Definition of done in the project rule so the agent runs the commands before it reports back. Cursor also has [Hooks](https://cursor.com/docs/hooks), scripts that exchange JSON with the agent over stdio, so a hook can run the same `dotnet build` and `dotnet test` commands locally; [Use hooks as deterministic guardrails](/en/developer-scorecard-guide/agent-hooks/) shows how to adapt the Claude Code script and keep it advisory until it is tested in a real Cursor session. Cursor's own gate runs after the pull request opens: the CI job below, plus Bugbot if your team uses it for review.

Whatever runs locally, CI is the gate that decides. Run the same commands there with a read-only token:

```yaml title=".github/workflows/dotnet-gates.yml"
name: dotnet-gates
on: [pull_request]
permissions:
  contents: read
jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-dotnet@v6
        with:
          global-json-file: global.json
      - run: dotnet restore --locked-mode
      - run: dotnet tool restore
      - run: dotnet format --verify-no-changes --no-restore
      - run: dotnet build --no-restore
      - run: dotnet test --no-build
      - run: dotnet ef migrations has-pending-model-changes --project src/Orders.Infrastructure --startup-project src/Orders.Api
```

## How do you handle EF Core migrations with an agent?

Migrations are the one place where a green test suite is not enough evidence. The agent can generate a migration that applies cleanly to an empty test database and still destroys data in production. The classic case: the agent renames a property, EF Core generates a `DropColumn` plus an `AddColumn`, the tests pass on a fresh database, and the column's data is gone on the first deploy.

Split the work between gates and a person:

| Check | How | Who decides |
| --- | --- | --- |
| Model and migrations agree | `dotnet ef migrations has-pending-model-changes` (EF Core 8 and later) fails when the model changed without a migration | CI |
| Migrations apply from zero | The `ApiFactory` fixture runs `MigrateAsync()` on an empty PostgreSQL | CI |
| The SQL is what you expect | `dotnet ef migrations script --idempotent` output attached to the pull request | A human reads the SQL, not the C# |
| Destructive operations | `DropColumn`, `DropTable`, `AlterColumn` that narrows a type | A human, through `CODEOWNERS` on `**/Migrations/` |

**Copy-paste prompt: a reviewed, non-destructive EF Core migration**

```text
Rename the Order.Notes property to Order.CustomerNotes. Generate the migration with `dotnet ef migrations add RenameOrderNotes --project src/Orders.Infrastructure --startup-project src/Orders.Api`. Open the generated file: if it contains DropColumn plus AddColumn for this change, replace them with migrationBuilder.RenameColumn so no data is lost. Do not edit any earlier migration. Then run `dotnet ef migrations script --idempotent --project src/Orders.Infrastructure --startup-project src/Orders.Api -o artifacts/migration.sql` and show me only the SQL for this migration, plus the result of `dotnet ef migrations has-pending-model-changes`. List every statement that could lose data, or say "none".
```

For the wider rules on expand-and-contract changes and rollbacks, see [database migration patterns](/en/cookbook/database-recipes/migration-patterns/). EF Core 11 adds a `.config/dotnet-ef.json` file for default `--project` and `--startup-project` values; on EF Core 10, keep the flags in `AGENTS.md`.

## Which analyzers and tests turn review comments into build failures?

Every comment you type twice on an agent's pull request is a rule you have not automated yet. In C#, most of them can become a compiler diagnostic or a test. Each gate below goes red for a specific bug:

| Gate | Setup | Goes red when |
| --- | --- | --- |
| Nullable reference types | `<Nullable>enable</Nullable>` plus `TreatWarningsAsErrors` | The agent dereferences a value that can be null |
| CA code-quality rules | `<AnalysisLevel>latest-recommended</AnalysisLevel>` | Code breaks a rule in the recommended CA set (design, reliability, performance, security and usage rules) |
| Code style | `.editorconfig` severities plus `EnforceCodeStyleInBuild` | The agent ignores the team's naming or `var` conventions |
| Banned APIs | `Microsoft.CodeAnalysis.BannedApiAnalyzers` (5.6.0) and a `BannedSymbols.txt` | Code calls `DateTime.Now`, `Task.Result` or anything else you list (diagnostic RS0030) |
| Architecture | `NetArchTest.Rules` (1.3.2, last release May 2021; `TngTech.ArchUnitNET` 0.13.4 is the actively maintained alternative) in a test | The domain project references infrastructure or ASP.NET Core |
| Test strength | `dotnet-stryker` (5.0.0) | Tests still pass after Stryker mutates the code under test |

The banned-API list is the most direct way to encode "we never do that here". Add the package to the projects under `src/`, add `<AdditionalFiles Include="BannedSymbols.txt" />`, and list documentation IDs with a message the agent will read:

```text title="BannedSymbols.txt"
P:System.DateTime.Now;Inject TimeProvider and call GetUtcNow()
P:System.DateTime.UtcNow;Inject TimeProvider and call GetUtcNow()
P:System.Threading.Tasks.Task`1.Result;Await the task instead of blocking
M:System.Threading.Tasks.Task.Wait;Await the task instead of blocking
M:System.Threading.Tasks.Task.Wait(System.Int32);Await the task instead of blocking
M:System.Threading.Tasks.Task.Wait(System.TimeSpan);Await the task instead of blocking
M:System.Threading.Tasks.Task.Wait(System.Threading.CancellationToken);Await the task instead of blocking
M:System.Threading.Tasks.Task.Wait(System.Int32,System.Threading.CancellationToken);Await the task instead of blocking
M:System.Runtime.CompilerServices.TaskAwaiter.GetResult;Await the task instead of blocking
M:System.Runtime.CompilerServices.TaskAwaiter`1.GetResult;Await the task instead of blocking
```

An architecture test keeps a layered solution layered after 50 agent sessions:

```csharp
[Fact]
public void Domain_does_not_depend_on_infrastructure_or_web()
{
    var result = Types.InAssembly(typeof(Order).Assembly)
        .ShouldNot().HaveDependencyOnAny("Orders.Infrastructure", "Microsoft.AspNetCore")
        .GetResult();

    Assert.True(result.IsSuccessful, string.Join(", ", result.FailingTypeNames ?? []));
}
```

Mutation testing answers the question a green run cannot: would these tests notice if the code were wrong? Run `dotnet tool install dotnet-stryker`, then `dotnet stryker` in the test project's folder, and read the surviving mutants. [Oracle strength](/en/workflows/test/oracle-strength/) explains how to turn survivors into missing test cases.

**Copy-paste prompt: turn repeated review comments into gates**

```text
Here are review comments I keep leaving on agent pull requests in this solution: [paste 5-10 comments]. For each one, propose the cheapest mechanical gate: an .editorconfig severity, a CA rule set to error, an entry in BannedSymbols.txt, a NetArchTest rule, or an xUnit test. Show the exact change. Implement only the ones that make `dotnet build` or `dotnet test` fail on the current code, list which files would break, and do not fix those files yet.
```

Changes to `Directory.Build.props`, `.editorconfig`, `BannedSymbols.txt` and any `NoWarn` entry weaken the gates themselves, so give those paths a human owner in `CODEOWNERS`. The [evidence bundle](/en/workflows/ship/evidence-bundle/) page shows how to attach gate results and the migration SQL to the pull request so the reviewer checks proof, not code.

## How do you give the agent current .NET docs and code navigation?

Two additions help most in .NET: current Microsoft documentation, because APIs change between major versions, and a language server, because text search is a poor way to find every caller in a large solution.

**Microsoft Learn MCP server.** A remote server at `https://learn.microsoft.com/api/mcp`, no authentication, with three tools: `microsoft_docs_search`, `microsoft_docs_fetch` and `microsoft_code_sample_search`. The `?maxTokenBudget=2000` query parameter caps how much each answer adds to context; the Codex and Cursor snippets below include it. Popularity: about 1.9k GitHub stars on `MicrosoftDocs/mcp` (GitHub, read 2026-09-26).

**Claude Code**

    Install Microsoft's plugin, which brings the MCP server and its skills together (run inside a session):

    ```text
    /plugin install microsoft-docs@claude-plugins-official
    ```

    The plugin registers the uncapped URL. To add only the server, with the cap, run this in your shell instead:

    ```bash
    claude mcp add --transport http microsoft-learn "https://learn.microsoft.com/api/mcp?maxTokenBudget=2000"
    ```

    For code navigation, install the C# language server and the plugin that registers it. The plugin does not bundle the binary:

    ```bash
    dotnet tool install --global csharp-ls
    claude plugin install csharp-lsp@claude-plugins-official
    ```

    `csharp-lsp` had 43,741 installs in the claude.com plugin directory (read 2026-09-26). LSP plugins add no always-on context, because the server runs out of process.

**Codex**

    ```bash
    codex mcp add microsoft-learn --url "https://learn.microsoft.com/api/mcp?maxTokenBudget=2000"
    ```

**Cursor**

    Add the server to `.cursor/mcp.json`:

    ```json
    { "mcpServers": { "microsoft-learn": { "url": "https://learn.microsoft.com/api/mcp?maxTokenBudget=2000" } } }
    ```

Before the server, the agent fills gaps from training data and writes, for example, the parameterless Testcontainers builder or VSTest-style `dotnet test` filters. With it, one prompt checks the current API first:

**Copy-paste prompt: check .NET 10 guidance before writing code**

```text
Using the Microsoft Learn MCP server, find the current guidance for (1) running `dotnet test` with Microsoft.Testing.Platform on the .NET 10 SDK and (2) integration testing minimal APIs with WebApplicationFactory. Quote the relevant lines and their URLs. Then compare them with tests/Orders.Api.Tests and our AGENTS.md, and list anything we do that the current docs no longer recommend. Do not change files.
```

The `microsoft/skills` README catalogues 175 SDK skills in language plugins for Python, .NET, TypeScript, Java and Rust. They sit below the repository root, so `npx skills add microsoft/skills --list` shows only 13 root skills; with `--full-depth` it finds 192, the SDK set plus the root and other nested skills (checked 2026-09-26). The README also warns that loading all of them causes context rot, so install only the Azure SDK skills your service uses. The [best backend and platform skills](/en/ecosystem/skills/top-skills-backend/) page compares them with the other vendor sets.

## What breaks when agents write .NET code?

**The build breaks on an obsolete Testcontainers constructor**

Symptom: `CS0618` on `new PostgreSqlBuilder()`, which `TreatWarningsAsErrors` turns into an error. Cause: Testcontainers 4.x marks the parameterless constructor obsolete in favour of one that takes the image. Recovery: "Replace every parameterless Testcontainers builder with the constructor that takes an explicit image tag, for example new PostgreSqlBuilder(\"postgres:17-alpine\"). Do not suppress CS0618."

**The agent silences a warning instead of fixing it**

Symptom: the build is green, and the diff adds `#pragma warning disable`, a `<NoWarn>` entry or `[SuppressMessage]`. Recovery: fail CI when a pull request adds any of the three outside an approved list, and re-prompt: "Remove the suppression you added and fix the underlying diagnostic. If it is a false positive, explain why in the pull request instead."

**NU1008 after the agent adds a package**

Symptom: restore fails with `NU1008` in a solution that uses central package management. Cause: the agent wrote `<PackageReference Include="…" Version="…" />` as older samples do. Recovery: move the version into `Directory.Packages.props` as a `PackageVersion` entry, remove `Version` from the project file, and restore again to update `packages.lock.json`.

**Green tests on the in-memory provider, red in production**

Symptom: a duplicate-key or foreign-key bug that no test caught. Cause: the agent used `UseInMemoryDatabase` because it is faster to set up. Recovery: move the tests onto the Testcontainers fixture and add a line to `AGENTS.md` that bans the in-memory provider. Criterion 5 above (concurrent requests with one key) is the test that exposes the difference.

**A cartesian explosion from Include chains**

Symptom: one endpoint loads 50 orders slowly and memory spikes. Cause: `Include(o => o.Lines).Include(o => o.Payments)` in a single query multiplies rows. Recovery: "Use AsSplitQuery() on queries that include two or more collections, AsNoTracking() on read-only queries, and add a test that asserts the number of SQL commands for GET /orders." For more EF Core query patterns, see [ORM patterns](/en/cookbook/database-recipes/orm-patterns/).

**Sync over async and hidden clock reads**

Symptom: thread-pool starvation under load, or tests that fail at midnight. Cause: `.Result` or `.Wait()` in request code, and `DateTime.UtcNow` in business logic. Recovery: the `BannedSymbols.txt` entries above make `.Result`, every `Task.Wait` overload listed, `GetAwaiter().GetResult()` on `Task` and `Task<T>`, and the clock reads build errors; inject `TimeProvider` and use `FakeTimeProvider` in tests.

**Codex cannot restore or reach Docker**

Symptom: `dotnet restore` or Testcontainers fails inside `codex exec`. Cause: the `workspace-write` sandbox has no network by default. Recovery: restore before starting the session, build with `--no-restore`, and enable network for one run only when a package change is the task.

## Where to go next with .NET and agents

- [Protect the oracle](/en/workflows/test/protect-the-oracle/) — Stop agents from editing the tests that judge them.
- [Database migration patterns](/en/cookbook/database-recipes/migration-patterns/) — Expand-and-contract changes and rollbacks for the migrations above.
- [API development patterns](/en/cookbook/backend-recipes/api-patterns/) — Idempotency keys, pagination and OpenAPI contracts for the endpoints you build.
- [Java and Spring Boot patterns](/en/cookbook/backend-recipes/java-patterns/) — The same gates and loops on the JVM.
- [Fitness functions](/en/workflows/test/fitness-functions/) — Architecture and performance checks that run on every agent change.
- [Agent-ready codebase](/en/workflows/harness/agent-ready-codebase/) — The repository properties that make any agent more reliable.
