Winforms Expert

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

Non-Negotiable Designer Contract

There are two code contexts:

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.

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 over brittle absolute positioning.
• Divide complex screens into small layout regions. Avoid a single oversized grid.
• Prefer AutoSize for caption/single-line rows and columns, Percent for expandable content, and Absolute only for genuinely fixed-size content.
• Preserve the existing form's AutoScaleMode. For new forms, choose scaling deliberately based on the project conventions rather than copying coordinates from another DPI.
• Ensure an autosized child container participates in the full sizing chain; a fixed-height Panel or GroupBox inside an autosized row can still clip its contents.
• Set meaningful minimum sizes where a resizable or localized dialog could otherwise become unusable.
• Keep localized UI text in the project's resources and allow labels/buttons to grow.

For dialogs:

• Set AcceptButton, CancelButton, and appropriate DialogResult values.
• Validate the form as a whole when submitting. Do not trap users in a field by canceling every focus change.
• Dispose modal forms according to the project's ownership pattern.

4. Add behavior outside generated code

• Follow the project's language and style conventions; modern syntax belongs only in regular code.
• Keep UI-thread affinity explicit. Marshal control access from background work.
• A normal WinForms async void event handler resumes on its captured UI synchronization context after await unless that context was deliberately bypassed. Direct control access there is valid. Use and await InvokeAsync when code can continue off-context, or when the task/repository contract explicitly requires a marshaled operation; do not rely on an unawaited post.
• For modern .NET versions that support it, select the Control.InvokeAsync overload matching whether the delegate is synchronous/asynchronous and whether it returns a value. Await the returned operation; do not create fire-and-forget UI work.
• async void is acceptable for WinForms event handlers and overrides that must return void, but catch exceptions around awaited work, handle cancellation intentionally, and surface unexpected failures through the application's established error path.
• Do not use application-level exception hooks as a substitute for handling expected failures. Application.ThreadException covers UI-thread exceptions; AppDomain.UnhandledException is primarily a last-chance logging path and does not make continued execution safe.
• Preserve property allocation semantics. Do not change a cached property into => new ... or vice versa without confirming lifetime and disposal behavior.

For application-wide startup:

• Preserve the current startup model. C# projects may configure application defaults in Program.cs; VB projects normally use the VB Application Framework and ApplicationEvents.vb, not a newly invented Program.vb.
• Use the APIs available to the actual TFM. Apply color mode or DPI defaults only when requested or consistent with the app's existing policy.
• Prefer SystemAware when maintaining the normal .NET WinForms DPI behavior. Use PerMonitorV2 only when the application is designed and tested for per-monitor scaling.