WinForms Expert

# WinForms Development Guidelines

These are the coding and design guidelines and instructions for WinForms Expert Agent development.

When customer asks/requests will require the creation of new projects

**New Projects:**

* Prefer .NET 10+. Note: MVVM Binding requires .NET 8+.

* Prefer `Application.SetColorMode(SystemColorMode.System);` in `Program.cs` at application startup for DarkMode support (.NET 9+).

* Make Windows API projection available by default. Assume 10.0.22000.0 as minimum Windows version requirement.

    <TargetFramework>net10.0-windows10.0.22000.0</TargetFramework>

**Critical:**

**📦 NUGET:** New projects or supporting class libraries often need special NuGet packages.

Follow these rules strictly:

* Prefer well-known, stable, and widely adopted NuGet packages - compatible with the project's TFM.

* Define the versions to the latest STABLE major version, e.g.: `[2.*,)`

**⚙️ Configuration and App-wide HighDPI settings:** *app.config* files are discouraged for configuration for .NET.

For setting the HighDpiMode, use e.g. `Application.SetHighDpiMode(HighDpiMode.SystemAware)` at application startup, not *app.config* nor *manifest* files.

Note: `SystemAware` is standard for .NET, use `PerMonitorV2` when explicitly requested.

**VB Specifics:**

- In VB, do NOT create a *Program.vb* - rather use the VB App Framework.

- For the specific settings, make sure the VB code file *ApplicationEvents.vb* is available.

Handle the `ApplyApplicationDefaults` event there and use the passed EventArgs to set the App defaults via its properties.

| Property | Type | Purpose |

|----------|------|---------|

| ColorMode | `SystemColorMode` | DarkMode setting for the application. Prefer `System`. Other options: `Dark`, `Classic`. |

| Font | `Font` | Default Font for the whole Application. |

| HighDpiMode | `HighDpiMode` | `SystemAware` is default. `PerMonitorV2` only when asked for HighDPI Multi-Monitor scenarios. |

---

🎯 Critical Generic WinForms Issue: Dealing with Two Code Contexts

| Context | Files/Location | Language Level | Key Rule |

|---------|----------------|----------------|----------|

| **Designer Code** | *.designer.cs*, inside `InitializeComponent` | Serialization-centric (assume C# 2.0 language features) | Simple, predictable, parsable |

| **Regular Code** | *.cs* files, event handlers, business logic | Modern C# 11-14 | Use ALL modern features aggressively |

**Decision:** In *.designer.cs* or `InitializeComponent` → Designer rules. Otherwise → Modern C# rules.

---

🚨 Designer File Rules (TOP PRIORITY)

⚠️ Make sure Diagnostic Errors and build/compile errors are eventually completely addressed!

❌ Prohibited in InitializeComponent

| Category | Prohibited | Why |

|----------|-----------|-----|

| Control Flow | `if`, `for`, `foreach`, `while`, `goto`, `switch`, `try`/`catch`, `lock`, `await`, VB: `On Error`/`Resume` | Designer cannot parse |

| Operators | `? :` (ternary), `??`/`?.`/`?[]` (null coalescing/conditional), `nameof()` | Not in serialization format |

| Functions | Lambdas, local functions, collection expressions (`...=[]` or `...=[1,2,3]`) | Breaks Designer parser |

| Backing fields | Only add variables with class field scope to ControlCollections, never local variables! | Designer cannot parse |

**Allowed method calls:** Designer-supporting interface methods like `SuspendLayout`, `ResumeLayout`, `BeginInit`, `EndInit`

❌ Prohibited in *.designer.cs* File

❌ Method definitions (except `InitializeComponent`, `Dispose`, preserve existing additional constructors)

❌ Properties

❌ Lambda expressions, DO ALSO NOT bind events in `InitializeComponent` to Lambdas!

❌ Complex logic

❌ `??`/`?.`/`?[]` (null coalescing/conditional), `nameof()`

❌ Collection Expressions

✅ Correct Pattern

✅ File-scope namespace definitions (preferred)

📋 Required Structure of InitializeComponent Method

| Order | Step | Example |

|-------|------|---------|

| 1 | Instantiate controls | `button1