Winforms Feature Adoption

WinForms Feature Adoption Scenario

Modernize WinForms applications with framework features introduced in .NET 8+ — dark mode support, modern async APIs, and MVVM data binding patterns.

Prerequisite: Projects must already target .NET 8+ (use dotnet-version-upgrade scenario first if needed).

Scenario Overview

Goal: Enhance existing WinForms applications with modern features that improve user experience, code quality, and maintainability.

Available Features by .NET Version

Workflow Stages

0. Pre-Initialization — validate TFM, detect WinForms projects. Consumed during pre-initialization by the scenario-initializer worker.
1. Feature Selection — determine which features to adopt. Creates feature-selection.md.
2. Planning — identify forms/controls to modernize. Creates plan.md, scenario-instructions.md.
3. Execution — apply feature adoption to the codebase. Uses the WinForms lazy skills.

Pre-Initialization

Tools to Call

Step 1: Validate environment:

• Call get_solution_path() to identify solution
• Scan all WinForms projects (.csproj files with <UseWindowsForms>true</UseWindowsForms>)
• Check each project's <TargetFramework>:
  • Must be net8.0 or higher
  • If below net8.0, inform user and suggest dotnet-version-upgrade first

Step 2: Present feature availability based on detected TFMs:

If all WinForms projects are net9.0+:

Available Features:
- ✅ Dark Mode Support (.NET 9+)
- ✅ Modern Async APIs (.NET 9+)
- ✅ MVVM Pattern (.NET 8+)

If all WinForms projects are net8.0:

Available Features:
- ❌ Dark Mode Support (requires .NET 9+ — upgrade first)
- ❌ Modern Async APIs (requires .NET 9+ — upgrade first)
- ✅ MVVM Pattern (.NET 8+)

If mixed TFMs (some net8.0, some net9.0+):

Available Features (varies by project):
- ⚠️ Dark Mode: available for net9.0+ projects only
- ⚠️ Async APIs: available for net9.0+ projects only
- ✅ MVVM Pattern: available for all .NET 8+ projects

Step 3: Ask user which features to adopt:

• Present checkboxes for available features
• Get scope preference: "Application-wide" or "Selected forms only"
• If "Selected forms only", list detected forms and get user selection

Stage Instructions

Stage 1: Feature Selection

When entering this stage, load: feature-selection.md

Determines which features to apply and to which forms/controls:

• Scan for existing Forms and UserControls
• Detect current patterns (existing async usage, data binding, color handling)
• Identify good candidates for each feature

Stage 2: Planning

When entering this stage, load: planning.md

Creates the execution plan:

• Task breakdown per feature (Dark Mode → Async → MVVM order)
• Dependency analysis (which forms depend on which)
• Risk assessment (Designer compatibility, breaking changes)
• Commit strategy (per-feature or per-form)

Stage 3: Execution

When entering this stage, load: execution.md

Applies the features using lazy-loaded WinForms skills:

• Dark Mode: Uses building-winforms-applications skill for Application.SetColorMode(), control color adjustments
• Async APIs: Uses managing-winforms-async-apis skill for InvokeAsync patterns, async event handlers
• MVVM: Uses managing-winforms-mvvm skill for ViewModel setup, data binding, Command patterns

Success Criteria

• Selected features applied to target forms/controls
• Application builds without errors
• Designer can open and edit modified forms
• All tests pass
• Visual verification completed (for dark mode)

Feature-Specific Validation

Dark Mode

• Application.SetColorMode() called in Program.cs
• SystemColors used for automatic theming
• Custom colors have light/dark variants
• Manually verify appearance in both modes

Async APIs

• All Control.Invoke replaced with Control.InvokeAsync
• Async event handlers wrapped in try/catch
• Cancellation tokens passed where applicable
• No blocking calls on UI thread

MVVM

• ViewModels implement INotifyPropertyChanged (or use ObservableObject)
• Forms set DataContext to ViewModel
• Commands wired to UI actions
• Business logic separated from UI code

Error Handling

Designer compatibility breaks:

1. Check that Designer code follows managing-winforms-designer-code rules
2. Verify no modern C# features in InitializeComponent
3. Revert problematic changes and apply them in regular code files only

Build errors after MVVM adoption:

1. Verify NuGet packages installed (CommunityToolkit.Mvvm if used)
2. Check DataContext binding paths match ViewModel properties
3. Ensure event handlers aren't removed when using Commands

Notes

• This scenario is opt-in enhancement - not required for functional applications
• Features can be adopted incrementally (start with one form, expand later)
• Each feature is independent - can adopt dark mode without MVVM, etc.
• Always validate in the Designer after changes