Kompilierte Bindungen

Durchsuchen Sie das Beispiel

Datenbindungen für .NET Multi-platform App UI (.NET MAUI) weisen zwei Hauptprobleme auf.

1. Es gibt keine Validierung von Bindungsausdrücken während der Kompilierzeit. Stattdessen werden Bindungen zur Laufzeit aufgelöst. Daher werden ungültige Bindungen erst zur Laufzeit ermittelt, wenn die Anwendung nicht erwartungsgemäß funktioniert oder Fehlermeldungen angezeigt werden.
2. Sie sind nicht kosteneffizient. Bindungen werden zur Laufzeit mithilfe universeller Objektsinspektion (Reflexion) aufgelöst, und der entstehende Overhead variiert von Plattform zu Plattform.

Kompilierte Bindungen verbessern die Datenbindungsleistung in .NET MAUI-Anwendungen, indem die Bindungsausdrücke zur Kompilierzeit anstatt zur Laufzeit aufgelöst werden. Darüber hinaus vereinfacht die Validierung von Bindungsausdrücken zur Kompilierzeit die Problembehandlung durch den Entwickler, da ungültige Bindungen als Buildfehler gemeldet werden.

Kompilierte Bindungen in XAML

Um kompilierte XAML-Bindungen zu verwenden, setzen Sie ein x:DataType-Attribut auf einem VisualElement auf den Typ des Objekts, an das das VisualElement und untergeordnete Elemente gebunden werden sollen. Es wird empfohlen, das x:DataType-Attribut auf der gleichen Ebene in der Ansichtshierarchie festzulegen, auf der die BindingContext-Eigenschaft festgelegt ist. Dieses Attribut kann jedoch an jeder Position in einer Ansichtshierarchie neu definiert werden.

Um kompilierte Bindungen in XAML zu verwenden, muss das x:DataType-Attribut auf eine Zeichenfolge oder einen Typ mit der x:Type-Markuperweiterung festgelegt werden. Zur Kompilierzeit des XAML-Codes werden jegliche ungültige Bindungsausdrücke als Buildfehler gemeldet. Der XAML-Compiler meldet einen Buildfehler jedoch nur für den ungültigen Bindungsausdruck, der als erstes ermittelt wird. Alle gültigen Bindungsausdrücke, die im VisualElement-Element oder in dessen untergeordneten Elemente definiert sind, werden unabhängig davon, ob BindingContext in der XAML-Datei oder im Code festgelegt ist, kompiliert. Das Kompilieren eines Bindungsausdrucks generiert kompilierten Code, der einen Wert von einer Eigenschaft in der Quelle abruft und diesen für die Eigenschaft des Ziels festlegt, das im Markup angegeben ist. Je nach Bindungsausdruck kann der generierte Code Änderungen im Wert der Eigenschaft source beobachten und die Eigenschaft target aktualisieren. Änderungen können möglicherweise vom target zurück an die source übertragen werden.

<MauiStrictXamlCompilation>true</MauiStrictXamlCompilation>

Weitere Informationen zu Warnungen zu kompilierten XAML-Bindungen finden Sie unter Warnungen zu kompilierten XAML-Bindungen.

Verwenden kompilierter Bindungen in XAML

Das folgende Beispiel veranschaulicht die Verwendung kompilierter Bindungen zwischen .NET MAUI-Ansichten und Viewmodel-Eigenschaften:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:DataBindingDemos"
             x:Class="DataBindingDemos.CompiledColorSelectorPage"
             x:DataType="local:HslColorViewModel"
             Title="Compiled Color Selector">
    <ContentPage.BindingContext>
        <local:HslColorViewModel Color="Sienna" />
    </ContentPage.BindingContext>
    ...
    <StackLayout>
        <BoxView Color="{Binding Color}"
                 ... />
        <StackLayout Margin="10, 0">
            <Label Text="{Binding Name}" />
            <Slider Value="{Binding Hue}" />
            <Label Text="{Binding Hue, StringFormat='Hue = {0:F2}'}" />
            <Slider Value="{Binding Saturation}" />
            <Label Text="{Binding Saturation, StringFormat='Saturation = {0:F2}'}" />
            <Slider Value="{Binding Luminosity}" />
            <Label Text="{Binding Luminosity, StringFormat='Luminosity = {0:F2}'}" />
        </StackLayout>
    </StackLayout>    
</ContentPage>

