Bạn đã dựng API, viết migration, thêm cache và hàng đợi — nhưng sản phẩm vẫn thiếu phần người dùng thật sự cầm trên tay. Với lập trình viên full-stack .NET, .NET MAUI là con đường ngắn nhất để có app Android, iOS, Windows và macOS từ một project C#. Bài này chỉ ra MAUI 10 cho bạn gì, code nào chạy được ngay, và những giới hạn bạn phải chấp nhận trước khi cam kết.
Mục lục
Cập nhật 2026
- .NET MAUI 10 (10.0.120) chạy trên .NET 10 LTS. Xamarin.Forms đã ngừng hỗ trợ từ 2024-05-01, nên mọi so sánh “MAUI vs Xamarin.Forms” chỉ còn giá trị lịch sử.
Application.MainPageđã obsolete; template hiện tại overrideCreateWindow. Nếu bạn copy code cũ có dòngMainPage = new AppShell(), hãy đổi.CommunityToolkit.Mvvm8.4.2 là chuẩn de facto cho MVVM: source generator sinh property và command, không reflection, chạy tốt với trimming.- MAUI vẫn không có target Linux desktop chính thức. Cần Linux thì Avalonia là lựa chọn, không phải MAUI.
Một project, nhiều target framework
Điểm khác biệt cốt lõi so với Xamarin.Forms là mô hình single project. Một file .csproj khai báo nhiều TargetFramework, mỗi TFM tương ứng một nền tảng. Code trong thư mục gốc được biên dịch cho tất cả nền tảng; code trong Platforms/Android, Platforms/iOS, Platforms/MacCatalyst, Platforms/Windows chỉ vào đúng target của nó.
<!-- File: Evotek.Field.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net10.0-windows10.0.19041.0</TargetFrameworks>
<OutputType>Exe</OutputType>
<UseMaui>true</UseMaui>
<SingleProject>true</SingleProject>
<ApplicationTitle>Evotek Field</ApplicationTitle>
<ApplicationId>vn.evotek.field</ApplicationId>
<ApplicationDisplayVersion>1.0</ApplicationDisplayVersion>
<ApplicationVersion>1</ApplicationVersion>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
</Project>
Điều kiện IsOSPlatform('windows') không phải mẹo vặt: target Windows chỉ build được trên Windows, còn iOS và Mac Catalyst chỉ build được trên macOS. Nếu bạn để cả bốn TFM vô điều kiện, build trên CI Linux sẽ chết ngay ở bước restore. Cách làm thực tế là để ba TFM đa nền tảng, thêm Windows có điều kiện, và luôn build iOS trên runner macOS.
Cài workload một lần trên máy dev:
dotnet workload install maui
dotnet new maui -n Evotek.Field
Khởi động ứng dụng và dependency injection
MauiProgram.CreateMauiApp là Program.cs của bạn: một IServiceCollection, một ILoggingBuilder, và không có middleware. Mọi thứ bạn đã học về DI trong ASP.NET Core áp dụng nguyên vẹn — chỉ khác vòng đời: app mobile sống lâu, nên Scoped không tự động reset theo request HTTP.
// File: MauiProgram.cs
using Evotek.Field.Services;
using Evotek.Field.ViewModels;
using Evotek.Field.Views;
using Microsoft.Extensions.Logging;
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.ConfigureFonts(fonts => fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular"));
// Typed client: cùng IHttpClientFactory như bên ASP.NET Core.
builder.Services.AddHttpClient<IWorkOrderApi, WorkOrderApi>(client =>
{
client.BaseAddress = new Uri("https://api.evotek.vn/");
client.Timeout = TimeSpan.FromSeconds(20);
});
builder.Services.AddSingleton<WorkOrdersViewModel>();
builder.Services.AddTransient<WorkOrdersPage>();
builder.Services.AddTransient<WorkOrderDetailPage>();
#if DEBUG
builder.Logging.AddDebug();
#endif
return builder.Build();
}
}
Cẩn thận với vòng đời. Một Singleton giữ HttpClient là đúng, nhưng một Singleton giữ DbContext trong app mobile là lỗi: DbContext không thread-safe và sẽ giữ change tracker suốt phiên app. Dùng AddDbContextFactory và tạo context ngắn hạn trong từng thao tác, giống cách bạn làm với IDbContextFactory trong background service.
// File: App.xaml.cs
public partial class App : Application
{
private readonly IServiceProvider _services;
public App(IServiceProvider services)
{
InitializeComponent();
_services = services;
}
protected override Window CreateWindow(IActivationState? activationState)
=> new Window(new AppShell(_services));
}
UseMauiApp<App>() resolve App từ container, nên constructor có tham số vẫn chạy. Đây là lý do CreateWindow là chỗ đúng để dựng AppShell, thay vì gán MainPage trong constructor như code 2024.
MVVM: XAML khai báo, ViewModel quyết định
MAUI không ép bạn dùng MVVM, nhưng code-behind phình ra rất nhanh khi có state, lỗi mạng và loading. Với CommunityToolkit.Mvvm, mỗi property chỉ cần một field kèm attribute; generator sinh ra IsRefreshing, OnPropertyChanged và command tương ứng.
// File: ViewModels/WorkOrdersViewModel.cs
using System.Collections.ObjectModel;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
public partial class WorkOrdersViewModel : ObservableObject
{
private readonly IWorkOrderApi _api;
[ObservableProperty]
private bool _isRefreshing;
[ObservableProperty]
private string? _error;
public ObservableCollection<WorkOrder> Items { get; } = new();
public WorkOrdersViewModel(IWorkOrderApi api) => _api = api;
[RelayCommand]
private async Task LoadAsync(CancellationToken token)
{
IsRefreshing = true;
Error = null;
try
{
var items = await _api.GetAsync(token);
Items.Clear();
foreach (var item in items)
{
Items.Add(item);
}
}
catch (HttpRequestException ex)
{
Error = ex.Message;
}
finally
{
IsRefreshing = false;
}
}
}
[RelayCommand] trên method có CancellationToken sinh ra LoadCommand kiểu IAsyncRelayCommand — command tự tạo token và hủy được khi page biến mất. Tên command theo convention: bỏ hậu tố Async, thêm Command. Đừng tự viết ICommand bằng tay nữa.
<!-- File: Views/WorkOrdersPage.xaml -->
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:vm="clr-namespace:Evotek.Field.ViewModels"
xmlns:models="clr-namespace:Evotek.Field.Models"
x:Class="Evotek.Field.Views.WorkOrdersPage"
x:DataType="vm:WorkOrdersViewModel"
Title="Phiếu việc">
<Grid RowDefinitions="Auto,*" Padding="16" RowSpacing="12">
<Label Text="{Binding Error}" TextColor="Crimson" />
<RefreshView Grid.Row="1"
IsRefreshing="{Binding IsRefreshing}"
Command="{Binding LoadCommand}">
<CollectionView ItemsSource="{Binding Items}">
<CollectionView.ItemTemplate>
<DataTemplate x:DataType="models:WorkOrder">
<Border Padding="12" Margin="0,0,0,8" StrokeThickness="1">
<VerticalStackLayout Spacing="4">
<Label Text="{Binding Code}" FontAttributes="Bold" />
<Label Text="{Binding CustomerName}" />
</VerticalStackLayout>
</Border>
</DataTemplate>
</CollectionView.ItemTemplate>
</CollectionView>
</RefreshView>
</Grid>
</ContentPage>
x:DataType ở cả page và DataTemplate là bắt buộc nếu bạn muốn compiled bindings. Không có nó, binding chạy qua reflection, tốn CPU mỗi lần scroll và không cảnh báo được lỗi chính tả property. Đây là cú pháp dễ quên nhất khi chuyển từ WPF sang MAUI.
Navigation bằng Shell
Shell đóng gói ba pattern phổ biến: tab, flyout và stack navigation. Bạn khai báo cấu trúc một lần, route bằng URI, và deep link đến cùng route đó từ notification.
// File: AppShell.xaml.cs
public partial class AppShell : Shell
{
public AppShell(IServiceProvider services)
{
InitializeComponent();
// Page cần DI (ViewModel, API client) không thể dùng DataTemplate.
WorkOrders.Content = services.GetRequiredService<WorkOrdersPage>();
Routing.RegisterRoute("workorder", typeof(WorkOrderDetailPage));
}
}
Trong AppShell.xaml, ShellContent chỉ cần khai báo x:Name="WorkOrders", Title và Route; phần Content do code-behind gán để page đi qua container. Điều hướng có tham số:
await Shell.Current.GoToAsync($"workorder?id={workOrder.Id}");
// File: Views/WorkOrderDetailPage.xaml.cs
[QueryProperty(nameof(Id), "id")]
public partial class WorkOrderDetailPage : ContentPage
{
public string Id { get; set; } = string.Empty;
}
Giữ nguyên tắc: route là dữ liệu, không phải chuỗi hard-code rải khắp app. Gom vào một lớp AppRoutes để đổi tên route không phải grep toàn bộ project. Và đừng dùng Navigation.PushAsync lẫn Shell.GoToAsync trong cùng một app — hai ngăn xếp điều hướng chồng lên nhau là bug khó tái hiện.
Code đặc thù nền tảng và handler
MAUI render bằng handler, không phải renderer. Mỗi control trừu tượng ánh xạ sang control native qua một Handler; muốn sửa chi tiết native, bạn AppendToMapping hoặc thay handler. Đây là API chính thức cho những thứ XAML không diễn đạt được.
// File: MauiProgram.cs (trong CreateMauiApp)
Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("NoBorder", (handler, view) =>
{
#if ANDROID
handler.PlatformView.BackgroundTintList =
Android.Content.Res.ColorStateList.ValueOf(Android.Graphics.Color.Transparent);
#elif IOS || MACCATALYST
handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
#elif WINDOWS
handler.PlatformView.BorderThickness = new Microsoft.UI.Xaml.Thickness(0);
#endif
});
Ưu điểm của mapping so với custom handler: nó áp dụng cho mọi Entry trong app, không cần đăng ký từng instance. Nhược điểm: nếu bạn cần logic phức tạp, hãy tạo handler riêng trong Platforms/<platform> và đăng ký bằng ConfigureMauiHandlers. Quy ước thư mục quan trọng: file trong Platforms không được include vào TFM khác, nên đừng đặt type dùng chung ở đó.
Hiệu năng: những thứ thật sự tạo khác biệt
- CollectionView, không phải ListView.
ListViewlà control legacy, virtualize kém và không hỗ trợ template phức tạp.CollectionViewcó virtualization thật, nhưng chỉ khi bạn không bọc nó trongScrollView— lồng ScrollView sẽ tắt virtualization và render toàn bộ item. - Không block UI thread. Mọi I/O là async; constructor page không được gọi API đồng bộ. Dùng
Loadedevent hoặc trigger command sau khi page hiện. - Ảnh đúng kích thước. Resizetizer sinh ảnh theo density từ một file nguồn; đừng nhét ảnh 4000px vào
Resources/Imagesrồi scale bằngHeightRequest. - Trim-friendly JSON. Trên iOS, AOT và trimming là mặc định; reflection-based serializer dễ vỡ. Dùng
JsonSerializerContext(source generator) thay vìJsonSerializer.Deserialize<T>mù mờ. - Khởi động. Đo bằng
StopwatchquanhCreateMauiApptrên thiết bị thật. Đăng ký hàng trăm service trong DI và resolve singleton nặng trong constructorApplà nguyên nhân phổ biến của màn hình trắng 2–3 giây.
Blazor Hybrid: lựa chọn thứ ba
Nếu team bạn đã có Blazor component và muốn tái sử dụng, MAUI cho phép nhúng Razor vào app native qua BlazorWebView. UI chạy trong WebView, nhưng code C# chạy trong process app và gọi được API native — không phải Blazor Server qua mạng.
// File: MauiProgram.cs
builder.Services.AddMauiBlazorWebView();
#if DEBUG
builder.Services.AddBlazorWebViewDeveloperTools();
#endif
<BlazorWebView HostPage="wwwroot/index.html">
<RootComponent Selector="#app" ComponentType="{x:Type local:Components.Routes}" />
</BlazorWebView>
Đánh đổi rõ ràng: bạn đổi độ mượt native lấy tốc độ phát triển và khả năng chia sẻ component với web. Với app line-of-business dạng form và bảng, đó thường là trade tốt. Với app cần gesture phức tạp, scroll mượt 120Hz hay animation tinh tế, XAML native vẫn thắng. Nếu bạn chưa chọn được giữa Blazor, Razor Pages và MVC cho phần web, bài so sánh cuối trang sẽ giúp bạn quyết định.
Build và publish từng nền tảng
# Android: AAB để upload CH Play
dotnet publish -f net10.0-android -c Release -p:AndroidPackageFormat=aab
# Windows: bản unpackaged, không cần MSIX
dotnet publish -f net10.0-windows10.0.19041.0 -c Release \
-p:RuntimeIdentifierOverride=win-x64 -p:WindowsPackageType=None
# iOS: bắt buộc chạy trên macOS, cần provisioning profile
dotnet publish -f net10.0-ios -c Release -p:RuntimeIdentifier=ios-arm64
Ký Android cần keystore và AndroidSigningKeyStore/AndroidSigningKeyAlias trong CI secret, không commit vào repo. iOS cần certificate và profile trên máy Mac hoặc runner macOS. Bản Windows WindowsPackageType=None chạy được không cần cài đặt, nhưng không auto-update — nếu cần update, dùng MSIX và gói cài đặt có ký.
MAUI, Avalonia, Flutter hay React Native?
| Lựa chọn | Chọn khi |
|---|---|
| .NET MAUI | Team đã sống trong .NET; app line-of-business; cần chia sẻ model, service, validation với backend; chấp nhận không có Linux desktop. |
| Avalonia | Cần desktop Linux thật, hoặc muốn XAML chạy đa nền tảng không phụ thuộc workload MAUI; kiểm soát rendering tốt hơn. |
| Flutter | Ưu tiên UI đồng nhất pixel-perfect trên nhiều nền tảng, team không cần C#, chấp nhận thêm ngôn ngữ Dart. |
| React Native | Team mạnh TypeScript/React, cần hệ sinh thái JS và chia sẻ logic với web; app chủ yếu là form và list. |
Tiêu chí quyết định thực tế không phải “framework nào mạnh nhất” mà là: ai sẽ bảo trì trong 3 năm tới, có cần Linux không, có cần truy cập SDK native đời mới không, và ngân sách cho hai codebase có chấp nhận được không. Với team .NET, chi phí học Flutter thường lớn hơn chi phí chấp nhận giới hạn của MAUI.
Giới hạn thật của MAUI
- Không có Linux desktop. Không phải “chưa hỗ trợ tốt” — không có target. Đây là lý do tồn tại của Avalonia trong các dự án .NET cần Linux.
- iOS build cần macOS. Không có đường vòng hợp pháp trên Windows; CI phải có runner macOS.
- Không có XAML designer. Bạn sống bằng Hot Reload và device preview; layout phức tạp vẫn phải chỉnh tay.
- Hệ sinh thái control bên thứ ba mỏng hơn WPF/Flutter. Chart, data grid, barcode scanner cần mua hoặc tự viết handler.
- App size và startup cao hơn native tối giản. Với app nội bộ thì không đáng lo; với app tiêu dùng tải hàng triệu lượt, cần đo trên thiết bị tầm trung.
- Debug trên emulator chậm. Luôn test trên máy thật trước khi kết luận “app lag”.
2027
.NET 11 (GA tháng 11/2026) mang MAUI sang chu kỳ STS mới; .NET 12 LTS đến tháng 11/2027. Hướng đi rõ ràng là siết chất lượng handler, cải thiện startup và AOT thay vì thêm control mới. Nếu bạn định cam kết MAUI cho sản phẩm dài hạn, hãy theo dõi release notes của MAUI 11 trước khi nâng cấp — breaking change ở tầng handler từng làm vỡ custom mapping.
Checklist bắt đầu
- Cài
dotnet workload install maui, tạo project bằng templatemaui, chạy trên một nền tảng trước khi mở rộng. - Dựng DI trong
MauiProgram: typedHttpClient, ViewModel singleton, page transient. - Thay
MainPagebằngCreateWindow; kiểm tra không còn API obsolete trong build warning. - Bật
x:DataTypecho mọi page vàDataTemplate. - Đo startup và scroll trên thiết bị thật, không chỉ trên emulator.
- Viết một handler mapping nhỏ để làm quen trước khi cần custom control.



