Csharp coding

C# / .NET Best Practices

Comprehensive guide for writing high-quality, idiomatic C# and .NET code. Contains 186 rules across 15 categories, prioritized by impact. Project constraints override generic defaults: preserve the declared LangVersion, TargetFramework, and nullable/analyzer settings unless the user explicitly requests a migration or upgrade.

When to Apply

Reference these guidelines when:

• Writing new C# classes, records, methods, or minimal API endpoints
• Implementing error handling or async/await code
• Designing public APIs for libraries or NuGet packages
• Reviewing code for nullability, disposal, or concurrency issues
• Optimizing memory usage or reducing allocations
• Configuring dependency injection lifetimes and registrations
• Writing or reviewing unit/integration tests
• Refactoring existing C#/.NET code
• Setting up analyzers, .editorconfig, or CI formatting checks

Modern C#/.NET (C# 12/13, .NET 8/9)

For an existing project, preserve its LangVersion and TargetFramework unless a migration is explicitly in scope. For new projects, target the latest LTS/STS release actually supported by your deployment environment. Key modern idioms to prefer when the project's language version supports them:

• Primary constructors (C# 12+). Reduce constructor boilerplate for simple field capture and DI - see api-primary-constructor.
• Collection expressions ([1, 2, 3], C# 12+). One consistent literal syntax across arrays, List<T>, Span<T>, and custom collection-builder types, including the spread operator (..) - see api-collection-expressions.
• required members (C# 11+). Compiler-enforced mandatory properties without a long constructor - see api-required-members.
• record/record struct. Value-based equality, with expressions, and deconstruction generated for you - see api-record-value-data and immut-record-struct-small-value.
• Nullable reference types (<Nullable>enable</Nullable>, C# 8+, foundational for modern code). Turns a huge class of NullReferenceExceptions into compile-time warnings - see type-nullable-reference-types.
• Pattern matching enhancements: list patterns, property patterns, logical (and/or/not) patterns - see type-pattern-matching-is.
• ref structs and Span<T>/Memory<T>. Stack-only, allocation-free data access for hot paths - see mem-span-zero-alloc and mem-ref-struct-stack.
• Source generators over reflection for serialization, logging, and mapping - see perf-source-generators-over-reflection.
• Frozen collections (FrozenDictionary/FrozenSet, .NET 8+) for build-once/read-many lookups - see immut-frozen-collections.
• Generic math (INumber<T>, .NET 7+) for numeric-agnostic algorithms - see type-generic-math.
• Keyed DI services (.NET 8+) for multiple implementations of one interface - see di-keyed-services.

For the authoritative, complete list of language and runtime changes, consult the official What's New in C# and .NET release notes. Everything below applies across supported versions; prefer the modern forms above where the project's LangVersion/TargetFramework allow them.

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Memory & Resource Management	CRITICAL	mem-	14
2	Error Handling	CRITICAL	err-	13
3	Async/Await & Concurrency	CRITICAL	async-	17
4	API & Type Design	HIGH	api-	15
5	Records & Immutability	HIGH	immut-	10
6	LINQ & Collections	HIGH	linq-	12
7	Naming Conventions	MEDIUM	name-	14
8	Type Safety & Nullability	MEDIUM/HIGH	type-	12
9	Dependency Injection & Configuration	MEDIUM	di-	10
10	Testing	MEDIUM	test-	13
11	Documentation	MEDIUM	doc-	9
12	Performance Patterns	MEDIUM	perf-	12
13	Project Structure	LOW	proj-	10
14	Analyzers & Linting	LOW	lint-	10
15	Anti-patterns	REFERENCE	anti-	15

---

Quick Reference

1. Memory & Resource Management (CRITICAL)

• mem-using-declaration - Use using declarations for deterministic disposal
• mem-await-using-async - Use await using for IAsyncDisposable
• mem-dispose-pattern - Implement the full IDisposable dispose pattern
• mem-finalizer-rare - Only add a finalizer when holding raw unmanaged handles
• mem-span-zero-alloc - Use Span<T>/ReadOnlySpan<T> for zero-allocation slicing
• mem-memory-async-boundary - Use Memory<T> across async boundaries
• mem-arraypool-rent - Rent from ArrayPool<T> for short-lived large buffers
• mem-readonly-struct - Mark immutable structs readonly struct
• mem-ref-struct-stack - Use ref struct for stack-only types
• mem-struct-vs-class - Choose struct vs class by size/mutability/identity
• mem-avoid-boxing - Avoid boxing value types in hot paths
• mem-stackalloc-small - Use stackalloc for small, bounded buffers
• mem-object-pooling - Pool expensive objects with ObjectPool<T>
• mem-large-object-heap - Understand LOH allocations for large arrays/objects

2. Error Handling (CRITICAL)

• err-exceptions-exceptional - Reserve exceptions for exceptional conditions
• err-custom-hierarchy - Design a custom exception hierarchy
• err-argumentnull-throwifnull - Use ArgumentNullException.ThrowIfNull
• err-no-catch-exception - Don't catch the base Exception broadly
• err-exception-filters-when - Use exception filters (when)
• err-preserve-stack-trace - Use throw; not throw ex;
• err-finally-cleanup - Use finally for guaranteed cleanup
• err-wrap-with-innerexception - Wrap with innerException preserved
• err-async-exception-propagation - Understand async exception flow
• err-aggregateexception-flatten - Flatten AggregateException
• err-result-pattern-domain - Use Result<T> for expected failures
• err-exception-message-quality - Write actionable exception messages
• err-dont-swallow - Never swallow exceptions silently

3. Async/Await & Concurrency (CRITICAL)

• async-configureawait-false-lib - Use ConfigureAwait(false) in libraries
• async-no-async-void - Avoid async void except event handlers
• async-task-vs-valuetask - Choose ValueTask<T> only for proven hot paths
• async-cancellationtoken-propagate - Propagate CancellationToken
• async-no-sync-over-async - Never block on async with .Result/.Wait()
• async-iasyncenumerable-streaming - Use IAsyncEnumerable<T> for streaming
• async-semaphoreslim-lock - Use SemaphoreSlim for async-safe locking
• async-whenall-parallel - Use Task.WhenAll for parallel operations
• async-whenany-timeout - Use Task.WhenAny for timeouts/racing
• async-taskcompletionsource-bridge - Bridge callbacks with TaskCompletionSource<T>
• async-name-suffix - Suffix async methods with Async
• async-return-task-directly - Return the inner Task directly when possible
• async-avoid-task-run-server - Avoid Task.Run for server request paths
• async-valuetask-single-await - Await a ValueTask exactly once
• async-async-lambda-void - Avoid async lambdas assigned to Action
• async-channels-producer-consumer - Use System.Threading.Channels
• async-lock-not-monitor-async - Never hold lock/Monitor across await

4. API & Type Design (HIGH)

• api-primary-constructor - Use primary constructors to reduce boilerplate
• api-init-only-properties - Use init-only properties
• api-required-members - Use required members instead of throwing constructors
• api-record-value-data - Model immutable value data with record
• api-sealed-by-default - Seal classes by default
• api-interface-segregation - Keep interfaces small and role-based
• api-extension-methods - Use extension methods for types you don't own
• api-builder-fluent - Use a fluent builder for complex construction
• api-collection-expressions - Use collection expressions ([1, 2, 3])
• api-expose-interfaces-not-impls - Return abstractions, not concrete collections
• api-optional-parameters-vs-overloads - Prefer overloads over long optional-parameter lists
• api-generic-constraints - Constrain generics with where clauses
• api-static-factory-methods - Use static factory methods for validated construction
• api-out-var-pattern - Use out var/deconstruction for multiple returns
• api-with-expression-nondestructive - Use with for non-destructive mutation

5. Records & Immutability (HIGH)

• immut-record-equality - Understand records give value-based equality
• immut-record-struct-small-value - Use record struct for small values
• immut-readonly-fields - Mark fields readonly unless mutation is required
• immut-immutable-collections - Use System.Collections.Immutable
• immut-avoid-mutable-public-fields - Never expose mutable public fields
• immut-with-nondestructive-mutation - Use with instead of manual copy constructors
• immut-defensive-copy-collections - Defensively copy internal collections
• immut-frozen-collections - Use FrozenDictionary/FrozenSet for read-heavy lookups
• immut-positional-record-deconstruct - Positional records for deconstruction
• immut-value-object-record - Model value objects as records, entities as classes

6. LINQ & Collections (HIGH)

• linq-deferred-execution-aware - Understand deferred execution
• linq-avoid-multiple-enumeration - Avoid enumerating a query multiple times
• linq-avoid-hot-path - Avoid LINQ allocations in hot paths
• linq-any-vs-count - Use .Any() not .Count() > 0
• linq-firstordefault-vs-first - Choose FirstOrDefault vs First deliberately
• linq-select-then-where-order - Filter before projecting
• linq-avoid-linq-in-loop-alloc - Hoist invariant LINQ queries out of loops
• linq-collection-choice - Choose collections by access pattern
• linq-span-linq-alternative - Replace LINQ with loops only when profiled
• linq-groupby-lookup - Use GroupBy/ToLookup over manual grouping
• linq-orderby-stable - Rely on OrderBy's stability; chain ThenBy
• linq-iqueryable-vs-ienumerable - Know when work is pushed to the database

7. Naming Conventions (MEDIUM)

• name-pascalcase-public - PascalCase for types, methods, properties
• name-camelcase-locals - camelCase for locals and parameters
• name-underscore-private-fields - Prefix private fields with _camelCase
• name-interface-i-prefix - Prefix interfaces with I
• name-async-suffix - Suffix async methods with Async
• name-generic-type-param-t - Use T/TKey/TValue conventions
• name-boolean-is-has-can - Use Is/Has/Can for booleans
• name-constants-pascalcase - PascalCase for constants, not SCREAMING_CASE
• name-namespace-matches-folder - Match namespace to folder structure
• name-avoid-hungarian - Avoid Hungarian notation
• name-event-naming - Name events with a verb phrase; handlers with On
• name-avoid-abbreviations - Avoid unclear abbreviations
• name-file-matches-type - Name a file after its single public type
• name-plural-collections - Name collections with plural nouns

8. Type Safety & Nullability (MEDIUM/HIGH)

• type-nullable-reference-types - Enable nullable reference types
• type-pattern-matching-is - Use pattern matching over type-casting chains
• type-switch-expression-exhaustive - Exhaustive switch expressions
• type-avoid-dynamic - Avoid dynamic
• type-enum-design - Explicit enum values; [Flags] only when combinable
• type-nullable-value-types - Use T? for optional value types
• type-notnullwhen-attributes - Annotate your own nullable-flow APIs
• type-record-for-equality - Use records instead of manual equality
• type-generic-math - Use generic math for numeric-agnostic algorithms
• type-avoid-object-typed - Avoid object-typed APIs
• type-strongly-typed-ids - Wrap primitive IDs in strongly-typed structs
• type-null-forgiving-sparingly - Use ! sparingly, with justification

9. Dependency Injection & Configuration (MEDIUM)

• di-constructor-injection - Prefer constructor injection
• di-lifetime-choice - Choose Singleton/Scoped/Transient deliberately
• di-avoid-captive-dependency - Avoid captive dependencies
• di-options-pattern - Use the Options pattern for configuration
• di-avoid-service-locator - Avoid the service-locator anti-pattern
• di-register-interfaces - Register interfaces, not concrete implementations
• di-validate-on-start - Validate the DI graph eagerly at startup
• di-httpclientfactory - Use IHttpClientFactory
• di-keyed-services - Use keyed DI services for multiple implementations
• di-avoid-property-injection - Avoid property/method injection

10. Testing (MEDIUM)

• test-xunit-theory-inlinedata - Use [Theory]/[InlineData]
• test-arrange-act-assert - Structure tests as Arrange/Act/Assert
• test-fluentassertions - Use FluentAssertions for readable assertions
• test-mock-interfaces-not-concretes - Mock interfaces, not concretes
• test-nsubstitute-moq - Use NSubstitute/Moq for isolation
• test-descriptive-test-names - Name tests descriptively
• test-webapplicationfactory-integration - Use WebApplicationFactory<T>
• test-avoid-shared-mutable-state - Avoid shared mutable state across tests
• test-collection-fixture - Use fixtures for expensive shared setup
• test-avoid-thread-sleep - Never use Thread.Sleep to synchronize tests
• test-testcontainers-integration - Use Testcontainers for real dependencies
• test-one-assert-concept - Test one logical concept per test method
• test-avoid-testing-private - Test through the public API

11. Documentation (MEDIUM)

• doc-xml-summary-public - Document all public members with <summary>
• doc-param-returns-tags - Document parameters and return values
• doc-exception-tags - Document exceptions with <exception>
• doc-example-code - Include <example>/<code> for non-obvious APIs
• doc-generate-xml-docfile - Enable GenerateDocumentationFile
• doc-see-cref-links - Cross-reference with <see cref="..."/>
• doc-remarks-for-nuance - Use <remarks> for nuance/caveats
• doc-inheritdoc - Use <inheritdoc/> to avoid duplication
• doc-readme-nuget-metadata - Fill NuGet package metadata

12. Performance Patterns (MEDIUM)

• perf-stringbuilder-concat - Use StringBuilder for loop concatenation
• perf-string-interpolation-vs-concat - Know how interpolation compiles
• perf-span-parsing - Parse with Span<T> to avoid substring allocations
• perf-source-generators-over-reflection - Source generators over reflection
• perf-record-struct-hot-data - record struct for small, hot data
• perf-avoid-linq-hot-path - Avoid LINQ in proven hot paths
• perf-cache-regex - Compile/cache Regex, or use [GeneratedRegex]
• perf-frozen-lookup-startup - Frozen collections for startup-built lookups
• perf-value-task-hot-path - Return ValueTask from hot async methods
• perf-string-comparison-ordinal - Use StringComparison.Ordinal
• perf-avoid-unnecessary-async-state-machine - Avoid needless async state machines
• perf-json-source-gen - Use System.Text.Json source generation

13. Project Structure (LOW)

• proj-directory-build-props - Centralize settings in Directory.Build.props
• proj-central-package-management - Central package management
• proj-solution-folder-layout - Organize solution folders by layer
• proj-internal-visibility - Default to internal visibility
• proj-internalsvisibleto-tests - Expose internals to tests via InternalsVisibleTo
• proj-nullable-enable-solution-wide - Enable nullable solution-wide
• proj-namespace-folder-structure - Match namespaces to folders
• proj-separate-test-projects - Keep test projects separate
• proj-file-scoped-namespaces - Use file-scoped namespaces
• proj-implicit-usings - Use ImplicitUsings and GlobalUsings.cs

14. Analyzers & Linting (LOW)

• lint-treat-warnings-as-errors - Enable TreatWarningsAsErrors in CI
• lint-nullable-warnings-errors - Promote nullable warnings to errors
• lint-editorconfig-enforce - Enforce style with .editorconfig
• lint-roslyn-analyzers - Enable Microsoft.CodeAnalysis.NetAnalyzers
• lint-stylecop-analyzers - Use StyleCop.Analyzers
• lint-code-analysis-enforce-latest - Set AnalysisLevel to latest
• lint-format-verify-ci - Run dotnet format --verify-no-changes in CI
• lint-suppress-with-justification - Justify every suppression
• lint-banned-api-analyzer - Ban dangerous APIs at compile time
• lint-nuget-audit - Enable NuGetAudit for vulnerable packages

15. Anti-patterns (REFERENCE)

• anti-async-void - Don't use async void outside event handlers
• anti-sync-over-async - Don't block on async with .Result/.Wait()
• anti-catch-exception-broad - Don't catch Exception broadly
• anti-empty-catch-block - Don't leave empty catch blocks
• anti-god-class - Don't build God classes
• anti-magic-strings-numbers - Don't scatter magic strings/numbers
• anti-mutable-public-fields - Don't expose mutable public fields
• anti-linq-multiple-enumeration - Don't enumerate a query multiple times
• anti-over-mocking - Don't over-mock
• anti-primitive-obsession - Don't pass primitive swarms instead of types
• anti-throw-ex-loses-stack - Don't use throw ex;
• anti-datetime-now-untestable - Don't call DateTime.Now directly
• anti-singleton-static-state - Don't hide dependencies behind statics
• anti-boxing-generic-collections - Don't box into non-generic collections
• anti-region-abuse - Don't use #region to hide poor organization

---

Recommended .csproj / Directory.Build.props Settings

<!-- Directory.Build.props (repository root) -->
<Project>
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest</AnalysisLevel>
    <AnalysisMode>Recommended</AnalysisMode>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NuGetAudit>true</NuGetAudit>
    <NuGetAuditMode>all</NuGetAuditMode>
  </PropertyGroup>
</Project>

<!-- Directory.Packages.props (repository root) -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
</Project>

# .editorconfig
root = true

[*.cs]
indent_style = space
indent_size = 4
csharp_style_namespace_declarations = file_scoped:warning
dotnet_style_namespace_match_folder = true:warning
dotnet_style_require_accessibility_modifiers = always:warning
dotnet_diagnostic.CA2007.severity = warning  # ConfigureAwait(false) in libraries

---

How to Use

This skill provides rule identifiers for quick reference. When generating or reviewing C#/.NET code:

1. Check relevant category based on task type
2. Apply rules with matching prefix
3. Prioritize CRITICAL > HIGH > MEDIUM > LOW
4. Read rule files in rules/ for detailed examples

Rule Application by Task

Task	Primary Categories
New class/method	api-, err-, name-
New record/DTO	immut-, api-, type-
Async code	async-, mem-
Error handling	err-, api-
Memory optimization	mem-, perf-
LINQ/collections	linq-, perf-
Dependency injection	di-
Writing tests	test-
Performance tuning	perf-, mem-, linq-
Code review	anti-, lint-

---

Related Skills

• design-patterns - choosing and implementing GoF and idiomatic patterns; apply alongside this skill's API and naming rules for pattern-heavy C# design.
• security-review - security-focused audit checklists; apply alongside this skill's error-handling and interop rules when reviewing C# code for vulnerabilities.

Sources

This skill synthesizes best practices from:

• Microsoft C# Coding Conventions
• .NET Framework Design Guidelines (Cwalina & Abrams)
• .NET Naming Guidelines
• What's New in C# (C# 12/13 language reference)
• dotnet/roslyn-analyzers and dotnet/runtime source and analyzer documentation
• Production codebases: dotnet/runtime, dotnet/aspnetcore, dotnet/efcore
• Community conventions and tooling (StyleCop.Analyzers, xUnit, FluentAssertions, Testcontainers) (2024-2025)