Csharp Dotnet Engineering

C# and .NET Engineering

Use this skill for project-neutral C# implementation and the .NET SDK, MSBuild, NuGet, ASP.NET Core, EF Core, and testing mechanics that its target repository actually uses. Inspect the repository before selecting an SDK, project SDK, test platform, framework, package source, command, or template.

Current Official Evidence Baseline

This is a dated research baseline, not a target-repository support declaration. All sources below are official Microsoft product documentation or policy and were retrieved 2026-08-01 UTC. A source's documentation page is authoritative only for the scope shown; the target repository's pins and its supported target environment decide applicability. Do not treat an undocumented combination as supported.

The table intentionally records uncertainty rather than fabricating a document revision when a Microsoft Learn page exposes no immutable revision. Re-retrieve the exact official page for a later decision, especially after an SDK/framework release or when the target uses a preview feed, SDK, workload, package, or framework.

No SDK, workload, template, tool, package, restore, build, or test was installed or executed to establish this baseline.

Scope and Routing

Use this skill for C# source, compiler/language settings, .NET project and solution layout, SDK/MSBuild mechanics, NuGet workflow, ASP.NET Core/Blazor implementation, EF Core adapter mechanics, and .NET test implementation.

• Use api-design when an HTTP, RPC, SDK, CLI, event, serialization, versioning, or error contract is being designed or changed; keep C# handlers and types here.
• Use sql-engineering plus the matching engine skill for database-native schema, query, transaction, index, privilege, RLS, migration, or plan behavior. This skill owns EF Core/C# adapter mechanics, not database semantics.
• Use webassembly-engineering for a general Wasm artifact, WASI/WIT, Component Model, host/guest ABI, runtime, capability, packaging, or deployment decision. Keep C#, Razor, Blazor, SDK, and test mechanics here; do not duplicate the Wasm host/runtime owner.
• Use ci-release-engineering for checked-in hosted workflow/release behavior and container-engineering for Docker/OCI or Compose behavior. This skill owns the C# commands those workflows invoke.
• Use dependency-supply-chain-review, security-review, and security-review-evidence before executing an input that can restore, load, generate, compile, or run third-party code. The required pre-execution gate is defined below; this skill owns only the .NET mechanics after the gate is satisfied.
• Use parallelism-engineering when CPU-bound partitioning, worker bounds, reductions, cancellation across workers, or oversubscription is the design problem. Keep ordinary C# async I/O, Task lifetime, and framework mechanics here.
• Use observability-engineering for telemetry semantics, correlation, metrics, traces, dashboards, alerts, or SLOs; keep .NET logging and instrumentation implementation mechanics here.
• Use mcp-server-engineering for MCP protocol, transport, tool/resource/prompt, and capability-contract work. Keep the C# SDK, hosting, and test implementation mechanics here.
• Use playwright-e2e for checked-in browser E2E test design, css-scss-styling for stylesheet decisions, test-driven-development for implementation-driving regression tests, testing-strategy for a test-suite audit or plan, and documentation-engineering for reader-facing docs after behavior is settled.

MCP SDK Composition

For MCP implementation, load mcp-server-engineering and its dated SDK selection record. The selection record is the canonical source for the selected C# lane's retrieval-time authority, package/version, tier, core-revision, transport, and conformance caveats. It is not a target-repository pin or local test result.

MCP .NET Mechanics

Use this section only after loading mcp-server-engineering and its dated SDK selection record. Those sources own the selected MCP revision, capability contract, and transport rules; this section owns only .NET package and implementation mechanics.

• Discover and resolve packages: inspect Directory.Packages.props, every PackageReference, packages.lock.json, NuGet.Config, target frameworks, and CI restore policy. Select the resolved ModelContextProtocol SDK surface and any hosting/ASP.NET Core companion package from the target's compatible package graph and the resolved-version API docs. Keep related SDK packages in the versions the repository resolves; do not infer compatibility from the dated record or add a package solely to try an example.
• Compose server and client wiring at the edge: register the SDK server, handlers, dependencies, and serializers through the target's existing generic host, DI container, or ASP.NET Core composition root. Keep tool/resource/prompt application operations as ordinary typed services; let a thin SDK adapter map requests and results. For clients, construct the SDK client with the selected transport in a scoped factory/service rather than exposing transport/session objects through domain APIs.
• Integrate the selected transport idiomatically: bind a local adapter to the application's console/process lifetime, or a remote adapter to the repository's ASP.NET Core pipeline and endpoint configuration. Do not recreate protocol framing, discovery, or transport policy in handlers; obtain those behaviors from the parent skill and selected SDK. Thread request-abort and host-stopping cancellation tokens through owned work.
• Use types as the schema boundary: model SDK inputs and structured outputs as explicit C# records/classes with nullable and serialization policy made visible. Use the resolved SDK's supported schema derivation/generation path, then test representative valid and invalid payloads plus structured-output serialization. C# type checking or a generated schema alone does not validate untrusted runtime input.
• Make ownership and shutdown explicit: make each SDK client, server connection, stream, and transport adapter have one owner. Use the target's host lifetime, CancellationToken, IAsyncDisposable, and await using conventions; await cleanup in the composition layer and do not dispose container-owned services from handlers. Verify the selected SDK's close and disposal APIs instead of assuming a host stop closes every resource.
• Test at .NET boundaries: use the repository's configured test platform and framework. Unit-test typed handlers with fakes at application boundaries; integration-test the resolved SDK adapter, schema conversion, cancellation, and cleanup with an SDK-supported local/in-memory fixture when available. Exercise a real selected transport only in an authorized repository test lane; the parent MCP skill defines the protocol scenarios that fixture must cover.

