Liaisons compilées

Parcourir l'exemple

Les liaisons de données .NET Multi-platform App UI (.NET MAUI) présentent deux problèmes principaux :

1. Aucune validation des expressions de liaison n’a lieu au moment de la compilation. À la place, les liaisons sont résolues au moment de l’exécution. Par conséquent, les liaisons non valides ne sont pas détectées avant l’exécution, lorsque l’application ne se comporte pas comme prévu ou que des messages d’erreur apparaissent.
2. Elles ne sont pas rentables. Les liaisons sont résolues au moment de l’exécution via l’inspection (réflexion) des objets à usage général et la surcharge de cette opération varie d’une plateforme à l’autre.

Les liaisons compilées améliorent les performances de liaison de données dans les applications .NET MAUI en résolvant les expressions de liaison au moment de la compilation plutôt qu’au moment du runtime. En outre, cette validation des expressions de liaison au moment de la compilation favorise une meilleure expérience de dépannage pour les développeurs, car les liaisons non valides sont signalées comme erreurs de build.

Liaisons compilées dans XAML

Pour utiliser des liaisons compilées, définissez un attribut x:DataType sur un VisualElement avec le type d’objet auquel le VisualElement et ses enfants seront liés. Il est recommandé de définir l’attribut x:DataType dans la hiérarchie d’affichage au niveau où BindingContext est défini. Cependant, cet attribut peut être redéfini à tout emplacement dans une hiérarchie d’affichage.

Pour utiliser des liaisons compilées dans XAML, l’attribut x:DataType doit être défini sur un littéral de chaîne ou un type à l’aide de l’extension de balisage x:Type. Au moment de la compilation XAML, toutes les expressions de liaison non valides seront signalées comme erreurs de build. Toutefois, le compilateur XAML signalera uniquement une erreur de build pour la première expression de liaison non valide qu’il rencontrera. Toutes les expressions de liaison valides qui sont définies sur l’objet VisualElement ou ses enfants seront compilées, que BindingContext soit défini en XAML ou dans le code. La compilation d’une expression de liaison génère du code compilé qui obtiendra une valeur d’une propriété de la source et la définira sur la propriété de la cible spécifiée dans le balisage. En outre, en fonction de l’expression de liaison, le code généré peut observer des modifications dans la valeur de la propriété source et actualiser la propriété cible, et il peut renvoyer (push) des modifications à partir de la cible vers la source.

<MauiStrictXamlCompilation>true</MauiStrictXamlCompilation>

Pour plus d’informations sur les avertissements de liaisons compilées XAML, consultez les avertissements des liaisons compilées XAML.

Utiliser des liaisons compilées dans XAML

L’exemple suivant illustre l’utilisation de liaisons compilées entre les vues .NET MAUI et les propriétés de viewmodel :

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

Le ContentPage instancie le HslColorViewModel et initialise la propriété Color dans les balises d’élément de propriété pour la propriété BindingContext. Le ContentPage définit également l’attribut de x:DataType en tant que type de viewmodel, ce qui indique que toutes les expressions de liaison figurant dans la hiérarchie d’affichage ContentPage seront compilées. Cela peut être vérifié en modifiant l’une des expressions de liaison pour la lier à une propriété de viewmodel inexistante, ce qui entraînera une erreur de build. Bien que cet exemple définisse l’attribut x:DataType comme un littéral de chaîne, il peut également être défini comme un type à l’aide de l’extension de balisage x:Type. Pour plus d’informations sur l’extension de balisage x:Type, consultez la section x:Type Markup Extension.

Les éléments BoxView, Label et les vues Slider héritent du contexte de liaison de ContentPage. Ces vues sont toutes des cibles de liaison qui référencent les propriétés sources dans le viewmodel. Pour la propriété BoxView.Color et la propriété Label.Text, les liaisons de données sont OneWay - les propriétés dans la vue sont définies à partir des propriétés dans le viewmodel. Toutefois, la propriété Slider.Value utilise une liaison TwoWay. Cela permet à chaque Slider d’être défini à partir du viewmodel, et également au viewmodel d’être défini à partir de chaque Slider.

À la première exécution de l’application, les éléments BoxView, Label et Slider sont tous définis à partir du viewmodel basé sur la propriété de Color initiale définie lorsque le viewmodel a été instancié. Les éléments BoxView et Label sont mis à jour au fur et à mesure de la manipulation des curseurs :

Pour plus d’informations sur ce sélecteur de couleur, consultez la section ViewModels et notifications de changement de propriété.

Utiliser des liaisons compilées dans XAML dans un DataTemplate

Les liaisons figurant dans un DataTemplate sont interprétées dans le contexte de l’objet basé sur le modèle. Par conséquent, lorsque vous utilisez des liaisons compilées dans un DataTemplate, le DataTemplate doit déclarer le type de son objet de données à l’aide de l’attribut x:DataType. L’échec de cette opération peut entraîner l’héritage DataTemplate d’une erreur x:DataType à partir de son étendue parente :

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

L’exemple suivant illustre la définition correcte de l’élément x:DataType sur un DataTemplate:

<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.CompiledColorListPage"
             Title="Compiled Color List">
    <Grid>
        ...
        <ListView x:Name="colorListView"
                  ItemsSource="{x:Static local:NamedColor.All}"
                  ... >
            <ListView.ItemTemplate>
                <DataTemplate x:DataType="local:NamedColor">
                    <ViewCell>
                        <StackLayout Orientation="Horizontal">
                            <BoxView Color="{Binding Color}"
                                     ... />
                            <Label Text="{Binding FriendlyName}"
                                   ... />
                        </StackLayout>
                    </ViewCell>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
        <!-- The BoxView doesn't use compiled bindings -->
        <BoxView Color="{Binding Source={x:Reference colorListView}, Path=SelectedItem.Color}"
                 ... />
    </Grid>
