UI frameworks
Use Blazor for web UI, .NET MAUI for mobile, 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 Learn says "There's no official Microsoft testing framework for Blazor, but the community-driven project bUnit provides a convenient way to unit test Razor components". It renders components in-process without a browser, and it "isn't supported or maintained by Microsoft".
- Assert with
MarkupMatches, never string equality on markup. It compares HTML semantically, so whitespace and attribute order don't fail the test. (bUnit: Verifying markup from a component) - 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 with xUnit v3, the stack in testing.md, at the versions templates/Directory.Packages.props pins. The test class inherits
BunitContextand renders withRender<T>(). (bUnit: Writing tests)public class CounterTests : BunitContext { [Fact] public void Counter_ClickingButton_IncrementsCount() { // Arrange IRenderedComponent<Counter> cut = Render<Counter>(); // Act cut.Find("button").Click(); // Assert cut.Find("[role=status]").MarkupMatches( """<p role="status">Current count: 1</p>"""); } }
.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>for current theming, on MAUI 10.0.60 or later. The property shipped in 10.0.30, and most control support "landed in SR6 (10.0.60)", the version Versluis recommends "For the most complete experience". (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. That makes the app itself compatible, but "All dependencies in your .NET MAUI project also need 16 KB support". The build reports XA0141 for a shared library that isn't built for 16 KB pages, so update or replace that package. A clean build doesn't prove the app works, so test it on a 16 KB emulator or device. (Versluis: Preparing Your .NET MAUI Apps for Google Play's 16 KB Page Size Requirement, Microsoft Learn: XA0141)
- 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
-
Before you build an existing iOS app with Xcode 27, adopt the UIKit scene lifecycle. Without it, the app shows its splash screen and exits on iOS 27, with "UIScene life cycle is required for apps built with this SDK" in the device log. "Every iOS app built with Xcode 27, on any form factor, needs to adopt this pattern", and a package or workload update doesn't rewrite an existing project's platform files. An app that already has a
MauiUISceneDelegateand a matching scene manifest can skip steps 2 and 3.- Update the .NET MAUI packages to 10.0.110 or later, which "includes the scene-side App Actions dispatch and relevant WebAuthenticator forwarding".
- Add
Platforms/iOS/SceneDelegate.cs, with a public class that derives fromMauiUISceneDelegateand has[Register("SceneDelegate")]. Keep theAppDelegateclass. If the app already has a scene delegate, don't add a second one: "check its base class and registration", keep what it does, and use its registered name in the manifest. A scene configuration name other than__MAUI_DEFAULT_SCENE_CONFIGURATION__skips the default window creation, so that delegate has to create the window itself. An override ofWillConnectkeeps the default window as long as it calls the base implementation. - Add a
UIApplicationSceneManifesttoPlatforms/iOS/Info.plist. Its configuration name is__MAUI_DEFAULT_SCENE_CONFIGURATION__, and its delegate class name matches the registration. Update an existing manifest instead of adding a second key, and do it in "every plist that can produce a shipping app", such as one chosen per build configuration. If the project also targets Mac Catalyst, "make the same two changes there": addPlatforms/MacCatalyst/SceneDelegate.cs, and the same manifest toPlatforms/MacCatalyst/Info.plist. - Move
AppDelegatecallback logic to the scene events. "With scenes enabled, UIKit no longer calls the AppDelegate activation, backgrounding, URL, and user-activity callbacks", whether they'reConfigureLifecycleEventsregistrations or overrides.OpenUrlbecomesSceneOpenUrl, andContinueUserActivitybecomesSceneContinueUserActivity. A URL or user activity that launches the app arrives inSceneWillConnect, which "runs before .NET MAUI creates the window, so defer navigation until the window is ready". If the app opens content from a notification tap, readconnectionOptions.NotificationResponsethere too, "as another cold-start input". If you override a method in the scene delegate, call its base implementation, because the window setup, lifecycle events, and authentication forwarding depend on it. AnAppDelegateoverride ofPerformActionForShortcutItem"is no longer called with scenes enabled", so move it to aConfigureLifecycleEventsregistration that calls its completion callback exactly once. AppDelegate.Windowstaysnullunder scenes, so change any code that reads it afterFinishedLaunching. Test sign-in callbacks and deep links from a cold start and with the app running.- Set the iOS
SupportedOSPlatformVersionto 15.0 or higher, and the Mac Catalyst one to 17.0 or higher, which is macOS 14. They're the minimums the .NET for iOS and Mac Catalyst 27 SDKs support. If you have to keep an older version, stay on a 26.x SDK until you've decided what to support.
Apps created from the 10.0.110 templates already have the scene configuration. Drop this note when projects that predate those templates are rare. (Versluis: Get Your .NET MAUI App Ready for Xcode 27, dotnet/maui: MauiUISceneDelegate.cs) Review by 2027-11-30.
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. MonkeyCache's last stable release is 2.1.1, from 2024-03-14, so check that it still fits your target frameworks before you adopt it. (NuGet: MonkeyCache, 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. Avalonia's guidance is to move application logic into plain objects "with no dependency on Avalonia or any UI framework", which you can unit-test without a UI. (Avalonia Docs: The MVVM pattern)
-
When a collection combines filtering, sorting, and grouping, use Dynamic Data 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's documentation filters a simple collection in the view model, and recommends DynamicData "for complex scenarios". (Avalonia Docs: Sorting, filtering, and grouping collections, DynamicData: README)var orders = new SourceCache<Order, int>(o => o.Id); // The view binds to openOrders. Only mutate the cache. using IDisposable subscription = orders.Connect() .Filter(o => o.Status == OrderStatus.Open) .SortBy(o => o.Placed) .Bind(out ReadOnlyObservableCollection<Order> openOrders) .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 compiled binding reports an unresolved path as a build error. A reflection binding reports it at runtime, as a binding error in the log." Use a reflection binding only for a single dynamic case. (Avalonia 12: Ready for What's Next, Avalonia Docs: Compiled bindings)
- 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, so you don't need a custom navigation stack. (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 the backend is on an internal branch. The latest word, on 2026-11-09, is "Work continues, but there's no public update at this time". 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.