dotnet-csharp-api-design

Design-time principles for creating public .NET APIs that are intuitive, consistent, and forward-compatible. Covers naming conventions for API surface, parameter ordering, return type selection, error reporting strategies, extension points, and wire compatibility for serialized types. This skill addresses the design decisions that make APIs compatible and usable in the first place, before enforcement tooling gets involved.

Version assumptions: .NET 8.0+ baseline. Examples use modern C# features (primary constructors, collection expressions) where appropriate.

Scope

• Naming conventions for public API types, methods, and parameters
• Parameter ordering and overload progression
• Return type selection (nullable, IReadOnlyList, IAsyncEnumerable, ValueTask)
• Error reporting strategies (exceptions, Try pattern, result objects)
• Extension points (interfaces, delegates, builder patterns)
• Wire compatibility for serialized types

Out of scope

• Binary/source compatibility enforcement and tooling -- see [skill:dotnet-library-api-compat]
• PublicApiAnalyzers, Verify snapshots, and CI validation of API surface -- see [skill:dotnet-api-surface-validation]