</ContentPage>

La propriété ListView.ItemsSource est définie sur la propriété NamedColor.All statique. La classe NamedColor utilise la réflexion .NET pour énumérer tous les champs publics statiques de la classe Colors et les stocker avec leurs noms dans une collection accessible à partir de la propriété statique All. Par conséquent, l’objet ListView est rempli avec toutes les instances de NamedColor. Pour chaque élément figurant dans ListView, le contexte de liaison de l’élément est défini sur un objet NamedColor. Les éléments BoxView et Label dans l’objet ViewCell sont liés aux propriétés de NamedColor.

Notez que le DataTemplate définit l’attribut x:DataType en tant que type de NamedColor, ce qui indique que toutes les expressions de liaison figurant dans la hiérarchie d’affichage DataTemplate seront compilées. Cela peut être vérifié en modifiant les expressions de liaison à lier à une propriété de NamedColor inexistante, ce qui entraînera une erreur de build. Bien que cet exemple définisse l’attribut x:DataType comme un littéral de chaîne, il peut également être défini comme un type à l’aide de l’extension de balisage x:Type. Pour plus d’informations sur l’extension de balisage x:Type, consultez la section x:Type Markup Extension.

Lorsque l’exemple est exécuté pour la première fois, la ListView est remplie avec des instances NamedColor. Lorsqu’un élément dans ListView est sélectionné, la propriété BoxView.Color est définie sur la couleur de l’élément sélectionné dans ListView :

La sélection d’autres éléments dans l’objet ListView met à jour la couleur de l’objet BoxView.

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

Combiner des liaisons compilées avec des liaisons classiques dans XAML

Les expressions de liaison sont compilées uniquement pour la hiérarchie d’affichage sur laquelle l’attribut x:DataType est défini. À l’inverse, toutes les vues dans une hiérarchie sur laquelle l’attribut x:DataType n’est pas défini utiliseront des liaisons classiques. Par conséquent, il est possible de combiner des liaisons compilées et classiques sur une page. Par exemple, dans la section précédente, les vues figurant dans le DataTemplate utilisent des liaisons compilées, alors que ce n’est pas le cas du BoxView qui est défini sur la couleur sélectionnée dans l’objet ListView.

La structuration prudente des attributs x:DataType permet ainsi d’obtenir une page utilisant des liaisons compilées et classiques. Vous pouvez également redéfinir l’attribut x:DataType à tout moment dans une hiérarchie d’affichage sur null à l’aide de l’extension de balisage x:Null. Cela indique que toutes les expressions de liaison figurant dans la hiérarchie d’affichage utiliseront des liaisons classiques. L’exemple suivant illustre cette approche :

<StackLayout x:DataType="local:HslColorViewModel">
    <StackLayout.BindingContext>
        <local:HslColorViewModel Color="Sienna" />
    </StackLayout.BindingContext>
    <BoxView Color="{Binding Color}"
             VerticalOptions="FillAndExpand" />
    <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>   

Le StackLayout racine définit l’attribut x:DataType en tant que type HslColorViewModel, ce qui indique que toutes les expressions de liaison figurant dans la hiérarchie d’affichage StackLayout racine seront compilées. Toutefois, le StackLayout interne redéfinit l’attribut x:DataType sur null avec l’expression de balisage x:Null. Par conséquent, les expressions de liaison figurant dans le StackLayout interne utilisent des liaisons classiques. Seul l’objet BoxView, au sein de la hiérarchie d’affichage StackLayout racine, utilise des liaisons compilées.

Pour plus d'informations sur l’expression de balisage x:Null, consultez Extension de balisage x:Null.

Avertissements des liaisons compilées XAML

Le tableau suivant répertorie les avertissements du compilateur pour les liaisons compilées et comment les résoudre :

Pour vous assurer que ces avertissements ne sont pas ignorés, envisagez de modifier des avertissements spécifiques pour générer des erreurs avec la propriété de $(WarningsAsErrors) build :

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

Pour ignorer ces avertissements, utilisez la $(NoWarn) propriété de build avec des codes d’avertissement spécifiques :

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

Si vous définissez la $(TreatWarningsAsErrors) propriété true de build sur le fichier projet de votre application, mais que vous souhaitez ignorer certains avertissements du compilateur XAML, utilisez la $(NoWarn) propriété de build pour réduire ces avertissements ou la $(WarningsNotAsErrors) propriété de build pour réduire la gravité de certains codes spécifiques.

<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()
});

Performances

Les liaisons compilées améliorent les performances des liaisons de données, avec des avantages variables :

• Une liaison compilée qui utilise la notification de modification de propriété (c'est-à-dire une liaison OneWay, OneWayToSource ou TwoWay) est résolue environ 8 fois plus vite qu’une liaison classique.
• Une liaison compilée qui n’utilise pas la notification de modification de propriété (c'est-à-dire une liaison OneTime) est résolue environ 20 fois plus vite qu’une liaison classique.
• La définition du BindingContext sur une liaison compilée qui utilise la notification de modification de propriété (c'est-à-dire une liaison OneWay, OneWayToSource ou TwoWay) est environ 5 fois plus rapide que la définition du BindingContext sur une liaison classique.
• La définition du BindingContext sur une liaison compilée qui n’utilise pas la notification de modification de propriété (c'est-à-dire une liaison OneTime) est environ 7 fois plus rapide que la définition du BindingContext sur une liaison classique.

Ces différences de performances peuvent être accrues sur les appareils mobiles, selon la plateforme utilisée, la version du système d’exploitation utilisé et l’appareil sur lequel l’application s’exécute.