C# Style Guide

C# 14 Features

Projects targeting .NET 10 SHOULD adopt C# 14 features where they improve clarity and reduce boilerplate.

Why a containing static class and an explicit type parameter

An extension block MUST be declared inside a top-level, non-generic static class, and MUST declare its own type parameters. A bare extension(...) block is a compile error: the compiler reports CS9283 outside such a class, and CS0080 plus CS0246 when the block uses T without declaring extension<T>. The receiver parameter does not introduce type parameters.

Field Keyword

The field keyword provides direct access to auto-property backing fields. The backing field has the property’s own type, so field ??= ... compiles only when that type is nullable, and a field-backed non-nullable property MUST be required or carry an initializer or the compiler reports CS9264.

Do:

using System;
using System.ComponentModel;
using System.Runtime.CompilerServices;

public class User : INotifyPropertyChanged
{
    // Validate on set while keeping auto-property syntax
    public required string Email
    {
        get;
        set => field = value?.ToLowerInvariant()
            ?? throw new ArgumentNullException(nameof(value));
    }

    // Notify on change
    public required string Name
    {
        get;
        set
        {
            if (field != value)
            {
                field = value;
                OnPropertyChanged();
            }
        }
    }

    // DateTime has no null state, so seed the backing field from an
    // initializer; `field ??= DateTime.UtcNow` does not compile
    public DateTime CreatedAt { get; init; } = DateTime.UtcNow;

    // Lazy initialization needs a nullable property so `??=` has a null to test
    public string? Slug
    {
        get => field ??= Name.ToLowerInvariant().Replace(' ', '-');
    }

    public event PropertyChangedEventHandler? PropertyChanged;

    private void OnPropertyChanged([CallerMemberName] string? name = null) =>
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
}

Don’t:

using System;

// Don't trade a mutable property for an immutable one without saying so:
// the null check below runs on every assignment, at run time
public class MutableOrder
{
    public required string Id
    {
        get;
        set => field = value ?? throw new ArgumentNullException(nameof(value));
    }
}

// Better when the value must not change after construction: the compiler
// enforces it at every call site instead
public class ImmutableOrder
{
    public required string Id { get; init; }
}

// A member already named `field` is shadowed inside an accessor (CS9258):
// write `this.field` or `@field` to reach it
public class Legacy
{
    private readonly string field = "backing";

    public string Value => this.field;
}

Why required rather than an unchecked setter

required string Id { get; init; } and a mutable property with a null-rejecting setter are not interchangeable. The first is checked by the compiler at every object initializer and cannot change afterwards; the second throws at run time and stays writable. Projects MUST choose init only where the value is genuinely set once.

Projects that already declare a member named field MUST migrate it or qualify every accessor reference. In language version 14.0 the compiler reports CS9258 and binds field to a synthesized backing field, so this.field or @field is required to reach the existing member.

Simple Lambda Parameters with Modifiers

Lambda parameters can carry modifiers without explicit types, provided the target delegate declares the same modifiers. A params parameter is the exception: it MUST be explicitly typed.

Do:

using System;
using System.Linq;

public delegate int RefComparer(ref int x, ref int y);

public delegate int SpanLength(scoped ReadOnlySpan<char> text);

public delegate int Aggregator(params int[] values);

public static class LambdaSamples
{
    public static void Run()
    {
        // ref, out and in modifiers need a delegate that declares them
        RefComparer compare = (ref x, ref y) => x.CompareTo(y);
        int left = 3, right = 7;
        Console.WriteLine(compare(ref left, ref right));

        // Span<T>.Sort takes Comparison<T>, whose parameters are by value
        Span<int> numbers = stackalloc int[] { 3, 1, 2 };
        numbers.Sort((x, y) => x.CompareTo(y));

        // scoped modifier
        SpanLength trimmedLength = (scoped text) => text.Trim().Length;
        Console.WriteLine(trimmedLength("  hello  "));

        // params modifier: the parameter type must be written out
        Aggregator sum = (params int[] values) => values.Sum();
        Console.WriteLine(sum(1, 2, 3));
    }
}

Linting: Roslynator + SonarAnalyzer

