dotnet-guidelines

dotnet coding guidelines and best practices. MUST follow these rules. Use when reviewing or writing .NET code or tasks.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill serves as an automated expert for .NET development, enforcing strict coding guidelines and modern best practices. It ensures high-quality C# code by mandating the use of primary constructors, record types, and structured logging while preventing common architectural anti-patterns. By integrating these rules into the development workflow, it helps maintain consistency, improves performance through optimized collection initializers, and ensures robust asynchronous programming with mandatory cancellation tokens.

Use Cases

  • 1. Automated Code Auditing: Use this skill to review Pull Requests or existing files to identify violations of .NET standards, such as improper dependency injection or the use of forbidden wrapper methods.
  • 2. Modernizing Legacy C# Code: Guide the refactoring of older .NET projects by converting traditional classes to sealed records and updating collection syntax to modern expressions ([.. list]).
  • 3. Standardizing Service Architecture: Ensure all backend services correctly implement ITransientService/IScopedService interfaces and utilize IRestClient instead of direct HttpClient instantiation.
  • 4. Enhancing Log Quality and Traceability: Automatically verify that all server-side logs use structured logging without string interpolation and include the required trailing punctuation for consistency.
namedotnet-guidelines

IMPORTANT Server Guidelines

  • ALWAYS Use Primary Constructors for classes.
  • ALWAYS Prefer record types for immutable data structures.
  • NEVER mix multiple classes or DTOs in a single file, even if they are small. Filename ALWAYS matches the class or DTO name, for example UserDto.cs for a UserDto class.
  • Private fields should NOT be prefixed with _ (e.g., repository not _repository).
  • Add (.) to the end of all server-side log messages.
  • Use string? over string for nullable strings.
  • Use var for local variables when type is obvious.
  • Don't use Regions in code files.
  • Use Collection initializers for collections: instead of new List<string>(), use new() { "item1", "item2" }, and instead of list.ToArray() use [.. list].
  • Use Anonymous function static: instead of list.Select(x => new Dto(x.SameProperty)), use list.Select(static x => new Dto(x.SameProperty)).
  • ALWAYS use sealed accessor for classes or records if not intended for inheritance.
  • ALWAYS use internal accessor for internal classes or records.
  • NEVER inject or create HttpClient and IHttpClientFactory, instead use the IRestClient interface.
  • NEVER register services directly in IServiceCollection. Instead, use the ITransientService, IScopedService, or ISingletonService interfaces to register services with the appropriate lifetimes.
  • ALWAYS use ILogger with Structured logging to log, no string interpolation and no other logging methods.
  • ALWAYS use cancellation tokens for asynchronous methods.
  • ALWAYS use IMemoryCore for time-based in-memory caching, NEVER use IMemoryCache.
  • ALWAYS use Data Transfer Objects (DTO) for API communication, validated with attributes.
  • ALWAYS use x as a parameter name in lambdas and anonymous functions.
  • If any backend changes are made, run dotnet build in the root and ensure no build errors for the entire solution.

Code Organization Principles

Avoid Unnecessary Wrapper Methods

Rule: Do NOT create wrapper methods for specific cases that simply call another method with fixed parameters. Call the base method directly instead.

Example - DON'T:

// ❌ Don't create this wrapper method for a single use case:
public async Task<int> CreateAgentHistoryClearedMessageAsync(int sessionId)
{
    var request = new CreateMessageRequest(
        Type: MessageType.System,
        Content: "Agent history has been cleared",
        Status: MessageStatus.Done
    );
    return await CreateMessageAsync(sessionId, request);
}

Example - DO:

// ✅ Instead, call CreateMessageAsync directly where needed:
await messageService.CreateMessageAsync(
    sessionId,
    new CreateMessageRequest(
        MessageType.System,
        "Agent history has been cleared",
        MessageStatus.Done
    )
);

When to create a helper method:

  • When there's complex logic beyond just parameter mapping
  • When the same combination is used in multiple places (3+ times)
  • When the method provides meaningful abstraction or validation