Blazor Hybrid Migration Guide

Updated: 2026-08-08 · Audited: 2026-06-26

Direction resolved 2026-06-08: ALPA Mobile is moving to Blazor Hybrid. This guide is the canonical reference for migrating the existing MAUI/XAML pages to Razor components. See also migration-estimate.html for LOE and the straggler-migration pattern overview.

Summary

Total estimated effort: 7–10 person-months. See estimate doc for full LOE breakdown, risk factors, and key migration traps.

Prerequisites (P1–P5)

Before any page migration can begin, five infrastructure layers must be in place:

Tier 1 — Migrate Now 16 pages

Low-complexity pages with minimal native coupling. Good candidates to prove out the infrastructure and build team familiarity.

Tier 2 — Migrate Soon 16 pages + 1 control

Medium complexity. Native coupling present but well-understood. Prerequisite services (P3/P4) must be in place.

Tier 3 — Defer 17 pages/controls

High complexity. Significant refactoring required before migration. Total estimated effort: 8–10 weeks.

3.1 SettingsPage — HARD

320+ lines XAML, 5+ commands, geolocation, permissions, messenger. Extract geolocation into IGeolocationService; replace messenger with state container; replace Expander with HTML accordion. Effort: 4–5 days

3.2 HomePage — HARD

Server-driven layout with drag-and-drop tile reordering, 7+ messenger registrations. Extract home layout into service; replace drag-and-drop with CSS drag API; replace messenger with state container. Effort: 5–7 days

3.3 BannerPage — MEDIUM-HARD

Web content loading with 4-step single-threaded render pipeline. Extract loading logic; replace CollectionView with Razor list; replace unread badge with Razor component. Effort: 4–5 days

3.4 DocumentCenterPage — HARD

Grouped CollectionView with 5-scope document hierarchy. Grouped list → nested Razor components; auth guards → Blazor AuthorizeView; extract ShowContent(). Effort: 4–5 days

3.5 PushNotificationsListPage — HARD

330+ line ViewModel, 5-way content switch (Document / WebLink / DeepLink / FlightAlert / Unknown). Extract into IContentRouterService; content routing from Razor to native page. Effort: 4–5 days

3.6 AdvocacyPage — HARD

250+ lines XAML, PAC membership tiers, 4 WebView targets. PAC tier display → @switch; WebView targets → inline HTML or <iframe>; parallel data loading via Task.WhenAll. Effort: 5–7 days

3.7 InternationalDirectoryPage — HARD

Grouped CollectionView, background filtering, country detail HTML, platform SearchBar. Grouped list → continent/country nesting; background filtering → debounced component-level search; country detail → @((MarkupString)html). Effort: 3–4 days

3.8 MyPilotGroupPage — HARD

Heavy messenger usage (DocumentsReady, EventsReady), Launcher. Replace all messenger registrations with state container subscriptions; grouped menu → nested Razor; unread badges → reusable Razor badge component. Effort: 4–5 days

3.9 FTDTFlightDutyPeriodListPage — HARD

445 lines XAML, Expander + SwipeView + grouped CollectionView, Thread.Sleep in background tasks. Replace Expander with <details>/<summary>; replace SwipeView with action buttons; remove Thread.Sleep → Task.Delay. Effort: 5–7 days

3.10 FTDTDutyDetailsPage — HARD

400 lines XAML, SegmentedControl + DatePicker, 25+ bindings, timezone matching, scroll handlers. Segment state machine → @switch; replace scroll commands with JS scrollIntoView; timezone → ITimeZoneService. Effort: 5–7 days

3.11 JumpseatFlightFinderDetailsPage — HARD

Reflection-based property updates (GetProperties().Where(...)). Replace reflection with explicit property setters; policy WebView → inline HTML. Effort: 3–4 days

3.12 JumpseatFlightFinderResultsFiltersPage — HARD

Toolkit Expander, Messenger pattern. State container replacing FilterSettingsHaveChangedMessage; Expander → HTML accordion; modal → Blazor overlay. Effort: 3–4 days

3.13 JumpseatFlightFinderResultsPage — HARD

