---

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 partial class, usually after InitializeComponent has run.

Rules That Change the Answer

Use the symptom to choose one WinForms-specific repair. Do not list several plausible patterns when the existing project and failure identify one.

| Symptom or request | Do | Never | Verify | |---|---|---|---| | A Form/UserControl builds but the Designer cannot instantiate it | Preserve the runtime constructor, add a designer-usable parameterless path, and defer dependency use until runtime load with an explicit design/null guard | Construct production services, open files, or query data from the designer path | The runtime composition root still supplies the real dependency; the design path reaches InitializeComponent without invoking it | | Controls/components disappear, duplicate, or fail after Designer save/reopen | Restore the generated field/collection shape and balance every BeginInit/EndInit and SuspendLayout/ResumeLayout pair | Patch the symptom in OnLoad or move serialized controls into local variables | Save, close, reopen, and inspect the regenerated diff | | A designer-created Timer, BindingSource, image list, or similar component outlives the Form | Create the components container and pass it to the component constructor | Add ad hoc disposal while leaving designer ownership inconsistent | Closing the Form disposes the container-owned component and the component remains designer-managed | | Adding/removing list items does not refresh a bound WinForms list control | Use BindingList<T> or the repository's adapter that raises WinForms list-change notifications | Treat ObservableCollection<T> as a drop-in WinForms DataSource | Mutate the list after binding and observe the control update | | Nested content clips at DPI, font, or localization changes | Inspect AutoSize, AutoSizeMode, Dock, MinimumSize, MaximumSize, and row/column styles from the leaf through every parent; remove the actual growth cap while preserving intentional minimums; also inspect sibling controls positioned against the growing chain and keep them in responsive layout | Assume AutoSize = true is sufficient, increase one fixed Size, bypass a parent container, or leave a sibling where expanded content can overlap it | Exercise resize plus the relevant DPI/font/text expansion | | UI work is posted but completion/errors are lost | Put the operation in a Task-returning method that callers/tests can await; let the required async void event handler do only await RefreshAsync(); update controls on the captured WinForms context or await InvokeAsync when execution can be off-context; restore control state in finally | Keep the whole operation inside async void, use _ =, BeginInvoke, a dead cancellation catch, or an application-wide exception hook as the normal path | Await the task-returning method through success and failure; verify the UI entry point delegates to it | | Text must be localizable | Use the existing .resx and ComponentResourceManager.ApplyResources serialization pattern | Leave fallback UI text hard-coded in InitializeComponent | Build, switch culture when possible, and perform a Designer save/reopen | | A VB app needs startup, single-instance, or unhandled-UI hooks | Extend ApplicationEvents.vb; qualify Microsoft.VisualBasic.ApplicationServices event-argument types when ambiguous; restore, activate, and bring the existing MainForm forward; log e.Exception; set e.ExitApplication = True explicitly | Invent Program.vb, add Sub Main, replace generated startup, or leave post-error continuation implicit | The configured StartupObject and generated application file remain unchanged, no new entry point exists, and the final report states the exit choice | | Review finds no actual designer defect | Leave tracked project/source files byte-for-byte unchanged and report why the suspicious construct is harmless | Clean up warnings, reformat generated code, or modernize unrelated syntax | Run the narrow available check and focused build; confirm the source diff is empty | | The workspace contains a task-specific validator or test script | Run the narrow repository-provided check after editing and before the generic build; treat its failure as evidence that the change is incomplete | Skip the specialized check because the project compiles, or claim a Designer round trip from static validation | Report the exact validator and build commands separately, then state whether runtime UI and Designer round-trip checks were actually available |

Workflow

1. Establish the project constraints

1. Inspect the solution/project, target framework, language, nullable setting, package management, application startup, and existing build commands.
2. Identify whether the app targets modern .NET or .NET Framework. Preserve its current family unless migration is requested.
3. Read the complete partial-file set and .resx for every affected Form/UserControl before editing. Check base classes and nearby controls for repository conventions.
4. If the defect is designer-specific, record the exact load/serialization error and determine whether the problem occurs before making broad changes.

2. Plan the serialization boundary

1. Classify each change as serialized UI state or runtime behavior.
2. Put only designer-representable state in InitializeComponent.
3. Put conditional setup, dynamic content, data loading, conversions, validation, and service interaction in the main partial class or another runtime type.
4. Prefer the smallest designer diff. Do not reorder or reformat the whole generated file.
5. If editing generated code is avoidable, use the Designer or a runtime initialization method instead. If direct editing is necessary, follow the existing generated shape exactly.

3. Implement the UI structure

For new or substantially revised layouts:

• Prefer TableLayoutPanel, FlowLayoutPanel, SplitContainer, and nested UserControls o