WinForms Expert

Your specialized agent for developing and modernizing Windows Forms applications using .NET, covering UI design, data binding, custom controls, and migration to modern .NET.

When to Use This Agent

Choose WinForms Expert when:

• Building new Windows Forms desktop applications with .NET 8+
• Modernizing legacy .NET Framework WinForms apps to .NET 8
• Implementing complex UI layouts, custom controls, or data binding scenarios
• Debugging WinForms-specific issues (rendering, threading, DPI scaling)
• Integrating WinForms apps with modern services (REST APIs, databases, Azure)

Consider alternatives when:

• You need web applications — use a web developer agent
• You prefer WPF or MAUI for desktop — use a WPF or MAUI agent
• You need cross-platform desktop apps — use an Electron or MAUI agent

Quick Start

Copy
# .claude/agents/winforms-expert.yml
name: WinForms Expert
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Windows Forms specialist for desktop application development, modernization, and .NET migration

Example invocation:

claude "Create a data-bound WinForms DataGridView with sorting, filtering, inline editing, and row validation that connects to a SQL Server database via Entity Framework Core"

Core Concepts

WinForms Architecture (Modern .NET)

├── Program.cs                    # Application entry point
├── MainForm.cs / .Designer.cs    # Main form + designer code
├── Forms/
│   ├── SettingsForm.cs           # Settings dialog
│   └── DetailForm.cs             # Detail view
├── Controls/
│   └── CustomDataGrid.cs         # Custom user controls
├── Models/
│   └── Customer.cs               # Data models
├── Services/
│   └── CustomerService.cs        # Business logic
├── Data/
│   └── AppDbContext.cs           # EF Core context
└── appsettings.json              # Configuration

Key WinForms Patterns

Pattern	Purpose	Implementation
MVP (Model-View-Presenter)	Separate UI from logic	Presenter holds logic, Form is passive view
Data Binding	Sync UI with data	BindingSource + DataGridView
Async/Await	Keep UI responsive	async Task methods, avoid Control.Invoke
Dependency Injection	Testable services	Microsoft.Extensions.DependencyInjection
User Controls	Reusable UI components	UserControl subclass

Configuration

Parameter	Description	Default
dotnet_version	Target .NET version	8.0
dpi_awareness	DPI scaling mode (per-monitor, system, unaware)	per-monitor-v2
data_access	Data layer (ef-core, dapper, ado-net)	ef-core
pattern	Architecture pattern (mvp, mvvm, code-behind)	mvp
migration_source	Legacy .NET Framework version (if migrating)	none

Best Practices

1. Use async/await for all I/O operations. Database queries, API calls, and file operations should use async Task methods to keep the UI thread responsive. Never call .Result or .Wait() on tasks from the UI thread — this causes deadlocks.

2. Implement the MVP pattern to separate concerns. Keep forms thin — they handle UI events and display data. Move all business logic, validation, and data access to presenter and service classes. This makes your logic testable without spinning up WinForms.

3. Use BindingSource for data binding. Connect DataGridView, TextBox, and other controls through BindingSource rather than manually setting values. Binding provides automatic two-way synchronization, change notifications, and navigation support.

4. Enable Per-Monitor V2 DPI awareness. Modern Windows displays use varying DPI scales. Set Application.SetHighDpiMode(HighDpiMode.PerMonitorV2) in Program.cs and use AutoScaleMode.Dpi on forms. Test at 100%, 125%, 150%, and 200% scaling.

5. Use dependency injection even in WinForms. Configure ServiceCollection in Program.cs, register services and forms, and resolve forms from the service provider. This enables testability and consistent lifetime management across your application.

Common Issues

UI freezes during long-running operations. Running database queries or API calls on the UI thread blocks the message pump. Convert to async/await, or for CPU-bound work, use Task.Run() and marshal results back to the UI thread with Control.Invoke() or SynchronizationContext.

DataGridView throws cross-thread exceptions. WinForms controls can only be accessed from the thread that created them. When updating the DataGridView from a background thread, use this.Invoke(() => { grid.DataSource = results; }) or use async/await which automatically returns to the UI thread.

Legacy .NET Framework WinForms app fails to build on .NET 8. Migration requires updating the project file format (SDK-style), replacing packages.config with PackageReference, and handling API differences. Use the .NET Upgrade Assistant tool to automate the most common migration steps, then fix remaining incompatibilities manually.