C# projects MUST use Roslynator¹ and SonarAnalyzer³ for static analysis.

Installation

You MUST add to your project or Directory.Build.props:

<ItemGroup>
  <PackageReference Include="Roslynator.Analyzers" Version="5.0.0">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
  </PackageReference>
  <PackageReference Include="SonarAnalyzer.CSharp" Version="10.33.0.1635">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
  </PackageReference>
</ItemGroup>

Both versions MUST be written exactly as published. SonarAnalyzer.CSharp uses four-part versions, so Version="10.33.0" resolves to the nearest higher build with NU1603, which TreatWarningsAsErrors turns into a fatal restore error.

Migrating to Roslynator 5.0.0

Roslynator 5.0.0 (released 2026-08-21) is a breaking release. Projects upgrading from 4.x MUST:

• Rename the legacy .editorconfig keys roslynator.max_line_length and roslynator.prefix_field_identifier_with_underscore to roslynator_max_line_length and roslynator_prefix_field_identifier_with_underscore, and replace roslynator_suppress_unity_script_methods with roslynator_unity_code_analysis.enabled
• Replace the analyzers removed in 5.0.0 with their successors, for example RCS0014 with RCS0061, RCS1035 with RCS1260, and RCS1237 with RCS1254
• Reference Microsoft.CodeAnalysis.CSharp.Workspaces explicitly in test projects that used the Roslynator testing packages, which now floor their Roslyn dependency at 3.8.0 instead of forcing 4.14.0
• Install the Roslynator 2026 extension for Visual Studio 2026, or stay on the last 4.x VSIX; the 5.0.0 extensions no longer bundle analyzers

Projects MUST baseline the diagnostics both upgrades introduce before turning warnings into errors, otherwise the first build after the upgrade fails on pre-existing code.

Solution-Wide (Directory.Build.props)

Projects SHOULD configure analyzers solution-wide using Directory.Build.props:

<Project>
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <EnableNETAnalyzers>true</EnableNETAnalyzers>
    <AnalysisLevel>latest-all</AnalysisLevel>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Roslynator.Analyzers" Version="5.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
    <PackageReference Include="SonarAnalyzer.CSharp" Version="10.33.0.1635">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

Formatting: dotnet format

C# projects MUST use dotnet format² for code formatting.

Code Coverage: coverlet

C# projects MUST use coverlet⁴ for code coverage measurement.

Why the glob and the local tool

The VSTest collector writes coverage.cobertura.xml into a freshly named GUID directory under TestResults, never at the repository root, so -reports:coverage.cobertura.xml fails with “No report files specified”. A recursive glob matches whichever directory the run produced. Pinning ReportGenerator in a tool manifest MUST be preferred over dotnet tool install -g, which gives CI an unpinned floating version.

Configuration

The settings below belong in coverlet.runsettings. The XML declaration MUST be the first node in the file, so the filename cannot be written as a leading comment; dotnet test otherwise rejects the file with “Unexpected XML declaration”.

<?xml version="1.0" encoding="utf-8" ?>
<RunSettings>
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="XPlat Code Coverage">
        <Configuration>
          <Format>cobertura</Format>
          <Exclude>[*]*.Migrations.*</Exclude>
          <ExcludeByAttribute>GeneratedCodeAttribute</ExcludeByAttribute>
        </Configuration>
      </DataCollector>
    </DataCollectors>
  </DataCollectionRunSettings>
</RunSettings>

Dependencies & Package Management

C# projects MUST use NuGet⁸ for package management and SHOULD enable lock files in CI environments.

# Add package
dotnet add package Newtonsoft.Json

# Enable lock file
dotnet restore --use-lock-file

# Update and lock
dotnet restore --force-evaluate

packages.lock.json

Projects SHOULD enable lock files and MUST use locked mode in CI:

<!-- MyProject.csproj -->
<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode Condition="'$(CI)' == 'true'">true</RestoreLockedMode>
</PropertyGroup>

Vulnerability Scanning

Projects MUST check for vulnerable packages regularly:

# Check for vulnerable packages
dotnet list package --vulnerable

# Include transitive
dotnet list package --vulnerable --include-transitive

Dependabot Config