Repository-First Workflow

1. Inspect global.json; *.sln, *.slnx, and solution filters; every project and its Sdk/imports; Directory.Build.props, Directory.Build.targets, Directory.Packages.props, and other imported props/targets; NuGet.Config, package lock/central-package files, and local tool manifest; .editorconfig, analyzer/global-config files, *.runsettings, source generators, CI, README/ AGENTS guidance, and test projects. Record the selected SDK and rollForward; TFM(s), runtime identifier(s), LangVersion, nullable policy, warning/analyzer/format policy; project SDK and build graph; package sources and central/locked package policy; test platform/framework; and existing format, restore, build, test, pack, and publish commands.
2. Classify the change: C# behavior, build/project graph, dependency, public contract, ASP.NET Core endpoint/pipeline, Razor/Blazor component, EF adapter, database behavior, test, or deployment. Load only the companion skills whose boundary the evidence reaches.
3. Derive commands from target evidence. Prefer its documented recipe, checked-in scripts, CI command, and pinned SDK. If none exists, select only a CLI command available in the resolved SDK and state the assumption. Never turn the baseline examples or a newest SDK into a repository mandate.
4. Complete the pre-execution provenance gate before a command can restore, load, generate, compile, or execute external inputs. Then specify behavior and edge cases before editing. Use test-driven-development for focused behavior/regression work and behavior-driven-development for user-visible workflows.
5. Keep domain policy independent of ASP.NET Core, EF Core, transport, persistence, and UI details unless the project intentionally makes the code an adapter. Load the appropriate architecture skill when that boundary is the design problem.
6. After the gate, run the narrowest repository-approved format, restore, build, test, migration, pack, publish, or target-environment check first, then the broader applicable lane. Report commands not run and the version-sensitive reason; do not claim a framework, browser, database, or CI matrix from a local result.

Executable Input and Provenance Gate

Treat the following as executable supply-chain inputs, even when their extension or purpose suggests configuration rather than code:

• an SDK selected by global.json, project SDK, MSBuild import, custom .props/.targets, task assembly, build hook, package restore hook, or repository template;
• every NuGet package, feed, package source mapping, lock/restore graph, and package-provided build target/task;
• analyzer, compiler extension, source generator, test adapter, template, workload, dotnet tool, local tool manifest entry, and generator output whose source is not already trusted; and
• any invocation of dotnet restore, build, test, format, pack, publish, new, workload, tool, a custom dotnet command, or direct MSBuild that can cause one of those inputs to be restored, loaded, generated, compiled, or executed.

Before executing any such surface, load dependency-supply-chain-review, security-review, and security-review-evidence. Establish the applicable package/tool/template/workload/import identity, version or digest, publisher and registry/feed, lock/source mapping, transitive and build-time effects, and repository approval policy. Perform the security review and retain only sanitized evidence. A lockfile, cache, signature, or previous successful build is evidence to assess, not permission to execute. If provenance or policy is unresolved, do not run the command; report the blocked input and missing evidence instead. Static inspection that does not load or execute these inputs is not a substitute for the gate, but may establish what needs review.

Version and Project Rules

• Treat the TFM, SDK selection, runtime/deployment target, and package graph as a compatibility set. A compiler accepting syntax does not prove the target runtime, reference assemblies, framework libraries, provider, browser, or host supports it.
• Let the target framework select the normal C# language version. Do not set LangVersion to latest; use preview only when the target explicitly needs a preview and its SDK, CI, deployment, and support policy allow it. Record that preview status in the change and test it with the exact selected SDK.
• Do not silently create, remove, or change global.json, rollForward, solution format, project SDK, workload, TFM, runtime identifier, source generator, or build import. These alter build selection or graph behavior.
• Preserve SDK-style/MSBuild structure and existing property/item/target policy. Avoid overriding imported defaults or using broad Directory.Build.* changes for a local concern without proving their affected project set.
• Use the repository's existing NuGet source, central version, lock, restore, and package-reference conventions. A package change is both a compatibility and supply-chain change; do not hand-edit generated restore assets or lock data.
• Preserve the repository's solution extension. In particular, do not infer that .slnx automation is valid on .NET 9 or earlier from .NET 10 documentation.
• Treat nullable annotations, warning levels, analyzers, editor configuration, and formatter settings as part of the compilation contract. Follow the repository's configured diagnostic policy rather than suppressing warnings or introducing an analyzer/formatter as a local preference.
• Select restore/build/test/format/pack/publish mechanics from checked-in scripts, CI, and the resolved SDK. Do not assume a command's default configuration, solution selection, runtime identifier, test runner, package output, or reproducibility option; record each explicitly when it matters.

