UI frameworks
Use Blazor for web UI, .NET MAUI for mobile and desktop, and Avalonia for cross-platform desktop. Choose the framework per app.
Blazor
- Choose the render mode per page, not per app. (Microsoft Learn: ASP.NET Core Blazor render modes)
- Use
[PersistentState]for state that must survive prerendering and circuit loss, instead of ad hoc session storage. (Microsoft Learn: ASP.NET Core Blazor prerendered state persistence) - Call
NavigationManager.NotFound()for a missing resource, and show the not-found state in the UI too. It sets a 404 only under static SSR or during prerendering. In an interactive component, it renders the Not Found content with no status code. (Microsoft Learn: ASP.NET Core Blazor navigation) -
In interactive server rendering, take the user's time zone from the browser through a scoped
TimeProviderper circuit. The process's local zone is the server's, not the user's.- Read the zone ID through JavaScript interop with
Intl.DateTimeFormat().resolvedOptions().timeZone, and validate it withTimeZoneInfo.TryFindSystemTimeZoneById. - Register a scoped
TimeProviderthat overridesLocalTimeZonewith that zone.
A component that injects the provider, instead of reading
DateTimeOffset.Now, then renders in the user's local time. For details, see datetime.md. UnderInteractiveServer, interop runs only inOnAfterRenderAsync, so the first render uses the server's zone. Expect one corrective re-render, and handleJSDisconnectedException. (Meziantou: Convert DateTime to the user's time zone with Blazor) - Read the zone ID through JavaScript interop with
-
Read WebAssembly
HttpClientresponses asynchronously. In .NET 10, response streaming is on by default, which is a breaking change.response.Content.ReadAsStreamAsync()returns aBrowserHttpReadStreaminstead of aMemoryStream, and it rejects synchronous calls such asStream.Read(Span<byte>). Fix the call site and keep the default, because streaming keeps large responses off the heap. If a dependency you don't own makes the synchronous call, opt out:- Per request, with
requestMessage.SetBrowserResponseStreamingEnabled(false). - Per project, with
<WasmEnableStreamingResponse>false</WasmEnableStreamingResponse>. - With an environment variable.
(Microsoft Learn: What's new in ASP.NET Core 10, last updated 2026-08-31)
- Per request, with
-
If users can switch culture at run time, set
<BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>. A WebAssembly app otherwise loads only its own culture's data. Remove<BlazorEnableTimeZoneSupport>, which is superseded. For details, see globalization.md.
Component testing
-
Unit-test components with bUnit, and keep Playwright for end-to-end tests. Microsoft has no component testing framework of its own, and Microsoft Learn recommends bUnit, which renders components in-process without a browser.
- Assert with
MarkupMatches, never string equality on markup. It compares HTML semantically, so whitespace and attribute order don't fail the test. - Test behaviour that depends on real JavaScript interop or DOM changes end to end with Playwright. A faked
IJSRuntimeproves nothing about it.
- Assert with
-
Use bUnit 2.x with xUnit v3, the stack in testing.md. In 2.x, the test class inherits
BunitContextand renders withRender<T>(). (bUnit: Writing tests)
.NET MAUI
- Put store billing behind one interface, such as
IBillingService, with conditional compilation per store. Validate every purchase on the server. (Versluis: Implementing Cross-Platform In-App Billing in .NET MAUI Applications) - On Android, set
<UseMaterial3>true</UseMaterial3>(MAUI 10.0.60 and later) for current theming. (Versluis: Give Your .NET MAUI Android Apps a Material 3 Makeover) - Keep trimming on, and exclude a problem assembly instead. Root it in a
Linker.xmlfile referenced by<TrimmerRootDescriptor Include="Linker.xml" />. Turn offPublishTrimmedonly to confirm that trimming causes the problem. (Versluis: Excluding Assemblies from Trimming in .NET MAUI) - Target .NET 9 or later to meet Google Play's 16 KB page size requirement. It concerns native library alignment, not trimming, and needs no other change. (Versluis: Preparing Your .NET MAUI Apps for Google Play's 16 KB Page Size Requirement)
- Test preview SDKs with
sdk.pathsinglobal.jsoninstead of changing the machine default, and ignore the.dotnet/folder it installs. For setup, see project-structure.md. (Versluis: Test .NET MAUI Preview SDKs Locally with global.json sdk.paths)
App lifecycle
-
Handle the app lifecycle with the cross-platform
Windowevents, not per-platform code.- Subclass
Window, and override the events you need:OnCreated,OnActivated,OnDeactivated,OnStopped,OnResumed, andOnDestroying, plusOnBackgroundingon iOS and Mac Catalyst. - Return the subclass from
App.CreateWindow. - In
Stopped, disconnect long-running work and cancel pending requests. InResumed, subscribe again and refresh the visible content.
Use
ConfigureLifecycleEventsinMauiProgramonly for a platform hook with no cross-platform event. (Microsoft Learn: .NET MAUI app lifecycle) - Subclass
Offline & sync
- Build mobile apps offline-first: the app reads and writes the local store, and syncs it with the server when the network allows. Cache remote data locally with an explicit expiry. Use SQLite-net for data you query, and MonkeyCache's
Barrel.Current.Add(key, data, expireIn, eTag)for simple payloads. The ETag overloads skip downloading unchanged responses. (Montemagno: Data caching made simple with Monkey Cache) - Check
Connectivity.NetworkAccess == NetworkAccess.Internetbefore remote calls, and handleConnectivityChanged. Never ping to test reachability. TheIsReachableAPIs were removed deliberately: make the real request and handle its failure. (Montemagno: Upgrading to Xamarin.Essentials from Plugins)
Avalonia & reactive UI
- Keep UI framework references out of view models.
INotifyPropertyChanged, Rx, and Dynamic Data are platform-neutral. A view model with no Avalonia or WPF reference binds on either framework, and you can unit-test it without a UI. (Avalonia Docs: The MVVM pattern) -
Use Dynamic Data for collection state in XAML UIs instead of hand-written
ObservableCollectioncode. Key entities in aSourceCache<T, TKey>, and project filtered and sorted views into a bindable collection withConnect(). Filters and sorts then compose, instead of being rewritten per screen. (Avalonia Docs: Sorting, filtering, and grouping collections)var orders = new SourceCache<Order, int>(o => o.Id); ReadOnlyObservableCollection<Order> openOrders; using var subscription = orders.Connect() .Filter(o => o.Status == OrderStatus.Open) .SortBy(o => o.Placed) .Bind(out openOrders) // the view binds to openOrders; only mutate the cache .Subscribe(); orders.AddOrUpdate(new Order(1, OrderStatus.Open, DateTimeOffset.UtcNow));
Avalonia 12
-
Target Avalonia 12 for new cross-platform desktop apps. It shipped on 2026-04-07, on .NET 10 and SkiaSharp 3.0, with:
- A reworked compositor.
- A real Android
IDispatcherImploverLooperandMessageQueue. - Mac Catalyst support in
Avalonia.iOS.
When you migrate, plan for the removals: Direct2D1, Tizen,
Avalonia.Browser.Blazor,BinaryFormatterusage, and netstandard2.0 in almost every project. (Avalonia 12: Ready for What's Next) -
Keep compiled bindings on, the default in 12. A broken compiled binding fails the build instead of binding to nothing. Use a reflection binding only for a single dynamic case. (Avalonia 12: Ready for What's Next)
- Embed web content with the built-in WebView, not a bundled Chromium. The WebView, formerly a commercial Accelerate component, is open source from 12. It uses each platform's native engine, so it adds nothing to app size. Avalonia retired the Accelerate brand in the same release. Before you work around a feature you remember as commercial-only, check its current licence. (Avalonia: The Avalonia WebView Is Going Open-Source, Avalonia: Retiring Accelerate: One Brand, One Clear Path)
- Use the built-in page navigation for mobile-style apps. Avalonia 12 includes
ContentPage,DrawerPage,CarouselPage,TabView, andPipsPager, with gestures and wrap selection. They replace a custom navigation stack over aContentControl. (Avalonia 12: Ready for What's Next) -
Avalonia's XAML hot reload has been GA since 2026-09-02, and it's paid.
AvaloniaUI.DiagnosticsSupport.HotReloadruns on Windows, macOS, Linux, iOS, and Android.dotnet watchdrives it through the same .NET Hot Reload mechanism as MAUI.- It patches changed elements in place, so view state survives the edit.
- It needs an
AvaloniaUILicenseKeyand a Plus, Pro, or Enterprise subscription.
-
Don't build on Impeller yet. Avalonia and Google's Flutter team are building an experimental GPU-first Impeller renderer for .NET. A maintainer paused the work on 2026-03-09 to ship v12, and no restart had been announced by 2026-09-24. Stay on the default Skia renderer. (Avalonia: Avalonia Partnering with Google's Flutter Team to Bring Impeller Rendering to .NET; Avalonia: Impeller rendering subsystem, discussion #20838)
Source redundancy
Avalonia has the fewest sources of any topic here. Its only independent source, nick-polyak, moved to the watch list for dormancy on 2026-08-23, back catalogue included. What remains is avalonia-blog and the discovery-only awesome-avalonia, both from the Avalonia project and its community.
- They're authoritative on what shipped and how the API works, but they argue for adoption. Read release claims, especially headline FPS numbers, as vendor benchmarks.
- Cite the docs for how something works, such as a binding, a control, or a collection view. Treat any judgement about whether to adopt something as uncorroborated until an independent source supports it. No current source does, so it's an open gap for
vet-source.