/winforms-expert

name: winforms-expert
description: >-
  Create, modify, debug, or review Windows Forms applications only when the request
  contains a concrete Windows Forms marker. USE FOR: WinForms, Windows Forms,
  System.Windows.Forms, WinForms Form or UserControl designer files (*.Designer.cs or
  *.Designer.vb), Visual Studio WinForms Designer, TableLayoutPanel, BindingSource,
  DataGridView, Control.InvokeAsync, component-tray ownership, or custom control
  serialization. DO NOT USE FOR: WPF or WPF XAML, including Window.InputBindings,
  KeyBinding, commands, or DataContext; .NET MAUI; Avalonia; or any request where none
  of the listed Windows Forms markers is present.
license: MIT

WinForms Expert

Purpose

Implement WinForms changes that compile, behave correctly at runtime, and remain editable in the Visual Studio Designer. Treat `InitializeComponent` and `*.Designer.*` as a serialization format, not ordinary application code; keep behavior in the main partial class and verify designer usability whenever the environment permits.

Execution Contract

Before editing, list the workspace root and locate any task-specific validator, test script, or documented verification command. Read its scenario selector and required arguments before choosing an implementation. After editing:

1. Run that narrow validator first and fix every failure it attributes to the change. 2. Run the focused project build after the validator passes. 3. If the build or any later edit changes source, rerun the narrow validator. 4. Report those commands separately from runtime UI and Designer round-trip checks.

A successful build never substitutes for an available layout, binding, serialization, or designer-safety validator. Do not finish after merely reading a validator or after a build succeeds.

Use the repository's actual command and arguments; the sequence should look like:

pwsh -NoProfile -File <task-validator.ps1> <scenario-arguments>
dotnet build <project> --nologo

Boundaries

Use this skill for:

• Creating or changing a WinForms project, `Form`, `UserControl`, or custom control.
• Editing designer-generated layout, event wiring, resources, or component fields.
• Diagnosing a Form Designer load, serialization, scaling, binding, or toolbox problem.
• Implementing WinForms-specific async, MVVM, accessibility, DPI, or dark-mode behavior.

Do not use it to:

• Convert the application to another UI framework unless the user explicitly requests migration.
• Rewrite working generated code for style alone.
• Change the target framework, language version, SDK, package strategy, startup model, DPI mode,

or application-wide theme unless required by the request.

• Claim that the Visual Studio Designer works when it was not actually opened and exercised.

Inputs

| Input | Required | How to obtain it | |---|---:|---| | Requested UI behavior or defect | Yes | Use the user's request and reproduce the symptom when possible. | | Project language and target framework | Yes | Inspect the project file; do not assume modern .NET or C#. | | Existing Form/UserControl partial files | Yes | Find the main file, designer file, and matching `.resx`. | | Repository conventions | Yes | Inspect nearby WinForms types, build scripts, analyzers, and package management. | | Designer availability | No | Determine whether a compatible Visual Studio WinForms Designer can be opened. |

Non-Negotiable Designer Contract

There are two code contexts:

| Context | Files | Rule | |---|---|---| | Designer serialization | `*.Designer.cs`, `*.Designer.vb`, `InitializeComponent` | Use simple, deterministic statements the designer can parse and regenerate. | | Application behavior | Main partial class, services, view models | Use language features supported by the project's TFM and language version. |

In `InitializeComponent` and designer files:

• Keep control/component construction, property assignments, collection additions, layout

suspension/resumption, resource application, and named event-handler wiring.

• Use class-level control/component fields. Do not add a control to `Controls`,

`Items`, `Columns`, or another serialized collection through a local variable.

• Use named event handlers defined in the main partial file. Never use lambdas or anonymous

delegates in generated event wiring.

• Do not add control flow (`if`, loops, `switch`, `try`/`catch`, `lock`, `await`, `goto`),

local functions, expression-bodied logic, collection expressions, null-conditional or null-coalescing expressions, or other runtime decision logic.

• Do not add business logic, data loading, validation, service calls, or methods other than the

established generated members such as `InitializeComponent` and `Dispose`.

• Preserve the generator's existing namespace style, qualification style, ordering, resources,

and nullable treatment. Do not modernize generated syntax.

• Preserve existing constructors that the designer relies on. A designer-instantiated

`Form`/`UserControl` must have a usable parameterless construction path unless the project uses an established custom designer pattern.

• Keep `BeginInit`/`EndInit`, `SuspendLayout`/`ResumeLayout`, and container ownership balanced.
• For C#, keep generated fields at class scope in the designer partial. For VB, preserve

`Friend WithEvents` fields and prefer `Handles` clauses in the main file.

A safe `InitializeComponent` sequence is:

1. Instantiate controls and components. 2. Instantiate the `IContainer` when owned components require it. 3. Call required `BeginInit` and `SuspendLayout` methods. 4. Assign child control/component properties. 5. Add children to serialized collections and wire named handlers. 6. Configure the containing Form/UserControl after its children. 7. Call matching `EndInit`, `ResumeLayout`, and `PerformLayout` where appropriate. 8. Declare serialized backing fields in the generator's established location.

Move anything more complex to the main part