800+ line ViewModel, pagination, sorting, SwipeView, reflection-based property sync. Replace SwipeView with action buttons; pagination → load-more pattern; replace reflection with explicit mapping. Effort: 5–7 days

3.14 PilotGroupHotelsPage — HARD

Platform-specific map URLs (geo: vs maps.apple.com), grouped collection. IMapLauncherService abstraction; grouped → nested Razor; complex filtering → component state. Effort: 3–4 days

3.15 JumpseatBottomMenu — HARD (custom control)

Code-behind-driven state, icon manipulation, navigation logic. Replace with Razor tab/navigation component; state → component parameters + EventCallbacks; icons → CSS classes. Effort: 2–3 days

3.16 FTDTStartInfoView — HARD (custom control)

Complex form with timezone selection, nested conditional sections. Timezone → <select> from ITimeZoneService; conditional sections → @if; date/time → HTML5 inputs. Effort: 3–4 days

3.17 TimePickerControl — MEDIUM (custom control)

Required by FTDT pages — migrate early. Replace with HTML5 <input type="time"> + Blazor @bind; expose ValueChanged EventCallback. Effort: 1 day

Tier 4 — Defer Late 5 pages

Very high complexity. Require architectural decisions, significant refactoring, or deep inheritance hierarchies. Total estimated effort: 4–6 weeks.

4.1 FTDTDutyPeriodBasePage — VERY HARD

500+ line XAML ControlTemplate, reflection-based view discovery (GetTemplateChild()), base class for 3 duty period variants. Decompose into 5+ child Razor components; replace inheritance with composition (RenderFragment); replace reflection with explicit property updates; replace scroll commands with JS scrollIntoView. Effort: 8–10 days

4.2 FTDTCADutyPeriodDetailsPage — VERY HARD

650+ lines XAML, most complex FTDT page, event subscription chains (DutyPeriod → DutyCollection → Child), reserve operation branching. Break into 6+ child Razor components; replace event chains with cascading parameters; replace SwipeView with action buttons. Effort: 8–10 days

4.3 JumpseatFlightFinderSearchPage — VERY HARD

1100+ line ViewModel (largest in the app), geolocation, debounced airport search, date range restrictions, CancellationTokenSource pattern (Feature #1839). Extract into IAirportSearchService, IFlightSearchService, IGeolocationService; search form → Blazor EditForm; airport picker → autocomplete with debounce. Effort: 8–12 days

4.4 JumpseatToolPage — VERY HARD

Entire UI built programmatically (no XAML); 16 specialized card ViewModels. Convert to declarative Razor component tree; each card ViewModel → individual Razor component. Effort: 4–5 days

4.5 PDFJSPage — HARD

Platform-specific WebView configuration for local PDF files. Decision required: (A) Keep as native page — 0 days; (B) pdf.js via JS interop in Blazor component — 3–5 days; (C) Server-side PDF rendering. Recommendation: Option A during straggler period; revisit after Tier 3.

Tier 5 — Keep Native 5 pages

These remain as native MAUI pages permanently. Blazor components navigate to them via INavigationService.

Service Extraction Roadmap

Before pages in Tiers 2–4 can migrate, these platform-abstraction services must be created:

Priority 1 — Required for Tier 1

Priority 2 — Required for Tier 2

Priority 3 — Required for Tier 3

Priority 4 — Required for Tier 4

Known Traps

• Service Locator anti-pattern — ViewModels using GetService<T> lazy accessors must be converted to ActivatorUtilities factory injection. See GAP-1 work.
• WeakReferenceMessenger — 10+ pages depend on cross-page messaging. Replace with AppStateContainer (scoped DI state) before migrating those pages.
• ObservableRangeCollection — Community Toolkit type used in many ViewModels. Razor components use @foreach + StateHasChanged() — no direct equivalent; refactor to plain List<T> + explicit re-renders.
• AutoLogin JS Bridge — Platform-native JS bridges ([JavascriptInterface] / WKScriptMessageHandler) break if moved inside BlazorWebView. Keep AutoLoginWebViewContentView native (Tier 5).
• StackLayout deprecation — Any remaining StackLayout usage in native pages that host a BlazorWebView should be converted to VerticalStackLayout / HorizontalStackLayout as part of the surrounding page cleanup.

Cross-References