Die ContentPage instanziiert die HslColorViewModel und initialisiert die Color Eigenschaft innerhalb von Eigenschaftselement-Tags für die BindingContext Eigenschaft. Dieses ContentPage definiert das x:DataType Attribut als ViewModel-Typ, wodurch alle Bindungsausdrücke in der ContentPage Ansichtshierarchie kompiliert werden. Dies können Sie überprüfen, indem Sie einen der Bindungsausdrücke so ändern, dass er an eine nicht vorhandene ViewModel-Eigenschaft gebunden wird. Dies führt zu einem Buildfehler. In diesem Beispiel wird das x:DataType-Attribut auf ein Zeichenfolgenliteral festgelegt. Sie können es jedoch auch auf einen Typ mit der Markuperweiterung x:Type festlegen. Weitere Informationen zur Markuperweiterung x:Type finden Sie unter x:Type-Markuperweiterung.

Die BoxView- und Label-Elemente sowie die Slider-Ansichten erben den Bindungskontext von ContentPage. Alle diese Ansichten sind Bindungsziele, die auf Quelleneigenschaften des ViewModels verweisen. Für die Eigenschaften BoxView.Color und Label.Text sind die Datenbindungen OneWay. Die Eigenschaften in der Ansicht werden über die Eigenschaften in der ViewModel-Klasse festgelegt. Die Eigenschaft Slider.Value verwendet jedoch eine TwoWay-Bindung. Dadurch kann jedes Slider-Element aus dem ViewModel gesetzt werden, und das ViewModel kann auch aus jedem Slider-Element gesetzt werden.

Bei der ersten Ausführung des Beispiels werden alle BoxView, Label und Slider Elemente durch das Viewmodel basierend auf der anfänglichen Color Eigenschaft gesetzt, die bei der Instanziierung des Viewmodels festgelegt wurde. Wenn die Schieberegler bewegt werden, werden die Elemente BoxView und Label entsprechend aktualisiert.

Weitere Informationen zu dieser Farbauswahl finden Sie unter Benachrichtigungen für Änderungen an ViewModels und Eigenschaften.

Verwenden von kompilierten XAML-Bindungen in einer DataTemplate

Bindungen in einer DataTemplate-Klasse werden abhängig vom Kontext des Objekts interpretiert, auf dem die Vorlage basiert. Daher muss die DataTemplate-Klasse den Typ ihres Datenobjekts mithilfe des DataTemplate-Attributs deklarieren, wenn kompilierte Bindungen in einer x:DataType-Klasse verwendet werden. Das Versäumnis, dies zu tun, könnte dazu führen, dass ein DataTemplate einen falschen x:DataType vom übergeordneten Bereich erbt:

<ContentPage ...
             x:DataType="local:AnimalsPageViewModel">
    <!-- Binding to AnimalsPageViewModel.Animals -->
    <CollectionView ItemsSource="{Binding Animals}">
        <CollectionView.ItemTemplate>
            <DataTemplate>
                <!-- incorrect: compiler thinks you want to bind to AnimalsPageViewModel.Name -->  
                <Label Text="{Binding Name}" />
            </DataTemplate>
        </CollectionView.ItemTemplate>
    </CollectionView>
</ContentPage>

Das folgende Beispiel veranschaulicht das ordnungsgemäße Festlegen der Einstellung x:DataType für ein DataTemplate:

<ContentPage ...
             x:DataType="local:AnimalsPageViewModel">
    <!-- Binding to AnimalsPageViewModel.Animals -->
    <CollectionView ItemsSource="{Binding Animals}">
        <CollectionView.ItemTemplate>
            <DataTemplate x:DataType="local:Animal">
                <!-- correct: compiler knows you want to bind to Animal.Name -->
                <Label Text="{Binding Name}" />
            </DataTemplate>
        </CollectionView.ItemTemplate>
    </CollectionView>
</ContentPage>

In diesem Beispiel wird das x:DataType-Attribut auf ein Zeichenfolgenliteral festgelegt. Sie können es jedoch auch auf einen Typ mit der Markuperweiterung x:Type festlegen. Weitere Informationen zur Markuperweiterung x:Type finden Sie unter x:Type-Markuperweiterung.

Kompilieren von Bindungen, die einen generischen Typ angeben

Generische Typen können mit dem attribut x:DataType angegeben werden, indem die generische Einschränkung als präfixiertes Zeichenfolgenargument in Klammern angegeben wird:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:MyMauiApp"
             x:Class="MyMauiApp.MyPage"
             x:DataType="local:MyViewModel(x:Boolean)">
    ...
</ContentPage>

Mehrere Typargumente können als präfixierte Zeichenfolgenargumente angegeben werden, die durch ein Komma getrennt werden:

