YMhut-box-C-/参考/wpfui-main/docs/architecture/RECOMMENDATIONS.md

WPF UI - Architecture Recommendations

Generated: 2026-02-10. These recommendations are based on architectural analysis and should be re-evaluated as the codebase evolves.

Recommendations

Testing

Priority	Recommendation	Rationale	Affected
Critical	Add unit tests for core controls, targeting at least NavigationView, TitleBar, FluentWindow, ContentDialog, NumberBox, and ToggleSwitch.	Only 6 unit tests exist for a 77+ control library. Regressions ship undetected.	src/Wpf.Ui/Controls/, tests/Wpf.Ui.UnitTests/
Critical	Enable test execution in the PR validator CI workflow.	The current workflow builds the Gallery app but never runs tests. Merging broken code is possible.	.github/workflows/
High	Add integration tests for NavigationView page caching and lifecycle transitions.	Caching behavior is undocumented and untested. Users report inconsistent state across navigation.	src/Wpf.Ui/Controls/NavigationView/
Medium	Add contract tests for INavigationService, IContentDialogService, and ISnackbarService.	Service interfaces are the primary public API surface for DI consumers but lack test coverage.	src/Wpf.Ui.Abstractions/, src/Wpf.Ui/Services/

Architecture

Priority	Recommendation	Rationale	Affected
High	Wrap static theme managers (ApplicationThemeManager, ApplicationAccentColorManager) with injectable service interfaces.	Static managers cannot be mocked or unit tested. IThemeService exists but the underlying managers remain untestable.	src/Wpf.Ui/Appearance/
High	Document NavigationView page caching strategy: when pages are created, cached, and disposed.	Caching behavior is implicit in the implementation with no documentation or configuration surface.	src/Wpf.Ui/Controls/NavigationView/
Medium	Add structured logging (e.g., ILogger) to Win32 interop error-handling paths.	Catch blocks intentionally swallow Win32 exceptions but produce no diagnostics. Silent failures make debugging difficult for consumers.	src/Wpf.Ui/Interop/, src/Wpf.Ui/Win32/

Technical Debt

Priority	Recommendation	Rationale	Affected
High	Either implement Wpf.Ui.ToastNotifications or remove it from the solution.	The project is a stub with no implementation. It ships as a package that does nothing.	src/Wpf.Ui.ToastNotifications/
Medium	Audit and reduce public API surface of Win32/Interop namespaces.	Many P/Invoke declarations are public but intended for internal use only. Exposing raw Win32 types couples consumers to implementation details.	src/Wpf.Ui/Win32/, src/Wpf.Ui/Interop/
Low	Consolidate resource dictionary loading paths.	ThemesDictionary and ControlsDictionary have overlapping responsibilities that could confuse consumers.	src/Wpf.Ui/Resources/

CI/CD

Priority	Recommendation	Rationale	Affected
Critical	Add a CI job that runs dotnet test tests/Wpf.Ui.UnitTests/ on every PR.	No tests run in CI. The existing test suite provides zero protection against regressions.	.github/workflows/
High	Add code coverage reporting (Coverlet is already configured) and set a minimum threshold.	Coverage tooling is present but never executed. Without a baseline, coverage can only decrease.	tests/Wpf.Ui.UnitTests/, .github/workflows/
Medium	Add a CI step to run dotnet csharpier --check . to enforce formatting.	CSharpier is configured but not enforced in CI. Formatting inconsistencies can slip through review.	.github/workflows/

Documentation

Priority	Recommendation	Rationale	Affected
Medium	Add XML doc <example> tags with XAML usage to all public control APIs.	Project conventions require examples, but coverage is inconsistent across the 77+ controls.	src/Wpf.Ui/Controls/
Low	Create a process for keeping architecture docs in sync with code changes.	Architecture documentation (generated 2026-02-10) will drift from the implementation without a manual update process or automation.	docs/architecture/

---

Task Backlog

