Dotnet Coding Standards

.NET Coding Standards

Comprehensive coding standards for .NET projects following Clean Architecture principles.

Customization

This skill uses placeholders for company-specific values. Replace these throughout:

🚀 New Developer Quick Start

1. Clone the repo and run dotnet restore
2. Read the project's README.md (every project has one)
3. Check you have .NET 10 SDK installed
4. Run dotnet build — must complete with zero warnings
5. Run dotnet test — must have 80%+ coverage
6. Before committing: Run the PR Review Checklist

First task? Start with the New Solution Checklist.

Quick Reference

❌ Critical Rules (Non-Negotiable)

Never Use Pragma Suppressions

// ❌ FORBIDDEN
#pragma warning disable SA1600
public class MyClass { }
#pragma warning restore SA1600

// ✅ CORRECT - Fix the actual issue
/// <summary>
/// Provides functionality for processing data.
/// </summary>
public class MyClass { }

Never Skip Unit Tests for Functional Classes

Every class with business logic MUST have corresponding unit tests with 80%+ coverage.

Never Use Microsoft.Extensions.Logging Config in Hosts

Serilog configuration takes precedence. See Serilog Standards.

📁 Detailed Documentation

By Project Type

Standards & Patterns

Templates (Copy-Paste Ready)

Checklists

IDE Snippets

Common Mistakes to Avoid

Logging

Async/Await

Testing

StyleCop

Decision Flowcharts

Should I Use ConfigureAwait(false)?

Is this code in a Controller, Razor Page, or Blazor component?
├── YES → Do NOT use ConfigureAwait(false)
└── NO → Does this code access HttpContext, User, or UI elements?
    ├── YES → Do NOT use ConfigureAwait(false)
    └── NO → USE ConfigureAwait(false) ✓

What Log Level Should I Use?

Is this an unhandled exception or app crash?
├── YES → LogCritical (Fatal)
└── NO → Did an operation fail?
    ├── YES → LogError
    └── NO → Is something unexpected but handled?
        ├── YES → LogWarning
        └── NO → Is this a significant business event?
            ├── YES → LogInformation
            └── NO → Is this useful for debugging?
                ├── YES → LogDebug
                └── NO → LogTrace (or don't log)

Do I Need a Unit Test for This Class?

Does this class contain business logic or behavior?
├── YES → Unit test REQUIRED ✓
└── NO → Is this a DTO, model, or configuration class?
    ├── YES → Unit test optional (data-only)
    └── NO → Is this auto-generated code?
        ├── YES → Unit test not needed
        └── NO → Is this startup/Program.cs?
            ├── YES → Integration test instead
            └── NO → Probably needs a unit test ✓

Package Versions

Quick Commands

# Build with zero warnings
dotnet build --warnaserrors

# Run all tests with coverage
dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings

# Generate HTML coverage report
reportgenerator -reports:./TestResults/**/coverage.cobertura.xml -targetdir:./coverage -reporttypes:Html

# Find StyleCop violations
dotnet build 2>&1 | grep -E "SA[0-9]{4}"

# Find pragma suppressions (should return nothing)
grep -r "#pragma warning disable" --include="*.cs" src/

# Find missing ConfigureAwait in Infrastructure
grep -r "await.*;" --include="*.cs" src/Infrastructure/ | grep -v "ConfigureAwait(false)"

# Find Microsoft logging config (should not exist in hosts)
grep -r '"Logging"' --include="appsettings*.json" src/

Exception Process

If you genuinely cannot follow a standard (e.g., third-party library conflict):

1. Document the exception in code: // STANDARDS-EXCEPTION: [reason]
2. Create a GitHub issue linking to the code
3. Get tech lead approval
4. Add to project's docs/EXCEPTIONS.md file

Never use pragma suppressions as an escape hatch.

IDE Setup

Visual Studio 2022

1. Tools → Options → Text Editor → C# → Code Style
2. Import .editorconfig from solution root
3. Enable "Run code analysis on build"

JetBrains Rider

1. Settings → Editor → Code Style → C#
2. Import from .editorconfig
3. Enable StyleCop inspections in Inspections settings

VS Code

1. Install C# Dev Kit extension
2. Install "EditorConfig for VS Code" extension
3. Add to settings.json: "omnisharp.enableEditorConfigSupport": true

Glossary

Changelog

• 2.4.0 (2026-02-20): Audit & update — added globs/triggers to frontmatter, updated C# 12→13 references, fixed StyleCop version notes, added Seq apiKey guidance
• 2.3.0 (2026-01-11): Added Nullability & Annotations standards (JetBrains.Annotations)
• 2.2.0 (2026-01-11): Added Clean Architecture, CQRS/MediatR, Domain Design, Error Handling standards
• 2.1.0 (2026-01-10): Added Serilog, Sentry, ConfigureAwait standards; multi-file structure
• 2.0.0 (2025-12-01): Extended to multiple project types (Console, Worker, Blazor)
• 1.0.0 (2025-10-15): Initial Web API standards