.NET MAUI Community Toolkit v10.0: How to Fix BindingContext Issues with Behaviors

Yesterday marked the official release of the highly anticipated .NET MAUI Toolkit (CommunityToolkit.Maui) package v10.0, introducing native support for .NET 9.

Though it is the extended arm of .NET MAUI app development, for newcomers, this officially supported toolkit offers a comprehensive collection of essential components—such as Alerts, Behaviors, Converters, Extensions, Layouts, and Views—that are crucial for developing real-world apps.

This new release has some breaking changes, with the most notable being aligning with the design change introduced in .NET MAUI 9, where Behaviors no longer automatically inherit the BindingContext of their parent (a major shift from the original Xamarin.Forms design).

Please note that this new version of the Toolkit is exclusive to .NET MAUI 9 and is NOT compatible with .NET MAUI 8. Refer to the release notes for complete details.

Quoting from official documentation:

.NET MAUI does not set the BindingContext of a behavior, because behaviors can be shared and applied to multiple controls through styles.

This v10.0 release of the toolkit is now fully aligned with this change by no longer automatically assigning the value for the Behavior.BindingContext property.

What’s the Impact:

If your app uses Toolkit’s Behaviors and follows the MVVM architecture (which operates by defining Bindings), all those bound Data and Commands will not function after this v10.0 upgrade unless addressed.

Solution:

If a Behavior possesses a Binding, the BindingContext must be manually assigned to it.

For insights into the practical use of Behaviors, this article on EventToCommandBehavior is highly recommended. I’m going to take the sample from that article, highlight the issue, and apply the solution.

<ContentPage
    x:Class="MyApp.Views.MainPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:c="clr-namespace:MyApp.Converters"
    xmlns:mct="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
    xmlns:vm="clr-namespace:MyApp.ViewModels"
    x:DataType="vm:MainViewModel">
    <ContentPage.Resources>
        <c:HybridWebViewRawMessageReceivedEventArgsConverter x:Key="ArgsConverter" />
    </ContentPage.Resources>
    <HybridWebView x:Name="hwv">
        <HybridWebView.Behaviors>
            <mct:EventToCommandBehavior
                Command="{Binding ShowMessageCommand}"
                EventArgsConverter="{StaticResource ArgsConverter}"
                EventName="RawMessageReceived" />
        </HybridWebView.Behaviors>
    </HybridWebView>
</ContentPage>

HybridWebView:

This is a new control released in .NET MAUI 9 for developing JavaScript-based Hybrid Apps. Consult this Exploring HybridWebView article to delve into the details.

To know more about what’s new in .NET MAUI 9, refer to this Comprehensive Overview article.

Basics:

On a brief note, the EventToCommandBehavior serves to translate the UI event into an MVVM command, thereby ensuring that the View (UI) and the ViewModel (logic) remain decoupled. This approach exemplifies the principle of Separation of Concerns.

Optionally, Converters help to add logic by parsing the EventArgs object and passing them as parameters to the Command (method).

So, these three properties must be managed: the UI Event, the Command, and the optional CommandParameter or EventArgsConverter.

Working:

• Upon receiving a message, the HybridWebView control triggers the RawMessageReceived event to indicate the state change.
• A Command method is articulated within the ViewModel to manage the corresponding logic.
• The Converter extracts the value from the EventArgs and passes it as a parameter to this method.

Issue:

The BindingContext is the object that references this Command method.

In .NET MAUI, the value of the BindingContext property is typically set at the page level. This value propagates hierarchically throughout the various controls. As it is defined within the BindableObject, the foundational type, all derived types have access to it.

Now the propagation of BindingContext from UI control to the associated Behavior is no longer automatic. The command associated with the behavior cannot be resolved, failing to invoke it.

Solution:

Manually assign the BindingContext.

For clarity, only the HybridWebView section from the sample.

<HybridWebView x:Name="hwv">
    <HybridWebView.Behaviors>
        <mct:EventToCommandBehavior
            BindingContext="{Binding BindingContext, Source={x:Reference hwv}, x:DataType=HybridWebView}"
            Command="{Binding ShowMessageCommand}"
            EventArgsConverter="{StaticResource ArgsConverter}"
            EventName="RawMessageReceived" />
    </HybridWebView.Behaviors>
</HybridWebView>

Binding:

A Binding is a connection between a Source property and a Target property.

At times, both the Source and Target properties of the Binding can be related to the UI as well.

Behaviors also inherit from the BindableObject base type, thereby them access to the BindingContext property.

To propagate the value, a Binding is defined between the HybridWebView control’s BindingContext (Source property) and the EventToCommandBehavior’s BindingContext (Target property).

Although the properties involved in the Binding have been specified, to establish the Source object, the HybridWebView is explicitly named and used as the reference binding source.

Lastly, since the BindingContext property is of type object, set the x:DataType to the type name of the Source control for the XAML compiler to cast its value correctly. If it’s not defined in the root namespace (MAUI controls), then the XAML namespace prefix is necessary.

Conclusion:

In my scenario, for a different purpose, I have already named the UI control. However, if your app has multiple Behaviors defined at various levels, verify whether they will work with the value set as the root BindingContext. If so, define a name for the page and set the relative binding source to that page name and x:DataType to the page type name (with namespace prefix), thereby minimizing the naming of controls. Pay close attention to the Behaviors defined within Templates.

A working sample is made available in this GitHub repository.

Happy coding. Stay connected as we continue to learn and share the experiences from this exciting journey of being a .NET developer.