Instructions for adding new public APIs (properties, methods, events, delegates) to existing WinForms controls or components. Covers API issue tracking, PublicAPI file maintenance, property/event conventions, CodeDOM serialization, design-time attributes, and XML documentation.
These rules apply when adding new public or protected members — properties,
methods, events, delegates, enums, or interfaces — to an existing WinForms
control or component. For creating entirely new controls, or for general coding
standards, see the coding-standards skill instead.
Golden rule: Every new public API must be tracked, reviewed, documented, and serialization-safe before it ships.
Every new public API surface change requires a corresponding API proposal
issue in the api-suggestion format, which will be reviewed by the .NET API
review board.
Before creating anything, search the upstream repository () for an existing issue with the label that covers the planned API change.
dotnet/winformsapi-suggestion⚠️ NEVER create a new issue in the upstream repo (
dotnet/winforms).
The API issue must contain all of the following sections. If any information is missing, stop and ask the user before proceeding with implementation.
Section 1 — Background and motivation: Why is this API needed? What scenario does it enable?
Section 2 — API Proposal (C# code block with full public signature, no method bodies):
namespace System.Windows.Forms;
public partial class ExistingControl
{
public Color NewProperty { get; set; }
public event EventHandler? NewPropertyChanged;
protected virtual void OnNewPropertyChanged(EventArgs e);
}
Section 3 — API Usage (C# code block showing consumption):
var control = new ExistingControl();
control.NewProperty = Color.Red;
control.NewPropertyChanged += (s, e) => Console.WriteLine("Changed!");
Section 4 — Alternative Designs: Other approaches considered.
Section 5 — Risks: Breaking changes, perf regressions, etc.
Section 6 — Will this feature affect UI controls? Designer support, accessibility impact, localization needs.
All new public and protected members must be recorded in the PublicAPI text files so the Roslyn analyzer can enforce API compatibility.
PublicAPI.Unshipped.txtAdd entries for every new API surface to the Unshipped file of the
project that contains the new code. For System.Windows.Forms controls this