Structured work items derived from the recommendations above. Each item includes acceptance criteria (AC).

TB-001: Add unit tests for core controls [Critical]

Source: Testing #1 AC:

• NavigationView has ≥5 unit tests covering navigation, caching, back stack
• TitleBar has ≥3 tests covering minimize/maximize/close commands
• FluentWindow has ≥2 tests covering backdrop type selection
• ContentDialog has ≥3 tests covering show/hide/result lifecycle
• NumberBox has ≥3 tests covering min/max/step validation
• ToggleSwitch has ≥2 tests covering checked/unchecked state
• All tests follow MethodName_ExpectedResult_WhenCondition naming convention
• All tests use XUnit v3, NSubstitute, AwesomeAssertions

TB-002: Enable test execution in CI [Critical]

Source: CI/CD #1, Testing #2 AC:

• .github/workflows/ contains a job that runs dotnet test tests/Wpf.Ui.UnitTests/ on every PR
• CI job fails the PR if any test fails
• Test results are visible in the GitHub Actions summary
• Job runs on ubuntu-latest or windows-latest as appropriate for WPF tests

TB-003: Add code coverage reporting with threshold [High]

Source: CI/CD #2 AC:

• Coverlet generates coverage report during CI test run
• Coverage report is uploaded as a CI artifact or displayed in PR summary
• Minimum coverage threshold is set (≥50% for initial baseline)
• Build fails if coverage drops below threshold

TB-004: Enforce CSharpier formatting in CI [Medium]

Source: CI/CD #3 AC:

• CI job runs dotnet csharpier --check . on every PR
• PR fails if any file is not formatted
• Contributing guide documents the dotnet csharpier . command

TB-005: Wrap static theme managers with injectable interfaces [High]

Source: Architecture #1 AC:

• IApplicationThemeManager interface exists with Apply(), GetAppTheme(), and Changed event
• IApplicationAccentColorManager interface exists with Apply() and GetColorizationColor()
• Default implementations delegate to existing static classes
• Interfaces are registered in DI via ServiceCollectionExtensions
• Existing static API remains functional (non-breaking change)

TB-006: Document NavigationView page caching strategy [High]

Source: Architecture #2 AC:

• XML doc comments on NavigationCacheMode enum explain each mode
• docs/architecture/cross-cutting/navigation.md describes caching lifecycle
• Gallery demo includes a page demonstrating cache mode differences
• At least one unit test verifies cache behavior per mode

TB-007: Implement or remove Wpf.Ui.ToastNotifications [High]

Source: Technical Debt #1 AC:

• Decision documented: implement with Windows App SDK toast APIs OR remove from solution
• If implemented: at least one functional toast notification scenario works end-to-end
• If removed: NuGet package is delisted, project removed from solution, references cleaned up

TB-008: Audit and reduce Win32/Interop public API surface [Medium]

Source: Technical Debt #2 AC:

• All types in Wpf.Ui.Interop and Wpf.Ui.Win32 are marked internal or documented as public API
• [EditorBrowsable(EditorBrowsableState.Never)] added to types that must remain public for binary compat
• No consumer-facing documentation references internal interop types

TB-009: Add integration tests for NavigationView caching [High]

Source: Testing #3 AC:

• FlaUI integration test navigates forward/backward and verifies page instance identity (cached vs new)
• Test covers NavigationCacheMode.Enabled, Disabled, and Required
• Test verifies INavigationAware.OnNavigatedTo/OnNavigatedFrom callback order

TB-010: Add contract tests for service interfaces [Medium]

Source: Testing #4 AC:

• INavigationService has ≥3 contract tests (Navigate, GoBack, SetService)
• IContentDialogService has ≥2 contract tests (ShowAsync, SetDialogHost)
• ISnackbarService has ≥2 contract tests (Show, SetPresenter)
• Tests verify interface contracts, not implementation details
• Tests use NSubstitute for mock dependencies