Skip to content

UI frameworks

Targets net11.0 csharp-15Last reviewed 2026-11-14 freshSources aspnet-blog avalonia-blog gerald-versluis james-montemagno meziantou ms-learn

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 TimeProvider per circuit. The process's local zone is the server's, not the user's.

    1. Read the zone ID through JavaScript interop with Intl.DateTimeFormat().resolvedOptions().timeZone, and validate it with TimeZoneInfo.TryFindSystemTimeZoneById.
    2. Register a scoped TimeProvider that overrides LocalTimeZone with 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. Under InteractiveServer, interop runs only in OnAfterRenderAsync, so the first render uses the server's zone. Expect one corrective re-render, and handle JSDisconnectedException. (Meziantou: Convert DateTime to the user's time zone with Blazor)

  • Read WebAssembly HttpClient responses asynchronously. In .NET 10, response streaming is on by default, which is a breaking change. response.Content.ReadAsStreamAsync() returns a BrowserHttpReadStream instead of a MemoryStream, and it rejects synchronous calls such as Stream.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)

  • 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 IJSRuntime proves nothing about it.

    (Microsoft Learn: Test components in ASP.NET Core Blazor)

  • Use bUnit with xUnit v3, the stack in testing.md, at the versions templates/Directory.Packages.props pins. The test class inherits BunitContext and renders with Render<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

App lifecycle

  • Handle the app lifecycle with the cross-platform Window events, not per-platform code.

    1. Subclass Window, and override the events you need: OnCreated, OnActivated, OnDeactivated, OnStopped, OnResumed, and OnDestroying, plus OnBackgrounding on iOS and Mac Catalyst.
    2. Return the subclass from App.CreateWindow.
    3. In Stopped, disconnect long-running work and cancel pending requests. In Resumed, subscribe again and refresh the visible content.

    Use ConfigureLifecycleEvents in MauiProgram only for a platform hook with no cross-platform event. (Microsoft Learn: .NET MAUI app lifecycle)

    public class MainWindow : Window
    {
        protected override void OnStopped() => _sync.PauseBackgroundSync();
    
        protected override void OnResumed() => _sync.ResumeAndRefresh();
    }
    
  • 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 MauiUISceneDelegate and a matching scene manifest can skip steps 2 and 3.

    1. Update the .NET MAUI packages to 10.0.110 or later, which "includes the scene-side App Actions dispatch and relevant WebAuthenticator forwarding".
    2. Add Platforms/iOS/SceneDelegate.cs, with a public class that derives from MauiUISceneDelegate and has [Register("SceneDelegate")]. Keep the AppDelegate class. 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 of WillConnect keeps the default window as long as it calls the base implementation.
    3. Add a UIApplicationSceneManifest to Platforms/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": add Platforms/MacCatalyst/SceneDelegate.cs, and the same manifest to Platforms/MacCatalyst/Info.plist.
    4. Move AppDelegate callback logic to the scene events. "With scenes enabled, UIKit no longer calls the AppDelegate activation, backgrounding, URL, and user-activity callbacks", whether they're ConfigureLifecycleEvents registrations or overrides. OpenUrl becomes SceneOpenUrl, and ContinueUserActivity becomes SceneContinueUserActivity. A URL or user activity that launches the app arrives in SceneWillConnect, 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, read connectionOptions.NotificationResponse there 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. An AppDelegate override of PerformActionForShortcutItem "is no longer called with scenes enabled", so move it to a ConfigureLifecycleEvents registration that calls its completion callback exactly once.
    5. AppDelegate.Window stays null under scenes, so change any code that reads it after FinishedLaunching. Test sign-in callbacks and deep links from a cold start and with the app running.
    6. Set the iOS SupportedOSPlatformVersion to 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.Internet before remote calls, and handle ConnectivityChanged. Never ping to test reachability. The IsReachable APIs 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 ObservableCollection code. Key entities in a SourceCache<T, TKey>, and project filtered and sorted views into a bindable collection with Connect(). 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 IDispatcherImpl over Looper and MessageQueue.
    • Mac Catalyst support in Avalonia.iOS.

    When you migrate, plan for the removals: Direct2D1, Tizen, Avalonia.Browser.Blazor, BinaryFormatter usage, 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, and PipsPager, 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.HotReload runs on Windows, macOS, Linux, iOS, and Android.

    • dotnet watch drives 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 AvaloniaUILicenseKey and a Plus, Pro, or Enterprise subscription.

    (Avalonia: Hot Reload for Avalonia)

  • 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.