Projects SHOULD configure Dependabot⁹ for automated dependency updates:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5

E2E & Acceptance Testing

Web applications SHOULD use Playwright¹⁰ for end-to-end testing. BDD projects MAY use SpecFlow¹¹.

Why the integration package

IPlaywright does not implement IAsyncDisposable, so await using var playwright = await Playwright.CreateAsync() fails with CS8417, and Expect is a member of the runner base class rather than a free function, so calling it without that base class fails with CS0103. Projects using xUnit MUST reference Microsoft.Playwright.Xunit.v3 for xUnit v3 or Microsoft.Playwright.Xunit for xUnit v2; NUnit attributes such as [Test] MUST NOT be mixed into an xUnit suite.

WebApplicationFactory

ASP.NET Core applications SHOULD use WebApplicationFactory¹² for integration testing:

public class ApiTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    [Fact]
    public async Task GetUsers_ReturnsOk()
    {
        var client = factory.CreateClient();
        var response = await client.GetAsync("/api/users");

        response.StatusCode.Should().Be(HttpStatusCode.OK);
        var users = await response.Content.ReadFromJsonAsync<List<User>>();
        users.Should().NotBeEmpty();
    }
}

This example uses FluentAssertions¹³ for readable assertions.

Thread Safety Testing

Concurrent code MUST include thread safety tests:

[Fact]
public async Task ConcurrentAccess_IsSafe()
{
    var counter = new ThreadSafeCounter();
    var tasks = Enumerable.Range(0, 1000)
        .Select(_ => Task.Run(() => counter.Increment()));

    await Task.WhenAll(tasks);

    counter.Value.Should().Be(1000);
}

// Implementation
public class ThreadSafeCounter
{
    private int _value;

    public void Increment() => Interlocked.Increment(ref _value);
    public int Value => Interlocked.CompareExchange(ref _value, 0, 0);
}

Idempotence Testing

Operations that can be called multiple times SHOULD be tested for idempotence:

[Fact]
public async Task CreateUser_IsIdempotent()
{
    var request = new CreateUserRequest { Email = "test@example.com" };

    var result1 = await _service.CreateUserAsync(request);
    var result2 = await _service.CreateUserAsync(request);

    result1.Id.Should().Be(result2.Id);
    var users = await _repository.GetByEmailAsync(request.Email);
    users.Should().ContainSingle();
}

Reliability & Resilience Testing

Applications with external dependencies SHOULD implement and test resilience patterns using Polly¹⁴.

Chaos Engineering

Polly 8.7.0 ships chaos strategies in the box, so Simmy¹⁵ as a separate package is no longer required. Injection MUST be made deterministic in tests by setting InjectionRate to 1.0 rather than a probability:

using System.Diagnostics;
using Polly;
using Polly.Simmy;
using Polly.Simmy.Latency;

public class ChaosTests
{
    [Fact]
    public async Task Service_HandlesLatency()
    {
        var pipeline = new ResiliencePipelineBuilder()
            .AddChaosLatency(new ChaosLatencyStrategyOptions
            {
                InjectionRate = 1.0,
                Latency = TimeSpan.FromMilliseconds(500)
            })
            .Build();

        var stopwatch = Stopwatch.StartNew();
        await pipeline.ExecuteAsync(
            async ct => await _service.GetDataAsync(ct),
            CancellationToken.None);
        stopwatch.Stop();

        stopwatch.Elapsed.Should()
            .BeGreaterThanOrEqualTo(TimeSpan.FromMilliseconds(500));
        stopwatch.Elapsed.Should().BeLessThan(TimeSpan.FromSeconds(5));
    }
}

Timeout Testing

The executed delegate MUST accept and forward the cancellation token Polly supplies, otherwise an optimistic timeout has nothing to cancel:

[Fact]
public async Task Operation_RespectsTimeout()
{
    var timeout = Policy.TimeoutAsync(TimeSpan.FromMilliseconds(100));

    await timeout.Invoking(p => p.ExecuteAsync(
            async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct),
            CancellationToken.None))
        .Should().ThrowAsync<TimeoutRejectedException>();
}

Compatibility Testing

