[Application Builder] Establish the WinForms host and application lifetime

[JayashreeSF3546]

Fixes

Proposed changes

• Add the WinForms application builder, built application, options, and lifetime APIs, with UI-thread startup and graceful shutdown coordinated with Generic Host.
• Preserve existing Application.Run behavior while supporting startup forms and custom ApplicationContext instances.
• Add automated lifecycle and shutdown tests, C# and Visual Basic samples, architecture and compatibility documentation, and a diagnostic lifecycle benchmark harness.
• Reconcile the lifetime model with Add WindowsFormsLifetime extensions to the .NET Generic Host #11415.

Acceptance criteria

• C# and Visual Basic can configure, build, run, and stop the application model.
• Startup-form and custom-ApplicationContext scenarios are supported.
• UI-thread and synchronization-context behavior is explicit and deterministic.
• Host and WinForms shutdown signals propagate in both directions.
• Existing Application.Run applications remain supported and source compatible.
• The relationship with Add WindowsFormsLifetime extensions to the .NET Generic Host #11415 is documented and reconciled.

Definition of Done

• API contracts and ownership boundaries are documented, and the public API baseline is updated.
• Runtime implementation, automated tests, samples, diagnostics, and compatibility documentation are included.
• Startup/shutdown failure paths and resource cleanup have test coverage; lifecycle performance and resource behavior have a diagnostic benchmark.
• Accessibility impact reviewed: no new visible UI or controls are introduced.
• CI passes on supported architectures; PR checks are pending.

Customer Impact

• WinForms developers can opt into a builder-based application lifecycle and Generic Host integration.
• No migration is required; existing Application.Run usage remains supported.

Regression?

• No known regression. The API is additive; existing Application.Run behavior is retained.

Risk

• Medium. The change coordinates host lifetime, UI-thread ownership, message-loop exit, and cleanup. Automated lifecycle tests cover these paths;

Screenshots

N/A — no visual UI changes.

Test methodology

• dotnet test src\application-builder\..\..\test\unit\System.Windows.Forms\System.Windows.Forms.Tests.csproj --configuration Debug --no-build --no-restore -- --filter-class "System.Windows.Forms.Tests.WinFormsApplicationBuilderTests" — 31 passed, 0 failed.

  Correction: use the actual test project path:
  dotnet test src\test\unit\System.Windows.Forms\System.Windows.Forms.Tests.csproj --configuration Debug --no-build --no-restore -- --filter-class "System.Windows.Forms.Tests.WinFormsApplicationBuilderTests" — 31 passed, 0 failed.

• dotnet build docs\application-builder\benchmarks\WinFormsApplicationBuilder.Benchmarks.csproj --configuration Release --no-restore --verbosity minimal — passed, 0 warnings and 0 errors.

• dotnet run --configuration Release --project docs\application-builder\benchmarks\WinFormsApplicationBuilder.Benchmarks.csproj — completed successfully for all three scenarios. Measurements are diagnostic, not CI thresholds.

• Manual sample runs completed successfully for C# and Visual Basic, using both the default startup form and --custom-context.

• git diff --check — passed.

• Full solution build and full unit-test suite were not run locally; CI checks are pending.

Accessibility testing

N/A — no visible UI or controls are added or changed.

Test environment(s)

• Windows 10.0.26100, x64; .NET SDK 11.0.100-rc.1.26420.103; .NET host 12.0.0-alpha.1.26480.102.

Microsoft Reviewers: Open in CodeFlow

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.84861%. Comparing base (f055ed4) to head (9eefe01).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@              Coverage Diff              @@
##                main      #15240   +/-   ##
=============================================
  Coverage   37.84861%   37.84861%           
=============================================
  Files            246         246           
  Lines           9789        9789           
  Branches        1031        1031           
=============================================
  Hits            3705        3705           
  Misses          5920        5920           
  Partials         164         164           

Flag	Coverage Δ
Debug	37.84861% <ø> (ø)
production	40.04608% <ø> (ø)
test	20.64923% <ø> (ø)
unit	40.04608% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.