# C# Style Guide

This guide defines C# conventions for the gateway, worker, .NET client, test
CLIs, and C# tests.

## Baseline

- Use the latest stable C# version supported by the target runtime.
- Enable nullable reference types in new projects.
- Treat compiler warnings as actionable. Suppress only with a narrow reason.
- Prefer file-scoped namespaces.
- Prefer `sealed` classes unless inheritance is required.
- Keep public APIs explicit and small. Do not expose generated or transport
  internals through handwritten abstractions unless raw access is intentional.

## Source Documentation

- Maintain the existing documentation style in the file, project, and
  surrounding component.
- Write comments that include business-specific or domain-specific context when
  that context is available from the code, surrounding docs, or naming.
- Prefer XML documentation on public APIs when the behavior is not obvious from
  the signature.
- Avoid comments that restate syntax or control flow.

## Naming

- Use PascalCase for public types, methods, properties, events, and enum
  members.
- Use camelCase for local variables, parameters, and private fields.
- Prefix private fields with `_` only when that pattern is already established
  in the project.
- Use `Async` suffixes for methods that return `Task`, `Task<T>`,
  `ValueTask`, or `ValueTask<T>`.
- Keep names aligned with MXAccess terms: `MxStatusProxy`, `ServerHandle`,
  `ItemHandle`, `HResult`, and event family names should match the contract.

## Async And Cancellation

- Accept `CancellationToken` on public async methods that perform I/O or wait.
- Pass cancellation tokens through to called APIs.
- Do not use `Task.Run` to hide blocking COM calls. MXAccess calls belong on
  the worker STA.
- Use `ConfigureAwait(false)` in reusable libraries. It is optional in ASP.NET
  Core request handling where no synchronization context exists.
- Dispose async resources with `await using` when the type implements
  `IAsyncDisposable`.

## Errors

- Preserve protocol, gateway, worker, COM HRESULT, and MXAccess status details.
- Use typed exceptions at API boundaries, but prefer result DTOs when callers
  need method-specific MXAccess output.
- Do not log API keys, passwords, secured write values, or full tag values by
  default.
- Include correlation id and session id in diagnostics when available.

## Protobuf And Generated Code

- Do not hand-edit generated protobuf or gRPC files.
- Keep generated code in a clearly named `Generated` namespace or directory.
- Keep mapping code outside gRPC handlers so it can be unit tested.

## Formatting

- Run `dotnet format` when a solution or project is available.
- Use four spaces for indentation.
- Keep one public type per file unless a small nested type is clearer.
- Avoid region-heavy files. Split large responsibilities into focused types.

## Tests

- Use test names that describe behavior, condition, and result.
- Prefer fake workers, fake transports, or fake gRPC services over live
  MXAccess in unit tests.
- Mark live MXAccess tests as opt-in integration tests.