<DataTemplate x:DataType="local:MyType(local:MyObject,x:Boolean)">
    ...
</DataTemplate>

Weitere Informationen zu Generischen in XAML finden Sie unter Generics.

<MauiEnableXamlCBindingWithSourceCompilation>true</MauiEnableXamlCBindingWithSourceCompilation>

<HorizontalStackLayout BindingContext="{x:Reference slider}" x:DataType="Slider">
    <Label Text="{Binding Value}" />
    <Label Text="{Binding Text, Source={x:Reference entry}, x:DataType=Entry}" />
</HorizontalStackLayout>

<Button Command="{Binding Source={RelativeSource AncestorType={x:Type local:PeopleViewModel}},
                          Path=DeleteEmployeeCommand}" />

Kombinieren von kompilierten und klassischen XAML-Bindungen

Bindungsausdrücke werden nur für die Ansichtshierarchie kompiliert, für die das Attribut x:DataType definiert ist. Im Gegensatz dazu, verwenden alle Ansichten in einer Hierarchie, für die das Attribut x:DataType nicht definiert ist, klassische Bindungen. Daher ist es möglich, kompilierte Bindungen und klassische Bindungen auf einer Seite zu kombinieren. Zum Beispiel verwenden die Ansichten innerhalb der DataTemplate im vorherigen Abschnitt kompilierte Bindungen, während BoxView, das auf die im ListView ausgewählte Farbe eingestellt ist, dies nicht tut.

Mithilfe sorgfältiger Strukturierung von x:DataType-Attributen kann deshalb eine Seite mit kompilierten und klassischen Bindungen erstellt werden. Alternativ kann das Attribut x:DataType jederzeit und an beliebiger Position in einer Ansichtshierarchie mithilfe der Markuperweiterung null als x:Null definiert werden. Dadurch wird impliziert, dass alle Bindungsausdrücke in der Ansichtshierarchie klassische Bindungen nutzen. Das folgende Beispiel veranschaulicht diesen Ansatz:

<StackLayout x:DataType="local:HslColorViewModel">
    <StackLayout.BindingContext>
        <local:HslColorViewModel Color="Sienna" />
    </StackLayout.BindingContext>
    <BoxView Color="{Binding Color}"
             VerticalOptions="Fill" />
    <StackLayout x:DataType="{x:Null}"
                 Margin="10, 0">
        <Label Text="{Binding Name}" />
        <Slider Value="{Binding Hue}" />
        <Label Text="{Binding Hue, StringFormat='Hue = {0:F2}'}" />
        <Slider Value="{Binding Saturation}" />
        <Label Text="{Binding Saturation, StringFormat='Saturation = {0:F2}'}" />
        <Slider Value="{Binding Luminosity}" />
        <Label Text="{Binding Luminosity, StringFormat='Luminosity = {0:F2}'}" />
    </StackLayout>
</StackLayout>   

Der StackLayout-Stamm legt den Typ x:DataType für das Attribut HslColorViewModel fest, d.h., dass alle Bindungsausdrücke im StackLayout-Stamm der Ansichtshierarchie kompiliert werden. Das innere StackLayout definiert das x:DataType-Attribut mit dem null-Markupausdruck zu x:Null um. Daher verwenden Bindungsausdrücke in der inneren StackLayout-Klasse klassische Bindungen. Nur die BoxView-Klasse im StackLayout-Stamm der Ansichtshierarchie verwendet kompilierte Bindungen.

Weitere Informationen über den Markup-Ausdruck x:Null finden Sie unter x:Null-Markuperweiterung.

Warnungen zu kompilierten XAML-Bindungen

In der folgenden Tabelle sind die Compilerwarnungen für kompilierte Bindungen und deren Behebung aufgeführt:

Um sicherzustellen, dass diese Warnungen nicht ignoriert werden, sollten Sie bestimmte Warnungen in Fehler umwandeln, indem Sie die $(WarningsAsErrors)-Buildeigenschaft ändern.

<WarningsAsErrors>$(WarningsAsErrors);XC0022;XC0023</WarningsAsErrors>

Verwenden Sie die $(NoWarn) Buildeigenschaft mit bestimmten Warnungscodes, um diese Warnungen zu ignorieren:

<NoWarn>$(NoWarn);XC0022;XC0023</NoWarn>

