Dotnet Best Practices

.NET/C# Best Practices

Optimized for current .NET SDK-style projects, C# 12+, ASP.NET Core LTS, and current xUnit, NUnit, or MSTest workflows.

Your task is to ensure .NET/C# code in the selected scope or current solution meets the best practices specific to this project. This includes:

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Documentation & Structure

• Create comprehensive XML documentation comments for all public classes, interfaces, methods, and properties
• Include parameter descriptions and return value descriptions in XML comments
• Follow the established namespace structure: {Core|Console|App|Service}.{Feature}

Design Patterns & Architecture

• Use primary constructor syntax for dependency injection (e.g., public class MyClass(IDependency dependency))
• Implement the Command Handler pattern with generic base classes (e.g., CommandHandler<TOptions>)
• Use interface segregation with clear naming conventions (prefix interfaces with 'I')
• Follow the Factory pattern for complex object creation.

Dependency Injection & Services

• Use constructor dependency injection with null checks via ArgumentNullException
• Register services with appropriate lifetimes (Singleton, Scoped, Transient)
• Use Microsoft.Extensions.DependencyInjection patterns
• Implement service interfaces for testability

Resource Management & Localization

• Use ResourceManager for localized messages and error strings
• Separate LogMessages and ErrorMessages resource files
• Access resources via _resourceManager.GetString("MessageKey")

Async/Await Patterns

• Use async/await for all I/O operations and long-running tasks
• Return Task or Task<T> from async methods
• Use ConfigureAwait(false) where appropriate
• Handle async exceptions properly

Testing Standards

• Use MSTest framework with FluentAssertions for assertions
• Follow AAA pattern (Arrange, Act, Assert)
• Use Moq for mocking dependencies
• Test both success and failure scenarios
• Include null parameter validation tests

Configuration & Settings

• Use strongly-typed configuration classes with data annotations
• Implement validation attributes (Required, NotEmptyOrWhitespace)
• Use IConfiguration binding for settings
• Support appsettings.json configuration files

Semantic Kernel & AI Integration

• Use Microsoft.SemanticKernel for AI operations
• Implement proper kernel configuration and service registration
• Handle AI model settings (ChatCompletion, Embedding, etc.)
• Use structured output patterns for reliable AI responses

Error Handling & Logging

• Use structured logging with Microsoft.Extensions.Logging
• Include scoped logging with meaningful context
• Throw specific exceptions with descriptive messages
• Use try-catch blocks for expected failure scenarios

Performance & Security

• Use C# 12+ features and .NET 8 optimizations where applicable
• Implement proper input validation and sanitization
• Use parameterized queries for database operations
• Follow secure coding practices for AI/ML operations

Code Quality

• Ensure SOLID principles compliance
• Avoid code duplication through base classes and utilities
• Use meaningful names that reflect domain concepts
• Keep methods focused and cohesive
• Implement proper disposal patterns for resources

Anti-Patterns

• Constructing infrastructure inside business code: It defeats dependency injection and makes testing or observability much harder.
• Skipping cancellation and logging in I/O paths: Modern .NET services need both operational visibility and cooperative shutdown behavior.
• Hiding configuration behind magic strings: Options drift across environments when the contract is not explicit.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Dotnet Best Practices implementation names the target runtime, framework version, and affected files. 2. Pass/fail: Build, lint, test, or equivalent local validation is run for the changed surface. 3. Pass/fail: Edge cases for errors, dependency drift, and environment differences are addressed or explicitly out of scope. 4. Pressure-test scenario: Apply the workflow to a change that passes happy-path tests but fails one boundary condition. 5. Success metric: Zero untested success claims; every implementation claim maps to a command or artifact.

Before and After Example

// Before
public sealed class WeatherService
{
    public async Task<string> GetAsync()
    {
        using var client = new HttpClient();
        return await client.GetStringAsync("https://api.example.com/weather");
    }
}

// After
public sealed class WeatherService(HttpClient client, ILogger<WeatherService> logger)
{
    public async Task<string> GetAsync(CancellationToken cancellationToken)
    {
        logger.LogInformation("Fetching weather data");
        return await client.GetStringAsync("weather", cancellationToken);
    }
}

Uses dependency injection, logging, and cancellation instead of constructing infrastructure per call.

Common Pitfalls

• Constructing infrastructure inside business code: It defeats dependency injection and makes testing or observability much harder.
• Treating async methods like fire-and-forget work: Exceptions and cancellations disappear unless the call chain is designed for them.
• Burying configuration in magic strings: Runtime behavior drifts across environments when options are not strongly typed.

<!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

• GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
• Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
• Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
• Gemini CLI: this repository generates a project command named /skills:dotnet-best-practices from this skill. Rebuild commands with python scripts/export-gemini-skill.py dotnet-best-practices and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the .NET/C# Best Practices skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
• Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

<!-- MCP:END -->

Related Skills

• csharp-xunit: Use it when the workflow also needs modern xUnit test design in C#.
• code-quality: Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.
• development-workflow: Use it when the workflow also needs planning, quality gates, and delivery tracking.
• microsoft-development: Use it when the workflow also needs microsoft development guidance.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.
• Added an "Optimized for ..." note at the top so the guidance is anchored to current platform versions.

All notable changes to the dotnet-best-practices skill will be documented in this file.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.
• Added an explicit before-and-after example and a Common Pitfalls section for modern .NET implementation guidance.

[2026-04-04] - Initial Import and Portability Upgrade

Added

• Imported this skill from https://github.com/github/awesome-copilot at skills/dotnet-best-practices.
• Added cross-client portability guidance for GitHub Copilot, Claude Code, Codex, and Gemini CLI.
• Added the repo-standard MCP or no-MCP fallback guidance for this skill.

Changed

• Rewrote the description and scope wording so the guidance applies cleanly across clients and no longer depends on a host-specific ${selection} placeholder.

Tested

• Validated SKILL.md frontmatter and Gemini command export readiness with python scripts/validate-skills.py.