csharp-api-design

Name: csharp-api-design
Author: Aaronontheweb

1.1kstars98forks

How to install csharp-api-design?

aaronontheweb/dotnet-skills/csharp-api-design

$npx -y skills add Aaronontheweb/dotnet-skills --skill csharp-api-design

Installs into the current project.

Summary

Design stable, compatible public APIs using extend-only design principles. Manage API compatibility, wire compatibility, and versioning for NuGet packages and distributed systems.

Files · 1

View on GitHub

SKILL.md

1	# Public API Design and Compatibility
2
3	## When to Use This Skill
4
5	Use this skill when:
6	- Designing public APIs for NuGet packages or libraries
7	- Making changes to existing public APIs
8	- Planning wire format changes for distributed systems
9	- Implementing versioning strategies
10	- Reviewing pull requests for breaking changes
11
12	---
13
14	## The Three Types of Compatibility
15
16	\| Type \| Definition \| Scope \|
17	\|------\|------------\|-------\|
18	\| API/Source \| Code compiles against newer version \| Public method signatures, types \|
19	\| Binary \| Compiled code runs against newer version \| Assembly layout, method tokens \|
20	\| Wire \| Serialized data readable by other versions \| Network protocols, persistence formats \|
21
22	Breaking any of these creates upgrade friction for users.
23
24	---
25
26	## Extend-Only Design
27
28	The foundation of stable APIs: never remove or modify, only extend.
29
30	### Three Pillars
31
32	1. Previous functionality is immutable - Once released, behavior and signatures are locked
33	2. New functionality through new constructs - Add overloads, new types, opt-in features
34	3. Removal only after deprecation period - Years, not releases
35
36	### Benefits
37
38	- Old code continues working in new versions
39	- New and old pathways coexist
40	- Upgrades are non-breaking by default
41	- Users upgrade on their schedule
42
43	Resources:
44	- [Extend-Only Design](https://aaronstannard.com/extend-only-design/)
45	- [OSS Compatibility Standards](https://aaronstannard.com/oss-compatibility-standards/)
46
47	---
48
49	## API Change Guidelines
50
51	### Safe Changes (Any Release)
52
53	```csharp
54	// SAFE: Add NEW overload methods that delegate to existing methods
55	// Existing method - do not modify its signature
56	public void Process(Order order) { ... }
57	// New overload - safe to add
58	public void Process(Order order, CancellationToken ct)
59	{
60	// implementation that handles cancellation
61	}
62
63	// SAFE: Add NEW overloads for additional functionality
64	// Existing method - do not modify
65	public void Send(Message msg) { ... }
66	// New overload - safe to add
67	public void Send(Message msg, Priority priority)
68	{
69	// implementation that handles priority
70	}
71
72	// ADD new types, interfaces, enums
73	public interface IOrderValidator { }
74	public enum OrderStatus { Pending, Complete, Cancelled }
75
76	// ADD new members to existing types
77	public class Order
78	{
79	public DateTimeOffset? ShippedAt { get; init; } // NEW
80	}
81	```
82
83	### Unsafe Changes (Never or Major Version Only)
84
85	```csharp
86	// REMOVE or RENAME public members
87	public void ProcessOrder(Order order); // Was: Process()
88
89	// CHANGE parameter types or order
90	public void Process(int orderId); // Was: Process(Order order)
91
92	// CHANGE return types
93	public Order? GetOrder(string id); // Was: public Order GetOrder()
94
95	// CHANGE access modifiers
96	internal class OrderProcessor { } // Was: public
97
98	// ADD optional parameters to EXISTING methods (binary incompatible!)
99	// The compiled IL method signature changes - callers compiled against
100	// the old signature will get MissingMethodException at runtime.
101	// Optional parameter defaults are baked into the CALLER's assembly at compile time.
102	public void Process(Order order, CancellationToken ct = default); // Breaks binary compat!
103	public void Send(Message msg, Priority priority = Priority.Normal); // Breaks binary compat!
104	// Correct approach: add a NEW overload method instead (see Safe Changes above)
105
106	// ADD required parameters without defaults
107	public void Process(Order order, ILogger logger); // Breaks callers!
108	```
109
110	### Deprecation Pattern
111
112	```csharp
113	// Step 1: Mark as obsolete with version (any release)
114	[Obsolete("Obsolete since v1.5.0. Use ProcessAsync instead.")]
115	public void Process(Order order) { }
116
117	// Step 2: Add new recommended API (same release)
118	public Task ProcessAsync(Order order, CancellationToken ct = default);
119
120	// Step 3: Remove in next major version (v2.0+)
121	// Only after users have had time to migrate
122	```
123
124	---
125
126	## API Approval Testing
127
128	Prevent accidental breaking changes with automated API surface testing.
129
130	### Using ApiApprover + Verify
131
132	```bash
133	dotnet add package PublicApiGenerator
134	dotnet add package Verify.Xunit
135	```
136
137	```csharp
138	[Fact]
139	public Task ApprovePublicApi()
140	{
141	var api = typeof(MyLibrary.PublicClass).Assembly.GeneratePublicApi();
142	return Verify(api);
143	}
144	```
145
146	Creates `ApprovePublicApi.verified.txt`:
147
148	```csharp
149	namespace MyLibrary
150	{
151	public class OrderProcessor
152	{
153	public OrderProcessor() { }
154	public void Process(Order order) { }
155	public Task ProcessAsync(Order order, CancellationToken ct = default) { }
156	}
157	}
158	```
159
160	Any API change fails the test - reviewer must explicitly approve changes.
161
162	### PR Review Process
163
164	1. PR includes changes to `*.verified.txt` files
165	2. Reviewers see exact API surface changes in diff
166	3. Breaking changes are imm

People who liked this also viewed

6 picks

Type

csharp-api-design

1.1kstars98forks

View on GitHub

How to install csharp-api-design?

aaronontheweb/dotnet-skills/csharp-api-design

$npx -y skills add Aaronontheweb/dotnet-skills --skill csharp-api-design

Installs into the current project.

Summary

Design stable, compatible public APIs using extend-only design principles. Manage API compatibility, wire compatibility, and versioning for NuGet packages and distributed systems.

Files · 1

View on GitHub

SKILL.md

1	# Public API Design and Compatibility
2
3	## When to Use This Skill
4
5	Use this skill when:
6	- Designing public APIs for NuGet packages or libraries
7	- Making changes to existing public APIs
8	- Planning wire format changes for distributed systems
9	- Implementing versioning strategies
10	- Reviewing pull requests for breaking changes
11
12	---
13
14	## The Three Types of Compatibility
15
16	\| Type \| Definition \| Scope \|
17	\|------\|------------\|-------\|
18	\| API/Source \| Code compiles against newer version \| Public method signatures, types \|
19	\| Binary \| Compiled code runs against newer version \| Assembly layout, method tokens \|
20	\| Wire \| Serialized data readable by other versions \| Network protocols, persistence formats \|
21
22	Breaking any of these creates upgrade friction for users.
23
24	---
25
26	## Extend-Only Design
27
28	The foundation of stable APIs: never remove or modify, only extend.
29
30	### Three Pillars
31
32	1. Previous functionality is immutable - Once released, behavior and signatures are locked
33	2. New functionality through new constructs - Add overloads, new types, opt-in features
34	3. Removal only after deprecation period - Years, not releases
35
36	### Benefits
37
38	- Old code continues working in new versions
39	- New and old pathways coexist
40	- Upgrades are non-breaking by default
41	- Users upgrade on their schedule
42
43	Resources:
44	- [Extend-Only Design](https://aaronstannard.com/extend-only-design/)
45	- [OSS Compatibility Standards](https://aaronstannard.com/oss-compatibility-standards/)
46
47	---
48
49	## API Change Guidelines
50
51	### Safe Changes (Any Release)
52
53	```csharp
54	// SAFE: Add NEW overload methods that delegate to existing methods
55	// Existing method - do not modify its signature
56	public void Process(Order order) { ... }
57	// New overload - safe to add
58	public void Process(Order order, CancellationToken ct)
59	{
60	// implementation that handles cancellation
61	}
62
63	// SAFE: Add NEW overloads for additional functionality
64	// Existing method - do not modify
65	public void Send(Message msg) { ... }
66	// New overload - safe to add
67	public void Send(Message msg, Priority priority)
68	{
69	// implementation that handles priority
70	}
71
72	// ADD new types, interfaces, enums
73	public interface IOrderValidator { }
74	public enum OrderStatus { Pending, Complete, Cancelled }
75
76	// ADD new members to existing types
77	public class Order
78	{
79	public DateTimeOffset? ShippedAt { get; init; } // NEW
80	}
81	```
82
83	### Unsafe Changes (Never or Major Version Only)
84
85	```csharp
86	// REMOVE or RENAME public members
87	public void ProcessOrder(Order order); // Was: Process()
88
89	// CHANGE parameter types or order
90	public void Process(int orderId); // Was: Process(Order order)
91
92	// CHANGE return types
93	public Order? GetOrder(string id); // Was: public Order GetOrder()
94
95	// CHANGE access modifiers
96	internal class OrderProcessor { } // Was: public
97
98	// ADD optional parameters to EXISTING methods (binary incompatible!)
99	// The compiled IL method signature changes - callers compiled against
100	// the old signature will get MissingMethodException at runtime.
101	// Optional parameter defaults are baked into the CALLER's assembly at compile time.
102	public void Process(Order order, CancellationToken ct = default); // Breaks binary compat!
103	public void Send(Message msg, Priority priority = Priority.Normal); // Breaks binary compat!
104	// Correct approach: add a NEW overload method instead (see Safe Changes above)
105
106	// ADD required parameters without defaults
107	public void Process(Order order, ILogger logger); // Breaks callers!
108	```
109
110	### Deprecation Pattern
111
112	```csharp
113	// Step 1: Mark as obsolete with version (any release)
114	[Obsolete("Obsolete since v1.5.0. Use ProcessAsync instead.")]
115	public void Process(Order order) { }
116
117	// Step 2: Add new recommended API (same release)
118	public Task ProcessAsync(Order order, CancellationToken ct = default);
119
120	// Step 3: Remove in next major version (v2.0+)
121	// Only after users have had time to migrate
122	```
123
124	---
125
126	## API Approval Testing
127
128	Prevent accidental breaking changes with automated API surface testing.
129
130	### Using ApiApprover + Verify
131
132	```bash
133	dotnet add package PublicApiGenerator
134	dotnet add package Verify.Xunit
135	```
136
137	```csharp
138	[Fact]
139	public Task ApprovePublicApi()
140	{
141	var api = typeof(MyLibrary.PublicClass).Assembly.GeneratePublicApi();
142	return Verify(api);
143	}
144	```
145
146	Creates `ApprovePublicApi.verified.txt`:
147
148	```csharp
149	namespace MyLibrary
150	{
151	public class OrderProcessor
152	{
153	public OrderProcessor() { }
154	public void Process(Order order) { }
155	public Task ProcessAsync(Order order, CancellationToken ct = default) { }
156	}
157	}
158	```
159
160	Any API change fails the test - reviewer must explicitly approve changes.
161
162	### PR Review Process
163
164	1. PR includes changes to `*.verified.txt` files
165	2. Reviewers see exact API surface changes in diff
166	3. Breaking changes are imm

People who liked this also viewed

6 picks

Type