Csharp Dotnet Agent Skill

Modern C# and .NET services

You write and review C#, ASP.NET Core APIs, and EF Core data access. You own the

.NET idioms, the HTTP-contract patterns *as expressed in .NET*, async correctness,

and the .NET-specific quality/security gates. You delegate everything language-

agnostic to the right sibling.

**Target: .NET 10 (LTS, released 2025-11-11, supported 3 years) with C# 14, EF Core

10, ASP.NET Core 10.** .NET 9 / C# 13 is the immediate STS predecessor — still in

support but shorter-lived. Features gate on the target framework moniker (TFM): a

net10.0 project gets C# 14 by default; a net9.0 project caps at C# 13. When you

use a C# 14 feature (field, extension members, null-conditional assignment), say

which TFM it requires.

When NOT to use — delegate

| Situation | Route to |

|---|---|

| Java / Spring Boot backend | spring-boot |

| Node / NestJS TypeScript backend | nestjs |

| Language-agnostic threat modeling, OWASP authz/abuse review | ../secure-coding/SKILL.md |

| Raw Postgres schema/index/query tuning | ../postgresdb/SKILL.md |

| Framework-neutral REST resource taxonomy | api-design |

| Dockerfile / CI pipeline / deploy target | ../deployment/SKILL.md |

| Recording per-project conventions in the workspace wiki | ../harness/SKILL.md |

The .NET *expression* of an API contract and async correctness live HERE. Resource

naming theory lives in api-design; the JVM and Node counterparts are spring-boot

and nestjs.

Project & solution layout + dotnet CLI

dotnet new sln -n Shop                         # solution
dotnet new webapi -n Shop.Api                  # minimal API (default in .NET 10)
dotnet new webapi -n Shop.Api --use-controllers # opt into MVC controllers instead
dotnet new xunit -n Shop.Api.Tests             # test project
dotnet sln add Shop.Api Shop.Api.Tests         # wire into the solution
dotnet add Shop.Api package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet ef migrations add Initial -p Shop.Api   # create a migration
dotnet ef database update -p Shop.Api          # apply migrations
dotnet build -warnaserror                      # compile; analyzers + NRT as errors
dotnet test                                    # run tests
dotnet format                                  # apply style; --verify-no-changes in CI
dotnet publish -c Release                       # produce deployable output

Recommended shape:

Shop.sln
Directory.Packages.props    # central package management: <PackageVersion> here, no versions in csproj
Directory.Build.props       # shared <Nullable>enable</Nullable>, <TreatWarningsAsErrors>, LangVersion
src/Shop.Api/               # endpoints grouped by feature module (Products/, Orders/)
src/Shop.Domain/            # entities, value objects (no EF/ASP.NET dependency)
tests/Shop.Api.Tests/

Central package management: turn it on with <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>

and list versions once in Directory.Packages.props. Why: one source of truth, no

version drift across projects.

NRT on for every project — <Nullable>enable</Nullable> in Directory.Build.props.

Why: the compiler turns whole classes of NullReferenceException into build-time

warnings. Never disable it to silence a warning — fix the nullability.

Modern C# idioms (C# 14 / .NET 10)

DTO as a record, not a class:

// Bad: mutable class, no value equality, hand-written boilerplate
public class ProductDto { public int Id { get; set; } public string Name { get; set; } }

// Good: immutable record DTO
public record ProductDto(int Id, string Name, decimal Price);

Why: value equality, with expressions, no boilerplate — and never reuse an EF entity

as the wire DTO (see anti-patterns).

Pattern matching over if-chains:

// Bad
if (shape is Circle) { var c = (Circle)shape; return Math.PI * c.R * c.R; }

// Good
return shape switch
{
    Circle c      => Math.PI * c.R * c.R,
    Rectangle r   => r.W * r.H,
    _             => throw new ArgumentOutOfRangeException(nameof(shape)),
};

field keyword — field-backed property without a hand-written backing field

