Csharp Rules

C#/.NET Rules

These rules come from app/rules/csharp/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in C#/.NET. Apply them when writing or reviewing C#/.NET code.

C# Coding Style

Naming

• PascalCase: classes, structs, enums, interfaces, methods, properties, events.
• camelCase: local variables, parameters, private fields.
• Prefix interfaces with I: IUserRepository, IDisposable.
• Prefix private fields with _: private readonly ILogger _logger;.
• UPPER_SNAKE: not conventional in C#. Use PascalCase for constants.

Nullable Reference Types

• Enable <Nullable>enable</Nullable> in all projects.
• Use string? only when null is semantically meaningful.
• Use ! (null-forgiving) operator sparingly -- only when compiler cannot infer.
• Use ?? (null-coalescing) and ?. (null-conditional) for safe navigation.
• Use required modifier (C# 11) on properties that must be set at initialization.

Records and Types

• Use record for immutable value objects and DTOs.
• Use record struct for small, stack-allocated value types.
• Use init properties for immutable-after-construction objects.
• Use with expressions for non-destructive mutation of records.
• Use primary constructors (C# 12) for concise class definitions.

Pattern Matching

• Use is pattern for type checks: if (obj is string s).
• Use switch expressions for exhaustive matching over enums/types.
• Use property patterns: user is { Age: > 18, Role: "admin" }.
• Use relational patterns: size is > 0 and < 100.
• Use list patterns (C# 11): numbers is [1, 2, .., var last].

Async/Await

• Suffix async methods with Async: GetUserAsync().
• Return Task<T> or ValueTask<T>, never void (except event handlers).
• Use await with ConfigureAwait(false) in library code.
• Use CancellationToken parameters in all async public APIs.
• Prefer ValueTask<T> when synchronous completion is common.

File Organization

• One type per file. File name matches type name.
• Use file-scoped namespaces (C# 10): namespace MyApp.Services;.
• Order members: fields, constructors, properties, public methods, private methods.
• Use global using directives in a single GlobalUsings.cs file.

Formatting

• Use .editorconfig with C# style rules committed to the repository.
• Use dotnet format for automated formatting.
• Use Roslyn analyzers for compile-time style enforcement.
• Max line length: 120 characters.

C# Frameworks

ASP.NET Core

• Use minimal APIs for simple endpoints. Use controllers for complex APIs.
• Use [ApiController] attribute for automatic model validation and error responses.
• Use Results.Ok(), Results.NotFound() for typed HTTP results.
• Use endpoint filters / middleware for cross-cutting concerns.
• Use IHostedService / BackgroundService for long-running background tasks.
• Map routes with app.MapGet(), app.MapPost() for minimal API style.

Entity Framework Core

• Use code-first migrations: dotnet ef migrations add, dotnet ef database update.
• Use DbContext with scoped lifetime (one per request).
• Use AsNoTracking() for read-only queries. Use AsTracking() only for updates.
• Use Include() / ThenInclude() for eager loading related entities.
• Use shadow properties for audit fields (CreatedAt, UpdatedAt).
• Use HasQueryFilter() for soft-delete and multi-tenancy global filters.

Blazor

• Use Blazor Server for internal tools. Use Blazor WASM for public-facing SPAs.
• Use @inject for dependency injection in components.
• Use EventCallback<T> for parent-child component communication.
• Use CascadingValue for deeply shared state (theme, auth).
• Use StateContainer pattern with events for cross-component state management.

SignalR

• Use strongly-typed hubs: Hub<IClientMethods> for compile-time safety.
• Use HubContext<T> for sending messages from outside hubs.
• Use groups for targeted broadcasting: Groups.AddToGroupAsync().
• Configure automatic reconnection on the client side.

MassTransit / Messaging

• Use MassTransit for message bus abstraction over RabbitMQ/Azure Service Bus.
• Define messages as record types for immutability.
• Use consumers (IConsumer<T>) for message handling.
• Use sagas for long-running, multi-step workflows with state.
• Use retry and circuit breaker policies for transient failures.

Logging

• Use ILogger<T> via DI. Never instantiate loggers manually.
• Use structured logging: _logger.LogInformation("User {UserId} logged in", userId).
• Use Serilog with sinks for structured, centralized logging.
• Use log scopes for request correlation: using (_logger.BeginScope(...)).

Configuration

• Use appsettings.json + environment-specific overrides + environment variables.
• Bind configuration sections to strongly-typed classes with IOptions<T>.
• Use IOptionsMonitor<T> for configuration that changes at runtime.
• Validate configuration at startup with ValidateDataAnnotations().

Health Checks

• Use app.MapHealthChecks("/health") for liveness probes.
• Register custom health checks for database, cache, and external service dependencies.
• Use AspNetCore.HealthChecks.* NuGet packages for common checks.

C# Patterns

Error Handling

• Use exceptions for truly exceptional conditions. Use Result<T> pattern for expected failures.
• Create domain exception hierarchies: class DomainException : Exception.
• Use when clause in catch: catch (HttpRequestException e) when (e.StatusCode == 404).
• Use ExceptionDispatchInfo.Capture(e).Throw() to preserve original stack trace.
• Return Result<T, Error> types for operations with expected failure modes.

Async Patterns

• Use Task.WhenAll() for concurrent independent operations.
• Use SemaphoreSlim for async-compatible resource limiting.
• Use Channel<T> for async producer-consumer patterns.
• Use IAsyncEnumerable<T> for streaming data from async sources.
• Use Polly for retry, circuit breaker, and timeout policies.
• Never use .Result or .Wait() on tasks (deadlock risk). Always await.

Dependency Injection

• Use constructor injection exclusively. Avoid service locator pattern.
• Register services in Program.cs or IServiceCollection extension methods.
• Use Scoped for request-lifetime services, Singleton for stateless, Transient for lightweight.
• Use IOptions<T> pattern for configuration injection.
• Validate DI registrations at startup with ValidateOnBuild = true.

LINQ

• Use method syntax for complex queries. Use query syntax for joins.
• Use FirstOrDefault() over First() for safe access.
• Use AsNoTracking() for read-only EF Core queries (performance).
• Avoid materializing large collections: use IQueryable<T> until final projection.
• Use Select() to project only needed columns from database queries.

Disposable Pattern

• Implement IAsyncDisposable for async cleanup.
• Use await using var resource = ...; for deterministic async disposal.
• Use IDisposable with using declaration (C# 8) for scope-based cleanup.
• Register disposable services in DI container (auto-disposed at scope end).

Mediator / CQRS

• Use MediatR for command/query separation and pipeline behaviors.
• Commands: IRequest<Result> for mutations. Queries: IRequest<T> for reads.
• Use pipeline behaviors for cross-cutting: validation, logging, transactions.
• Keep handlers thin: delegate to domain services for business logic.

Value Objects

• Use record types for value objects with structural equality.
• Use factory methods with validation: public static Result<Email> Create(string value).
• Override ToString() for logging-friendly representations.
• Use implicit/explicit operators sparingly for primitive wrapper conversions.