maui-data-binding
Guidance for .NET MAUI XAML and C# data bindings — compiled bindings, INotifyPropertyChanged / ObservableObject, value converters, binding modes, multi-binding, relative bindings, fallbacks, and MVVM best practices. USE FOR: setting up compiled bindings with x:DataType, implementing INotifyPropertyChanged or CommunityToolkit ObservableObject, creating IValueConverter / IMultiValueConverter, choosing binding modes, configuring BindingContext, relative bindings, binding fallbacks, StringFormat, code-behind SetBinding with lambdas, and enforcing XC0022/XC0025 warnings. DO NOT USE FOR: CollectionView item templates and layouts (use maui-collectionview), Shell navigation data passing (use maui-shell-navigation), dependency injection (use maui-dependency-injection), or animations triggered by property changes (use .NET MAUI animation APIs).
managedcode · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add managedcode/dotnet-skills --skill maui-data-binding技能说明
name: maui-data-binding description: >- Guidance for .NET MAUI XAML and C# data bindings — compiled bindings, INotifyPropertyChanged / ObservableObject, value converters, binding modes, multi-binding, relative bindings, fallbacks, and MVVM best practices. USE FOR: setting up compiled bindings with x:DataType, implementing INotifyPropertyChanged or CommunityToolkit ObservableObject, creating IValueConverter / IMultiValueConverter, choosing binding modes, configuring BindingContext, relative bindings, binding fallbacks, StringFormat, code-behind SetBinding with lambdas, and enforcing XC0022/XC0025 warnings. DO NOT USE FOR: CollectionView item templates and layouts (use maui-collectionview), Shell navigation data passing (use maui-shell-navigation), dependency injection (use maui-dependency-injection), or animations triggered by property changes (use .NET MAUI animation APIs). license: MIT
.NET MAUI Data Binding
Wire UI controls to ViewModel properties with compile-time safety, correct change notification, and minimal overhead. Prefer compiled bindings everywhere and treat binding warnings as build errors.
When to Use
- Adding
x:DataTypecompiled bindings to a new or existing page - Implementing
INotifyPropertyChangedor CommunityToolkitObservableObject - Creating or consuming
IValueConverter/IMultiValueConverter - Choosing the correct
BindingModefor a control property - Setting
BindingContextin XAML or code-behind - Using relative bindings (
Self,AncestorType,TemplatedParent) - Applying
StringFormat,FallbackValue, orTargetNullValue - Writing AOT-safe code bindings with
SetBindingand lambdas (.NET 9+)
When Not to Use
- CollectionView layouts / templates — use the
maui-collectionviewskill - Shell navigation parameters — use the
maui-shell-navigationskill - Service registration / DI — use the
maui-dependency-injectionskill - Property-change-triggered animations — use built-in .NET MAUI animation APIs
Inputs
- A .NET MAUI project targeting .NET 8 or later
- XAML pages or C# code-behind where bindings are declared
- A ViewModel class (or plan to create one)
Rules That Change the Answer
Apply these to every binding answer — they are the differences between "it compiles" and "it actually updates the UI".
| Situation | Do this | Not this |
|---|---|---|
Deciding where x:DataType goes | Put it wherever a binding scope starts — the page/view root, and each DataTemplate | Scattering it on arbitrary children that share the parent's BindingContext |
| A binding falls back to reflection (XC0022 / XC0023) | Add the right x:DataType for that binding scope; for XC0023 remove the explicit x:DataType="{x:Null}" | x:DataType="x:Object" to silence it — this disables compile-time checking |
A DataTemplate inherits x:DataType from an outer scope (XC0024) | Give the DataTemplate its own x:DataType | Leaving it to resolve against the wrong type |
| ViewModel change notification | ObservableObject + [ObservableProperty], or implement INotifyPropertyChanged | A plain POCO base class — bindings will never update |
| Bindings show blank | Check BindingContext is actually set | Assuming the binding path is wrong |
| Enforcing compiled bindings | Set MauiEnableXamlCBindingWithSourceCompilation to true, then <WarningsAsErrors>XC0022;XC0025</WarningsAsErrors> | Promoting XC0025 without the switch if the project uses Source= / RelativeSource bindings |
Do not restructure a ViewModel or add a converter that the user did not ask for
and that fixes no real defect. Adding x:DataType is different: when you are
already editing a page's bindings, recommending compiled bindings is in scope.
Compiled Bindings — x:DataType Placement
Compiled bindings are 8–20× faster than reflection-based bindings and are
required for NativeAOT / trimming. Enable them with x:DataType.
Placement rules
Set x:DataType only where BindingContext is set:
- Page / View root — where you assign
BindingContext. - DataTemplate — which creates a new binding scope.
Do not scatter x:DataType on arbitrary child elements. Adding
x:DataType="x:Object" on children to escape compiled bindings is an
anti-pattern — it disables compile-time checking and reintroduces reflection.
<!-- ✅ Correct: x:DataType at the page root -->
<ContentPage xmlns:vm="clr-namespace:MyApp.ViewModels"
x:DataType="vm:MainViewModel">
<StackLayout>
<Label Text="{Binding Title}" />
<Slider Value="{Binding Progress}" />
</StackLayout>
</ContentPage>
<!-- ❌ Wrong: x:DataType scattered on children -->
<ContentPage x:DataType="vm:MainViewModel">
<StackLayout>
<Label Text="{Binding Title}" />
<Slider x:DataType="x:Object" Value="{Binding Progress}" />
</StackLayout>
</ContentPage>
DataTemplate always needs its own x:DataType
<CollectionView ItemsSource="{Binding People}">
<CollectionView.ItemTemplate>
<DataTemplate x:DataType="model:Person">
<Label Text="{Binding FullName}" />
</DataTemplate>
</CollectionView.ItemTemplate>
</CollectionView>
Enforce binding warnings as errors
| Warning | Meaning |
|---|---|
| XC0022 | Binding used without x:DataType in scope — not compiled, falls back to reflection |
| XC0023 | Binding not compiled because x:DataType is explicitly null |
| XC0024 | x:DataType came from an outer scope — annotate the DataTemplate with its own x:DataType |
| XC0025 | Binding not compiled because it has an explicit Source — enable <MauiEnableXamlCBindingWithSourceCompilation> |
阅读完整来源 ↗These four codes are verified against .NET 10 / .NET 11 MAUI (
Build.Tasks/BuildException.cs, `ErrorMessages.resx