WinForms Expert

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.

🎯 Critical Generic WinForms Issue: Dealing with Two Code Contexts

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

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

(Try meaningful naming of controls, derive style from existing codebase, if possible.)

private void InitializeComponent()
{
    // 1. Instantiate
    _picDogPhoto = new PictureBox();
    _lblDogographerCredit = new Label();
    _btnAdopt = new Button();
    _btnMaybeLater = new Button();
    
    // 2. Components
    components = new Container();
    
    // 3. Suspend
    ((ISupportInitialize)_picDogPhoto).BeginInit();
    SuspendLayout();
    
    // 4. Configure controls
    _picDogPhoto.Location = new Point(12, 12);
    _picDogPhoto.Name = "_picDogPhoto";
…

Remember: Complex UI configuration logic goes in main .cs file, NOT .designer.cs.

Modern C Features (Regular Code Only)

Apply ONLY to .cs files (event handlers, business logic). NEVER in .designer.cs or InitializeComponent.

Style Guidelines

Property Patterns (⚠️ CRITICAL - Common Bug Source!)

// ❌ WRONG - Memory leak
public Brush BackgroundBrush => new SolidBrush(BackColor);

// ✅ CORRECT - Cached
public Brush BackgroundBrush { get; } = new SolidBrush(Color.White);

// ✅ CORRECT - Dynamic
public Font CurrentFont => _customFont ?? DefaultFont;

Never "refactor" one to another without understanding semantic differences!

Prefer Switch Expressions over If-Else Chains

// ✅ NEW: Instead of countless IFs:
private Color GetStateColor(ControlState state) => state switch
{
    ControlState.Normal => SystemColors.Control,
    ControlState.Hover => SystemColors.ControlLight,
    ControlState.Pressed => SystemColors.ControlDark,
    _ => SystemColors.Control
};

Prefer Pattern Matching in Event Handlers

// Note nullable sender from .NET 8+ on!
private void Button_Click(object? sender, EventArgs e)
{
    if (sender is not Button button || button.Tag is null)
        return;
    
    // Use button here
}