| name | wfa-platform-services |
| description | Phase C of a WinForms-to-Avalonia migration: implement platform and infrastructure adapters for dependencies discovered in Phase A/B, such as persistence, process execution, dialogs, notifications, or environment capabilities. Use only in an explicit migration when such dependencies leak into Forms/core or when the orchestrator routes here. Do not invent adapters for capabilities the product does not have, and do not implement main-window XAML.
|
Phase C — Platform / Infrastructure services
Replace legacy static helpers and environment coupling with injectable, testable adapters.
Read platform abstraction to define ports,
external processes only when the product launches child
processes, and settings migration only when settings exist.
Workflow
1. Catalog touchpoints
| Legacy pattern | Service direction |
|---|
| UI prompts hidden in helpers | host-owned interaction port |
| Static notifications or logging | structured diagnostic/logging port |
| Persisted application preferences | typed, versioned store |
| Filesystem or process calls | narrow adapter with cancellation and failure semantics |
| Environment capability checks | capability query plus supported/unsupported result |
| Legacy deployment integration | replace, isolate, or explicitly retire |
2. Interfaces vs implementations
- Abstractions consumable without Avalonia types where possible
- Implementations in Infrastructure, or in the UI host when they require a UI lifetime
3. Persisted state, when present
Evolve toward a versioned single document when multiple stores appear:
schemaVersion + sections- Ordered migrators
- Reject future versions (do not overwrite with defaults)
- Preserve predecessor data while migration is being validated
- Validate the complete document before commit
- Write to a temporary sibling, flush as required, then atomically replace
- Preserve the last known-good state when parsing or migration fails
- Define in-process and cross-process coordination from the actual deployment model
4. External processes, when present
- Argument arrays, never shell string concatenation with user-controlled values
- Timeout + cancellation
- Distinguish not-found vs started-but-failed
- Document selection and fallback policy
Unavailable dependencies return a structured unavailable result without changing product state.
5. Dependency-backed adapters
Implement the ports defined in Phase B and test success, failure, cancellation, timeout, and
partial-result cleanup with fakes or controlled integration fixtures.
6. Secondary-surface API only
Use a narrow host interaction/window service for secondary surfaces; XAML belongs in Phase D.
7. Logging
Structured logging; bounded UI buffer with events after append; localize at display time.
Corrections seen in practice
- Resolve optional dependencies according to documented product policy, not a universal search order.
- Account for platform differences in process I/O, paths, permissions, and lifecycle when relevant.
- Prefer portable implementations when cross-platform support is an explicit requirement.
- Use one transaction boundary for one logical settings update.
- Treat migration as validated best effort, not a promise of lossless conversion.
- Do not silently change product defaults without an explicit decision.
Deliverables
Handoff
- UI →
wfa-avalonia-ui
- Post-port product evolution ->
wfa-post-port-evolve