C# and Framework Implementation Checks

• Make nullability, ownership/disposal, cancellation, async completion, exception mapping, culture/time handling, and serialization behavior explicit at public and external boundaries. Do not use nullable suppression or broad exception catches to hide an unmodeled state.
• Make the owner of every IDisposable, IAsyncDisposable, stream, response, cancellation registration, timer, and scope clear. The code that creates or explicitly takes ownership performs the matching cleanup; do not dispose an injected/shared dependency. Use await using when asynchronous disposal is required and preserve cancellation and exceptions rather than fire-and-forget work across a request, scope, or process boundary.
• Model expected failures with types, result/error paths, and boundary-specific exception translation. Preserve diagnostic context without exposing internal or sensitive details; use security review for a trust-boundary error surface.
• Keep services, handlers, controllers, Razor components, DbContext, entities, and provider APIs at their intended adapter/framework boundary. Avoid leaking them into domain contracts without an explicit architecture decision.
• For ASP.NET Core, derive middleware order, DI lifetime, configuration binding, authentication/authorization, endpoint behavior, environment handling, and server hosting/deployment from the target application and framework version. Validate options at the boundary, avoid singleton capture of scoped services, and keep middleware/request scopes and cancellation flow intentional. Use security-review and security-review-evidence for auth, sessions, cookies, CORS/CSRF/CSP, secrets, file paths/uploads, redirects, command execution, or another trust boundary.
• For EF Core, select provider APIs and migrations using the exact EF/runtime and database versions. Treat DbContext as a short-lived unit-of-work; choose tracking, projections, loading, transaction, concurrency, and query execution deliberately. Test queries and migrations against a representative provider; an in-memory substitute is not evidence of relational/database behavior. Route migration SQL, schema, index, transaction, privilege, RLS, and query-plan decisions to the matching SQL owner.
• For Blazor, keep Razor/C# component, rendering, DI, JS-interop, and test mechanics here. Treat browser support, download delivery, capabilities, Wasm runtime/ABI, and packaging as separate evidence questions under webassembly-engineering.

Dependencies, Testing, and Validation

• Match tests to the configured platform and framework; the test framework and test platform are distinct decisions. Cover pure C# behavior narrowly, use integration tests for framework/database/filesystem/network wiring, and use target-environment tests for browser, provider, and deployment claims.
• Prefer behavior-focused tests at the smallest useful boundary. Make fixtures and builders express domain intent; avoid tests coupled to private implementation, broad mocks that restate framework behavior, order-dependent shared state, or an in-memory EF substitute standing in for provider behavior. Use a test double only at a genuine boundary and assert externally meaningful outcomes.
• Keep tests deterministic: control clocks, randomness, environment, ports, temporary paths, global static state, parallel execution, and external services. Use random-data-identifiers for an ID, token, nonce, random fixture, or seeded test-data decision.
• Treat a passed local command as evidence only for its resolved SDK, TFM, platform, packages, configuration, and test selection. Report those limits and all skipped lanes.

Anti-Patterns

• Hard-coding the current baseline's .NET 10/C# 14 commands, project SDKs, or framework features without target-repository evidence.
• Calling a preview SDK, package, compiler feature, template, or workload stable because a nearby released framework is LTS.
• Assuming dotnet build, an IDE build, and a custom MSBuild invocation resolve the same SDK, imports, properties, or solution context.
• Treating a successful EF Core in-memory test as proof of provider SQL, migration, transaction, collation, concurrency, or performance behavior.
• Treating Blazor WebAssembly implementation as proof of a general Wasm host, runtime, capability, ABI, browser, or packaging claim.
• Installing an SDK, workload, template, tool, or package merely to discover a command. Inspect repository pins and current official documentation first.
• Running restore, build, test, format, pack, publish, template, workload, tool, analyzer, generator, or imported MSBuild work before the executable-input provenance gate has completed.
• Hiding ownership, nullability, cancellation, or failure behavior with null-forgiving operators, unbounded background tasks, broad exception catches, service-location, or a long-lived/shared DbContext.

Successful Use

Report the changed C#/project/framework surface; selected SDK, TFM, language and framework/package versions; preview/LTS/STS or unresolved-support status; commands and test results; dependency/source or security-review status where applicable; and any unverified target, provider, browser, or CI compatibility.

TypeScript Zod Interoperability

For a real TypeScript/backend JSON crossing, load zod-engineering. .NET independently validates/maps wire DTOs and safe errors; test shared malformed/null/unknown/number/date fixtures.