dotnet-core

.NET and C# Development Guidelines

Directives for .NET Core and C# development. Use Australian English spelling throughout.

Naming Conventions

• Public members: PascalCase (classes, methods, properties, constants)
• Private fields: camelCase with leading underscore (_userRepository)
• Constants: UPPER_CASE or PascalCase for public API constants
• Interfaces: Prefix with I (e.g. IUserRepository)
• Async methods: Suffix with Async (e.g. GetUserByIdAsync)
• File names: Match primary type (e.g. UserService.cs)

Modern C# Features

• Records: Prefer records for immutable DTOs, value objects, and API responses. Use positional syntax for simple data; add computed properties or with expressions when needed.
• Pattern matching: Use switch expressions and property patterns instead of long if-else chains. Prefer pattern matching in exception handlers for mapping to HTTP status codes.
• Nullable reference types: Enable <Nullable>enable</Nullable>. Use T? for optional returns; avoid null! except where framework requires it. Validate constructor parameters with ?? throw new ArgumentNullException(nameof(param)).
• Primary constructors: Use for DI-injected services and simple DTOs where it reduces boilerplate.

Async/Await Rules

• Use async/await for all I/O (database, HTTP, file system). Never use .Result or .Wait() — they block and can deadlock.
• Use Task.WhenAll for independent parallel operations; avoid sequential awaits when operations are independent.
• Use ConfigureAwait(false) only in library code, not in ASP.NET Core request handlers.
• Never use async void except for event handlers.

Dependency Injection

• Register services by interface. Use AddScoped for DbContext and request-scoped services; AddSingleton for caches and configuration; AddTransient for stateless, lightweight services.
• Prefer constructor injection. Validate dependencies with ?? throw new ArgumentNullException(nameof(x)).
• Use extension methods (e.g. AddApplicationServices) to group registrations.