跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
视频与音频

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:DataType compiled bindings to a new or existing page
  • Implementing INotifyPropertyChanged or CommunityToolkit ObservableObject
  • Creating or consuming IValueConverter / IMultiValueConverter
  • Choosing the correct BindingMode for a control property
  • Setting BindingContext in XAML or code-behind
  • Using relative bindings (Self, AncestorType, TemplatedParent)
  • Applying StringFormat, FallbackValue, or TargetNullValue
  • Writing AOT-safe code bindings with SetBinding and lambdas (.NET 9+)

When Not to Use

  • CollectionView layouts / templates — use the maui-collectionview skill
  • Shell navigation parameters — use the maui-shell-navigation skill
  • Service registration / DI — use the maui-dependency-injection skill
  • 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".

SituationDo thisNot this
Deciding where x:DataType goesPut it wherever a binding scope starts — the page/view root, and each DataTemplateScattering 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:DataTypeLeaving it to resolve against the wrong type
ViewModel change notificationObservableObject + [ObservableProperty], or implement INotifyPropertyChangedA plain POCO base class — bindings will never update
Bindings show blankCheck BindingContext is actually setAssuming the binding path is wrong
Enforcing compiled bindingsSet 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:

  1. Page / View root — where you assign BindingContext.
  2. 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

WarningMeaning
XC0022Binding used without x:DataType in scope — not compiled, falls back to reflection
XC0023Binding not compiled because x:DataType is explicitly null
XC0024x:DataType came from an outer scope — annotate the DataTemplate with its own x:DataType
XC0025Binding 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

阅读完整来源 ↗