(requires C# 14 / net10.0):

// Bad: explicit backing field just to trim a string
private string _name = "";
public string Name { get => _name; set => _name = value.Trim(); }

// Good (C# 14)
public string Name { get; set => field = value.Trim(); }

Primary constructors, required/init, collection expressions:

public class OrderService(IOrderRepository repo, ILogger<OrderService> log)  // primary ctor: DI in one line
{
    public required string Region { get; init; }                            // must be set at construction, then immutable
    private static readonly int[] DefaultTiers = [1, 2, 3];                  // collection expression
}

Prefer NRT annotations over defensive null checks: declare string? note when null is

valid and let the compiler force callers to handle it, instead of if (x == null)

guards scattered everywhere.

Dispose deterministically: using / await using (or using declarations) for

anything IDisposable/IAsyncDisposable. Why: leaked connections and handles.

async/await correctness

This is the highest-leverage area to get right. Core rules in body; the full catalog

(ConfigureAwait, ValueTask, IAsyncEnumerable, Channels, parallelism, deadlock cases)

is in references/async.md — read it before any non-trivial async review.

• No async void except top-level event handlers. Why: exceptions escape onto the

thread pool and crash the process; the caller cannot await or catch it. Use async Task.

• Never .Result / .Wait() / GetAwaiter().GetResult() on the request path. This

is the classic deadlock and the answer to "my endpoint hangs under load":

// Bad: blocks the thread on an async call -> thread-pool starvation / deadlock under load
public IActionResult Get() => Ok(_svc.LoadAsync().Result);

// Good: await all the way up
public async Task<IActionResult> Get(CancellationToken ct) => Ok(await _svc.LoadAsync(ct));

• Flow CancellationToken from the endpoint down into every async call —

SaveChangesAsync, queries, outbound HTTP. Why: a dropped token means the request

keeps running after the client gives up.

• ValueTask only for hot paths that usually complete synchronously; default to

Task. Never await a ValueTask twice.

• IAsyncEnumerable<T> for streaming results instead of materializing a huge list.

ASP.NET Core APIs

Decision: minimal API for new services; controllers only when you need MVC

machinery (model binding conventions, action filters at scale, views). Both can coexist.

Why minimal by default: less ceremony, first-class in .NET 10.

Production minimal API shape — route group + DataAnnotations validation (built in for

minimal API parameters in .NET 10) + ProblemDetails + OpenAPI 3.1:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();                 // OpenAPI 3.1, JSON Schema 2020-12
builder.Services.AddProblemDetails();          // RFC 9457 error bodies
builder.Services.AddDbContext<ShopDb>(o => o.UseNpgsql(builder.Configuration.GetConnectionString("Shop")));

var app = builder.Build();
app.MapOpenApi();                              // serves the OpenAPI document
app.UseExceptionHandler();                     // emits ProblemDetails on unhandled errors

var products = app.MapGroup("/products").WithTags("Products");
products.MapGet("/{id:int}", async (int id, ShopDb db, CancellationToken ct) =>
    await db.Products.AsNoTracking()
        .Where(p => p.Id == id)
        .Select(p => new ProductDto(p.Id, p.Name, p.Price))   // project to DTO, no entity leak
        .FirstOrDefaultAsync(ct) is { } dto
        ? Results.Ok(dto)
        : Results.NotFound());
products.MapPost("/", async (CreateProduct req, ShopDb db, CancellationToken ct) =>
{   // DataAnnotations on CreateProduct are validated automatically in .NET 10
    var entity = new Product { Name = req.Name, Price = req.Price };
    db.Products.Add(entity);
    await db.SaveChangesAsync(ct);
    return Results.Created($"/products/{entity.Id}", new ProductDto(entity.Id, entity.Name, entity.Price));
});
app.Run();

DI lifetimes: Singleton (one for the app), Scoped (one per request — DbContext

lives here; it is not thread-safe, so sharing one across requests corrupts change

tracking), Transient (new each resolve). Never inject a Scoped service into a

Singleton (captive dependency — see anti-patterns). Middleware ordering, endpoint

filters, the options pattern, and auth defaults are in references/aspnetcore.md.

EF Core 10

// Bad: tracking + N+1 — loads orders, then one query per order's customer
var orders = await db.Orders.ToListAsync(ct);
foreach (var o in orders) { var name = o.Customer.Name; /* lazy/round-trip per row */ }

// Good: no-tracking read + single query via projection
var rows = await db.Orders.AsNoTracking()
    .Select(o => new OrderRow(o.Id, o.Customer.Name))   // EF translates to one JOIN
    .ToListAsync(ct);

• AsNoTracking() on every read-only query — skips change-tracking overhead.
• Kill N+1 with projection (Select) or Include/ThenInclude; use AsSplitQuery()

when an Include cartesian explosion hurts.

• Migrations: dotnet ef migrations add <Name> then review the generated Up/Down

before database update. Never hand-edit applied migrations.

• EF Core 10 highlights: native json column type, vector type + VECTOR_DISTANCE()

for embeddings/RAG, LeftJoin/RightJoin LINQ operators, and named query filters

(multiple filters per entity, selectively disabled).

Raw SQL only via parameterized FromSql/ExecuteSql interpolated strings (EF

parameterizes the holes). Query patterns, migration workflow, the EF Core 10 features,

and raw-SQL safety in full are in references/efcore.md. Schema/index tuning is

../postgresdb/SKILL.md.

.NET security controls

Keep only the .NET-specific controls here; threat modeling and OWASP review go to

../secure-coding/SKILL.md.

• Parameterized data access — EF LINQ / parameterized FromSql / ADO.NET

SqlParameter. Never concatenate user input into SQL. Why: SQL injection.

• Secrets — dotnet user-secrets in dev, Key Vault / environment in prod. Never in

appsettings.json or source.

• Antiforgery for cookie-auth browser POSTs; Data Protection for cookies/tokens

(configure a persisted key ring across instances).

• Auth defaults — authenticate then authorize via middleware; prefer policy-based

authorization; ASP.NET Core 10 is secure-by-default but still verify HTTPS redirection

and HSTS in production.

Testing

• xUnit is the default. Unit-test domain logic with no framework dependency.
• Integration tests via WebApplicationFactory<Program> — boots the real pipeline

in-memory and lets you HttpClient your endpoints.

• Testcontainers to run a real Postgres in a container for EF integration tests

instead of the in-memory provider (which lies about relational behavior).

• Gate everything with scripts/verify.sh (format + build-warnaserror + test + vuln scan).

Anti-patterns

| Anti-pattern | Why it bites | Do instead |

|---|---|---|

| async void (non-event-handler) | Exceptions crash the process; uncatchable by caller | async Task |

| .Result / .Wait() on request path | Deadlock / thread-pool starvation under load | await all the way |

| Scoped service injected into a Singleton | Captive dependency: stale/DbContext reused across requests | Inject IServiceScopeFactory, or make the consumer scoped |

| Reusing an EF entity as the wire DTO | Over-posting, serialization cycles, leaked columns | Separate record DTO + mapping |

| Tracking queries on read-only reads | Wasted memory/CPU on change tracking | AsNoTracking() |

| Lazy navigation in a loop | N+1 round-trips | Projection or Include |

| Missing CancellationToken | Work continues after client disconnects | Flow the token to all I/O |

| catch (Exception) { } swallow | Hides failures; corrupt state continues | Handle specifically or let UseExceptionHandler map it |

| <Nullable>disable</Nullable> to mute a warning | Re-opens the NRE class of bugs | Keep NRT on; fix the nullability |

Project grounding

Record per-project conventions (target TFM, package manager, lint rules, deploy

target) in the workspace wiki via ../harness/SKILL.md, not inline assumptions. Before

calling a C# change done, run scripts/verify.sh from the solution/project root.