Wenn Sie die Buildeigenschaft $(TreatWarningsAsErrors) in der true Projektdatei Ihrer App festlegen, bestimmte XAML-Compilerwarnungen jedoch ignorieren möchten, verwenden Sie entweder die $(NoWarn) Buildeigenschaft, um diese Warnungen oder die $(WarningsNotAsErrors) Buildeigenschaft zu stillen, um den Schweregrad einiger bestimmter Codes zu verringern.

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<MauiStrictXamlCompilation>true</MauiStrictXamlCompilation>

MyLabel.SetBinding(Label.TextProperty, static (Entry entry) => entry.Text);

// Valid: Property access
static (PersonViewModel vm) => vm.Name;
static (PersonViewModel vm) => vm.Address?.Street;

// Valid: Array and indexer access
static (PersonViewModel vm) => vm.PhoneNumbers[0];
static (PersonViewModel vm) => vm.Config["Font"];

// Valid: Casts
static (Label label) => (label.BindingContext as PersonViewModel).Name;
static (Label label) => ((PersonViewModel)label.BindingContext).Name;

// Invalid: Method calls
static (PersonViewModel vm) => vm.GetAddress();
static (PersonViewModel vm) => vm.Address?.ToString();

// Invalid: Complex expressions
static (PersonViewModel vm) => vm.Address?.Street + " " + vm.Address?.City;
static (PersonViewModel vm) => $"Name: {vm.Name}";

myEntry.SetBinding(Entry.TextProperty, new MultiBinding
{
    Bindings = new Collection<BindingBase>
    {
        Binding.Create(static (Entry entry) => entry.FontFamily, source: RelativeBindingSource.Self),
        Binding.Create(static (Entry entry) => entry.FontSize, source: RelativeBindingSource.Self),
        Binding.Create(static (Entry entry) => entry.FontAttributes, source: RelativeBindingSource.Self),
    },
    Converter = new StringConcatenationConverter()
});

Leistung

Kompilierte Bindungen verbessern die Leistung der Datenbindung mit variierenden Leistungsvorteilen.

• Eine kompilierte Bindung, die eine Eigenschaftsänderungsbenachrichtigung verwendet (z.B. eine OneWay-, OneWayToSource- oder TwoWay-Bindung), wird ungefähr achtmal so schnell wie eine klassische Bindung aufgelöst.
• Eine kompilierte Bindung, die keine Eigenschaftsänderungsbenachrichtigung verwendet (z.B. eine OneTime-Bindung) wird ungefähr 20-mal so schnell wie eine klassische Bindung aufgelöst.
• Das Festlegen der BindingContext bei einer kompilierten Bindung, die die Benachrichtigung über Eigenschaftsänderungen verwendet (z.B. eine OneWay-, OneWayToSource- oder TwoWay-Bindung), erfolgt etwa fünfmal schneller als das Festlegen der BindingContext bei einer klassischen Bindung.
• Das Festlegen der BindingContext-Eigenschaft bei einer kompilierten Bindung, die keine Eigenschaftenänderungsbenachrichtigung verwendet (z.B. eine OneTime-Bindung), ist etwa siebenmal schneller als das Festlegen der BindingContext-Eigenschaft bei einer klassischen Bindung.

Diese Leistungsunterschiede können bei mobilen Geräten abhängig von der verwendeten Plattform, der Version des verwendeten Betriebssystems und dem Gerät, auf dem die Anwendung ausgeführt wird, gesteigert werden.

Häufige Fehler

X:DataType="x:Object" vermeiden

Ein häufiger Fehler beim Migrieren von Xamarin.Forms oder beim Versuch, eine Compilerwarnung schnell zu unterdrücken, besteht darin, für ein Element festzulegen x:DataType="x:Object" :

<!-- Anti-pattern: silently disables compiled bindings -->
<StackLayout x:DataType="x:Object">
    <Label Text="{Binding Name}" />
</StackLayout>

<!-- Correct: set x:DataType to the actual binding context type -->
<StackLayout x:DataType="viewmodels:PersonViewModel">
    <Label Text="{Binding Name}" />
</StackLayout>

Behandle XC0022 und XC0025 als Fehler in CI

Anstatt XC0022- und XC0025-Warnungen zu silencieren, behandeln Sie sie als Fehler in Ihrer CI-Pipeline, um falsch konfigurierte kompilierte Bindungen abzufangen, bevor sie die Produktion erreichen:

<WarningsAsErrors>$(WarningsAsErrors);XC0022;XC0023;XC0025</WarningsAsErrors>

Das Silencieren dieser Warnungen mit $(NoWarn) oder x:DataType="x:Object" blendet Bindungskonfigurationsfehler aus und entfernt die Leistungsvorteile von kompilierten Bindungen.