Libraries SHOULD test against multiple .NET versions using multi-targeting.

Why no conditional System.Text.Json reference

System.Text.Json ships in the shared framework for every net8.0 and later target, so referencing the package explicitly is redundant: NuGet reports NU1510 and asks for the reference to be removed. Pinning it to 8.0.0 also drags in two high-severity denial-of-service advisories, GHSA-hh2w-p6rv-4g7w and GHSA-8g4q-xg66-9fp4, which restore reports as NU1903 and TreatWarningsAsErrors turns into build failures. A target that genuinely needs the package, such as netstandard2.0, MUST pin a serviced version — 8.0.6 is the last 8.x, and 10.0.11 is the current stable release — and CI MUST fail on NU1903.

CI Matrix

Each matrix leg MUST check out the repository and build a single target framework, and the job MUST install every runtime the matrix exercises alongside an SDK new enough to evaluate net10.0:

jobs:
  test:
    strategy:
      matrix:
        framework: ['net8.0', 'net9.0', 'net10.0']
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
        with:
          dotnet-version: |
            8.0.x
            9.0.x
            10.0.x
      - run: dotnet test --framework ${{ matrix.framework }}

Internationalization Testing

Applications with international users MUST test localization and UTF-8 handling. Resource lookup reads CultureInfo.CurrentUICulture, not CultureInfo.CurrentCulture, so a localization test MUST set and restore both, and MUST run without parallelism because culture is ambient state:

[Collection("Sequential")]
public class GreetingTests
{
    [Theory]
    [InlineData("en-US", "Hello")]
    [InlineData("es-ES", "Hola")]
    [InlineData("ja-JP", "こんにちは")]
    public void Greeting_LocalizesToCulture(string culture, string expected)
    {
        var originalCulture = CultureInfo.CurrentCulture;
        var originalUICulture = CultureInfo.CurrentUICulture;
        try
        {
            var target = new CultureInfo(culture);
            CultureInfo.CurrentUICulture = target;  // resource lookup
            CultureInfo.CurrentCulture = target;    // formatting and parsing

            var greeting = _localizer["Greeting"];

            greeting.Value.Should().Be(expected);
        }
        finally
        {
            CultureInfo.CurrentCulture = originalCulture;
            CultureInfo.CurrentUICulture = originalUICulture;
        }
    }
}

Data Integrity Testing

Applications using databases MUST test migrations and transactions.

A/B Testing & Feature Flags

Applications implementing feature flags SHOULD use Microsoft.FeatureManagement¹⁷.

Testing Feature Filters

Tests MUST pin the filter inputs so the outcome is decided, not sampled:

[Fact]
public async Task FeatureFilter_AtZeroPercent_IsDisabled()
{
    var featureManager = CreatePercentageFeatureManager(0);

    var enabled = await featureManager.IsEnabledAsync("NewCheckout");

    enabled.Should().BeFalse();
}

[Fact]
public async Task FeatureFilter_AtHundredPercent_IsEnabled()
{
    var featureManager = CreatePercentageFeatureManager(100);

    var enabled = await featureManager.IsEnabledAsync("NewCheckout");

    enabled.Should().BeTrue();
}

private static IFeatureManager CreatePercentageFeatureManager(int percentage)
{
    var config = new ConfigurationBuilder()
        .AddInMemoryCollection(new Dictionary<string, string?>
        {
            ["FeatureManagement:NewCheckout:EnabledFor:0:Name"] = "Percentage",
            ["FeatureManagement:NewCheckout:EnabledFor:0:Parameters:Value"] =
                percentage.ToString(CultureInfo.InvariantCulture)
        })
        .Build();

    var services = new ServiceCollection();
    services.AddSingleton<IConfiguration>(config);
    services.AddFeatureManagement().AddFeatureFilter<PercentageFilter>();

    return services.BuildServiceProvider().GetRequiredService<IFeatureManager>();
}

[Fact]
public async Task Feature_IsDisabledByDefault()
{
    var featureManager = CreateFeatureManager(new Dictionary<string, bool>());

    var enabled = await featureManager.IsEnabledAsync("UnknownFeature");

    enabled.Should().BeFalse();
}