In .NET MAUI, we sometimes face the situation that we would like to evaluate a specific value, e.g. a property from a child object, against some logic from the ViewModel. I personally sometimes wish it were possible to bind directly to a method and pass a value to it so that I can decide how to display the value in the UI.

Normally, I would use a trigger when it comes to simply checking whether a property has a certain value and then update the UI accordingly. But, what if the evaluation isn’t as simple as checking for a specific value? What if we want to use a range of values or apply some more complex logic?

One thing that I would like to avoid when using the MVVM pattern is moving business logic to data objects or even into the UI layer, because that’s usually not where it belongs. I want my business logic to be separate from data and UI layers and I would like it to be unit testable, so having evaluation functions for objects or arguments is desired.

In this blog post I’ll demonstrate how we can use a trick in order to bind to functions from XAML by leveraging the capabilities of data triggers, multi-bindings, multi-value converters and function delegates.

As always, I’ve added the code used here to my MAUI Samples repository, so that you can follow along.

The Goal

The idea is to check whether the Count property of type int of the already existing BindingItem class is a prime number, and if it is, display the row the object resides in in a different color, in our case light green, without modifying the data class:

public class BindingItem
{
    public string Name { get; set; }
    public int Count { get; set; }
}

Currently, adding items simply displays a new row with the Count value for the new item:

However, we would like to highlight all rows that contain a prime number, like so:

Things like this can usually be done using triggers. Let’s have a look.

Data Triggers

A data trigger uses a binding expression and a value to compare the property against and then applies a setter to update a specified set of visual properties of a control, like the background color:

<Label>
  <Label.Triggers>
    <DataTrigger
      TargetType="Label"
      Binding="{Binding Count}"
      Value="3">
      <Setter Property="BackgroundColor" Value="LightGreen" />
    </DataTrigger>
  </Label.Triggers>
</Label>

The flaw of this approach is that we would need to know the value that we want to evaluate against for each item beforehand, but we don’t. In order to check whether an integer is actually a prime number requires applying some logic, which we usually cannot directly do using a data trigger, and, as mentioned above, this logic doesn’t belong into the data layer.

However, we can still make use of a data trigger to accomplish what we want, if we combine this with a converter that evaluates to true or false based on an evaluation function for the given property:

<ContentPage.Resources>
  <converters:PrimeNumberToBoolConverter x:Key="IsPrimeConverter" />
</ContentPage.Resources>

<Label>
  <Label.Triggers>
    <DataTrigger
      TargetType="Label"
      Binding="{Binding Count, Converter={StaticResource IsPrimeConverter}}"
      Value="True">
      <Setter Property="BackgroundColor" Value="LightGreen" />
    </DataTrigger>
  </Label.Triggers>
</Label>

We could implement a simple IValueConverter that contains the logic for checking for prime numbers, but this would potentially mean moving logic into a converter, which is not desirable in most scenarios, because we may want to apply some business logic from the ViewModel, as well. So, this logic doesn’t belong into the UI layer, either.

💡 Yet, we can create a generalized converter that allows us to bind to a function delegate, which can then execute any kind of business logic from the ViewModel. This is exciting, let’s have a look.

FuncValueToBoolConverter

The heart of our desired functionality is the FuncValueToBoolConverter which is an IMultiValueConverter implementation.

In our case it only takes two values: The first one is a function delegate of type Func<object, bool>, and the second value is an object which serves as the argument to be be passed to the function delegate:

public sealed class FuncValueToBoolConverter : IMultiValueConverter
{
    public object Convert(object[] values, Type targetType, object parameter, CultureInfo culture)
    {
        if (values[0] is Func<object, bool> func)
        {
            return func(values[1]);
        }

        return false;
    }

    public object[] ConvertBack(object value, Type[] targetTypes, object parameter, CultureInfo culture)
    {
        return [];
    }
}

This converter is a general-purpose multi-value converter. Its purpose is to take a function delegate that can evaluate an object based on some business logic and either returns true or false.

In our case, we will use a method from the BindingsViewModel class, which we don’t have yet.

Prime number function

Let’s add a method which checks whether a number is prime to the ViewModel:

public partial class BindingsViewModel : ObservableObject
{ 
    private static bool IsPrime(object number)
    {
        if (number is not int intNumber || intNumber < 2)
        {
            return false;
        }

        for (var i = 2; i <= Math.Sqrt(intNumber); i++)
        {
            if (intNumber % i == 0)
            {
                return false;
            }
        }

        return true;
    }
}

Note: The IsPrime() method takes in an argument of type object, because that way, the FuncValueToBoolConverter can be reused in different contexts. We could also create a FuncIntToBoolConverter or similar in order to avoid boxing the integer.

⁉️ But wait, we cannot bind to methods, and, apart from that, this static method is private. Fortunately, C# allows us to expose this method as a public function delegate auto-property (which means that we can use it in a binding expression):

public partial class BindingsViewModel : ObservableObject
{
    // expose the IsPrime() function as a delegate,
    // note that this property must not be static
    public Func<object, bool> IsPrimeFunc => IsPrime;

    private static bool IsPrime(object number)
    {
        // see above
    }
}

Time to put it all together and make the magic happen. 🪄

Putting it together

In our page, we first add the FuncValueToBoolConverter as a static resource:

  <ContentPage.Resources>
    <converters:FuncValueToBoolConverter x:Key="FuncValueToBoolConverter" />
  </ContentPage.Resources>

Then, we can apply the converter together with a data trigger inside the DataTemplate of a CollectionView:

<CollectionView ItemsSource="{Binding Items}">
  <CollectionView.ItemTemplate>
    <DataTemplate x:DataType="models:BindingItem">
      <Grid
        Padding="8"
        ColumnDefinitions="*,*">
        <!-- skipping irrelevant parts for brevity -->
        <Grid.Triggers>

          <DataTrigger TargetType="Grid" Value="True">
            <DataTrigger.Binding>
              <MultiBinding Converter="{StaticResource FuncValueToBoolConverter}">
                <Binding
                  Path="IsPrimeFunc"
                  Source="{RelativeSource AncestorType={x:Type viewModels:BindingsViewModel}}" />
                <Binding Path="Count" />
              </MultiBinding>
            </DataTrigger.Binding>
            <DataTrigger.Setters>
              <Setter Property="BackgroundColor" Value="LightGreen" />
            </DataTrigger.Setters>
          </DataTrigger>

        </Grid.Triggers>
      </Grid>
    </DataTemplate>
  </CollectionView.ItemTemplate>
</CollectionView>

Note the two separate bindings in the multi-binding. The first one must be pointing to the IsPrimeFunc property of the ViewModel (using a relative binding) and the second one binds to the Count property of the current item.

Running the app now, we will be greeted with green rows for every prime number when adding new items to the collection:

🤩 Isn’t this awesome? We managed to bind to a function to apply complex logic within a data binding context. I’m very happy with the result.

You might be asking yourself whether this will also work with objects that have observable properties that frequently can change. The answer is: Yes, absolutely. Multi-bindings are evaluated everytime one of the properties of the child bindings changes, as long as it’s an observable property.

Conclusions and next steps

I’ve demonstrated how we can take advantage of MAUI’s built-in capabilities in order to bind to a ViewModel method. We’ve done this by exposing it as a function delegate property and then using it in the context of a multi-binding expression together with a multi-value converter that executes the method for us. This let’s us evaluate values of data objects without having to add logic to the data class and without having to add critical business logic to converters.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts and developments. And remember that sharing is caring.

Have you ever come across two (or more) products that looked almost exactly the same and only differed in things like color and the company logo printed on them? This is a common practice called white labeling where one company develops a product and then rebrands it for other companies to sell it under their own brand. A lot of products you can find in popular online shops are actually white-labeled.

So, let me rephrase my initial question: Have you ever come across two (or more) apps that looked almost exactly the same and only differed in things like color and the company logo on them? What you saw might indeed have been the same app just with a different icon, different images and different colors but based on exactly the same code base.

This blog post is my contribution to Matt Goldman's MAUI UI July 2024. Check it out, there are many great blog posts about .NET MAUI to be found there.

Today, I will show you how you can develop a single .NET MAUI app and easily rebrand it for different clients that share the same (or very similar) requirements. We'll see an example setup for two clients: ClientA and ClientB, as well as an unbranded "default" version of the app. We'll cover client-specific logos, images, colors, styles, app names and identifiers, as well as fonts, and also quickly touch on custom behavior.

The goal is achieve two or three differently styled apps with the same code base under the hood:

Disclaimer: This blog post can only serve as a starting point, because this topic is too large to cover all aspects in a single write-up. For example, customer-specific resource files (for strings and translations) are a topic that might be addressed in a follow-up post. I do not guarantee that the concepts presented here will work for every scenario. There are various different ways to achieve white labeling and this is just one of many approaches.

As always, there is a companion repository where you can find the full source code for this blog post (and more). To quote a popular YouTuber: "it is enough talking, so let's do it!"

Project Setup

First, let's look at the project structure that we'll work with. A new MAUI single project app created using one of the available templates will usually result in a project structure that looks similar to this:

Things like the app identifier, app name, app icon, images, fonts, etc. are all defined or referenced in the SDK-style project (.csproj) file of a MAUI app project. This is typically done between <PropertyGroup> and <ItemGroup> tags:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- Display name -->
    <ApplicationTitle>MauiSamples</ApplicationTitle>
    <!-- App Identifier -->
    <ApplicationId>com.companyname.mauisamples</ApplicationId>
  </PropertyGroup>
  <ItemGroup>
    <!-- App Icon -->
    <MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" Color="#512BD4"/>
    <!-- Splash Screen -->
    <MauiSplashScreen Include="Resources\Splash\splash.svg" Color="#512BD4" BaseSize="128,128"/>
    <!-- Images -->
    <MauiImage Include="Resources\Images\*"/>
    <!-- Custom Fonts -->
    <MauiFont Include="Resources\Fonts\*"/>
    <!-- Raw Assets (also remove the "Resources\Raw" prefix) -->
    <MauiAsset Include="Resources\Raw\**" LogicalName="%(RecursiveDir)%(Filename)%(Extension)"/>
  </ItemGroup>
</Project>

Note: To keep things simple, I'm only showing relevant bits of the .csproj file

This structure assumes that there's ever only a single source of truth when it comes to icons, images, styles and so on, which in this context usually is the Resources folder. For single-client apps, this is perfect, but for white labeling this let's us face a couple of problems. For example, how would we replace the app icons or fonts for each client?

We can work with this, but we need to make some changes, that I will describe in the following paragraphs.

Resources Structure

For white labeling, I suggest using a slightly altered project structure with an additional level of subfolders right under Resources with the usual folders for icons, fonts, images and so on separated by client:

The main benefit of this structure is that we can keep all the client-specific assets separate without losing the logical grouping we're used to from other MAUI apps.

Now, this will not do anything on its own yet. In a MAUI single project app, the different asset types have their own specific build actions, as we've already seen above:

<!-- excerpt from .csproj file -->
<ItemGroup>
    <!-- App Icon -->
    <MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" Color="#512BD4"/>
    <!-- Splash Screen -->
    <MauiSplashScreen Include="Resources\Splash\splash.svg" Color="#512BD4" BaseSize="128,128"/>
    <!-- Images -->
    <MauiImage Include="Resources\Images\*"/>
    <!-- Custom Fonts -->
    <MauiFont Include="Resources\Fonts\*"/>
    <!-- Raw Assets (also remove the "Resources\Raw" prefix) -->
    <MauiAsset Include="Resources\Raw\**" LogicalName="%(RecursiveDir)%(Filename)%(Extension)"/>
</ItemGroup>

Now, you might be asking yourself "but, how do I get the client-specific resources in there?". Well, we could of course replace the paths to each resource subfolder each time we build the app for a different client. This, however, would quickly become a massive hassle and wouldn't work with automated build pipelines.

A common solution to this type of problem is to use different build configurations, two for each client (one Debug and one Release configuration) and then use build conditions to select the correct set of resources to be included in the build process. We'll have a look at that next before coming back to using the correct assets.

Build Configurations

To add new build configurations, we need to select the drop down with the active build configuration:

In the drop down that appears, we then select "Configuration Manager", which opens the following dialog:

Now, we select the "Active solution configuration" drop down and then hit "New", which will open the "New Solution Configuration" dialog:

We can now provide a name to the new configuration and copy the settings from an existing one. We also need to create new project configurations (make sure to tick the checkbox). When we're done, we hit "OK" and come back to the "Configuration Manager" dialog.

Now, we need to select the newly created solution configuration and select the companion project configuration that we created, so that it looks like this:

We repeat these steps for every client and for both Debug and Release configurations. Provided that we use two clients (ClientA, ClientB) and a default configuration in this example, we will end up with the following six configurations:

• Debug

• Debug-ClientA

• Debug-ClientB

• Release

• Release-ClientA

• Release-ClientB

Note how these conditions also get added to your project's .csproj file:

<PropertyGroup>
    <TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
    <!-- skipping other properties -->

    <!-- new configurations we just added in the Configuration Manager -->
    <Configurations>Debug;Release;Debug-ClientA;Debug-ClientB;Release-ClientA;Release-ClientB</Configurations>
</PropertyGroup>

Note: The .sln file will also get, too, some new GUIDs and configurations are added in there, as well. Please do not meddle with this file, as it's very easy to break the entire solution this way.

Now, we can use these configurations together with build conditions in order to decide which assets to include in the build process.

Build Conditions and Properties

When working with a default MAUI app template, we will eventually come across some build conditions. If you have a little bit of experience with MAUI, you will have seen lines like this in the .csproj file of other apps plenty of times already:

<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>

The Condition in the above example will ensure that the Windows target is only used when the operating system on which the solution is compiled is Windows, because MAUI apps for Windows cannot be compiled on a Mac.

We can use this same mechanism also for our white labeling purposes, which is what we created the build configurations for in the previous step. We can filter the assets to be included using the active build configuration as follows:

<PropertyGroup Condition="'$(Configuration)' == 'Debug' OR '$(Configuration)' == 'Release'">
   <!-- define default properties -->
</PropertyGroup>

<PropertyGroup Condition="$(Configuration.EndsWith('ClientA'))">
   <!-- define ClientA properties -->
</PropertyGroup>

<PropertyGroup Condition="$(Configuration.EndsWith('ClientB'))">
   <!-- define ClientA properties -->
</PropertyGroup>

Above, we use the Configuration build property, which will have the value of one of the six build configurations we created earlier (e.g. "Debug", "Debug-ClientA" or "Release-ClientB", ...). The value of this property can be evaluated. There are even methods that can be called, such as EndsWith() to check for a substring, e.g. Condition="$(Configuration.EndsWith('ClientB'))".

Now, if we would define the properties and project items all in the .csproj file, things would get messy pretty quickly. Having a clean, manageable structure is key when it comes to rebranding. Therefore, instead of having all client-specific data in one massive .csproj file, we can split this into separate project property (.props) files, one for each of the clients, which for ClientA could look like this, for example:

<!-- ClientA.props file -->
<Project>
  <PropertyGroup>
    <!-- Assembly Name -->
    <ApplicationAssemblyName>SuperDuperApp</ApplicationAssemblyName>
    <!-- Display name -->
    <ApplicationTitle>Super Duper App</ApplicationTitle>
    <!-- App Identifier -->
    <ApplicationId>com.ClientA.SuperDuperApp</ApplicationId>
  </PropertyGroup>
  <ItemGroup>
    <!-- App Icon -->
    <MauiIcon Include="Resources\ClientA\AppIcon\appicon.svg" ForegroundFile="Resources\ClientA\AppIcon\appiconfg.svg" Color="#123456" ForegroundScale="0.65"/>
    <!-- Splash Screen -->
    <MauiSplashScreen Include="Resources\ClientA\Splash\splash.svg" Color="#123456" BaseSize="128,128"/>
    <!-- Images -->
    <MauiImage Include="Resources\ClientA\Images\*"/>
    <!-- Custom Fonts -->
    <MauiFont Include="Resources\ClientA\Fonts\*"/>
    <!-- Raw Assets (also remove the "Resources\Raw" prefix) -->
    <MauiAsset Include="Resources\ClientA\Raw\**" LogicalName="%(RecursiveDir)%(Filename)%(Extension)"/>
    <!-- Privacy Manifest for iOS -->
    <BundleResource Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'" Include="Platforms\iOS\PrivacyInfo.xcprivacy" LogicalName="PrivacyInfo.xcprivacy"/>
  </ItemGroup>
</Project>

This file contains all the client-specific properties and items that should be included only when building the app for ClientA. It is referencing the files and folders from the Resources/ClientA subfolder for the app icon, splash screen, etc., and it also defines the client-specific app title and package identifier (= ApplicationId).

If we do this for all clients, we can then include the correct .props file based on the selected configuration in our .csproj file using our build conditions:

<Project Sdk="Microsoft.NET.Sdk">

  <Import Condition="'$(Configuration)' == 'Debug' OR '$(Configuration)' == 'Release'" Project="Resources\Default\default.props" />
  <Import Condition="$(Configuration.EndsWith('ClientA'))" Project="Resources\ClientA\ClientA.props" />
  <Import Condition="$(Configuration.EndsWith('ClientB'))" Project="Resources\ClientB\ClientB.props" />

  <!-- this is required to give the output files (.dll) a different assembly name per client -->
  <PropertyGroup>
    <AssemblyName>$(ApplicationAssemblyName)</AssemblyName>
  </PropertyGroup>

</Project>

This just looks so much cleaner than having one massive .csproj file with lots of client-specific stuff in it, don't you agree? It also makes the onboarding of new clients more straightforward.

Intermediate Build

If we would build and deploy each of the three different client apps to a device now, we will see three different installed apps each with a unique app icon and name, all based on the same code base:

This is already pretty cool! However, we're not done yet, because if we would run each of the apps, apart from the app icon and app name, their content would still look identical. This is because we haven't made any other changes so far.

Important: For this to work, the App.xaml file needs to reference valid paths to the Colors.xaml and Styles.xaml resource dictionaries. However, in our setup above, these files have been moved to a different location and we haven't modified the App.xaml file. However, I don't actually want to change the App.xaml file at all, it should remain exactly the way it is. We will take a look at this next.

Styles and Colors

In a MAUI app, the App.xaml file typically references the resource dictionaries that contain definitions for the colors and styles like this:

<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MauiWhiteLabelling.App">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Resources/Styles/Colors.xaml" />
                <ResourceDictionary Source="Resources/Styles/Styles.xaml" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Note that there is a relative path to each of the XAML resource dictionaries. This path is problematic, because, unfortunately, XAML does not support conditional compilation. Therefore, we cannot provide different paths for different clients and unfortunately, MAUI also doesn't allow us to set the Source property from the code-behind, either.

So, how can we reference the correct colors and styles from our separate client asset subfolders? We shouldn't have to modify the App.xaml file every time we build an app for a specific client. That's too risky and only makes things complicated.

A common Xamarin.Forms way for this was to load these resource dictionaries dynamically during the app start. However, this introduces a new problem: The StaticResource markup will not be usable, because the styles are not known at the time of construction. Hence, we would have to resort to using the DynamicResource markup instead, which would introduce a performance penalty and we would lose the preview capabilities of the XAML editor (at least when using Visual Studio on Windows).

💡 However, fret not, I found a solution for this, as well. Since we have the .props files for each client in place already, we can use this mechanism to also copy some assets like the XAML resource dictionaries to a shared location, more specifically the location where the App.xaml file expects those resources to be: the Resources/Styles subfolder.

All we need to do for this to work is to update the .props files and add the InitialTargets attribute to the <Project> tag that points to a named Target with an action that copies the required files to the correct location:

<Project InitialTargets="CopyResourceFiles">
  <!-- skipping PropertyGroups and ItemGroups -->
  <Target Name="CopyResourceFiles">
    <Copy SourceFiles="Resources\ClientA\Styles\Styles.xaml;Resources\ClientA\Styles\Colors.xaml" DestinationFolder="Resources\Styles" />
  </Target>
</Project>

Basically, with this approach, we replace the two resource dictionary files every time we select a different build configuration. This is fine, because it's very fast and any build targets included in the InitialTargets will run before compilation. This is what allows us to still use the StaticResource markup, thus avoiding sweeping changes and performance hits.

I recommend adding the paths of the shared Styles.xaml and Colors.xaml file locations under Resources/Styles to the .gitignore file of your repository, so that they don't get included in any commits, similar to any auto-generated files that also don't need to be included, either:

# Explicit file exclusions
MauiWhiteLabelling/Resources/Styles/Colors.xaml
MauiWhiteLabelling/Resources/Styles/Styles.xaml

Styles and colors: Check ✅.

Let's have a look at custom fonts before finally running the app for the first time.

Fonts

In order to use custom fonts, we usually need to add the font files to the project and set the build action to MauiFont. Normally, this is already the case, as long as the font files are located in the directory specified for the <MauiFont> tag, e.g.:

<MauiFont Include="Resources\Fonts\*"/>

For white labeling to work, a simple trick to use different fonts per client is to add the font files using the exact same name for all clients inside the client-specific folders and then to register them using the exact same alias:

In the custom .props file we already specified the path to the client-specific font files:

<!-- ClientA.props -->
<MauiFont Include="Resources\ClientA\Fonts\*"/>

This way, we can reference a font directly by its shared alias and the correct client font file will always be used. We then don't have to specify which client we're registering which font for, we only need to modify the font registration in the MauiProgram.cs file as follows:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseMauiCommunityToolkit()
        .ConfigureFonts(fonts =>
        {
            // use the same font filename and alias for every client
            fonts.AddFont("FontRegular.ttf", "FontRegular");
            fonts.AddFont("FontSemibold.ttf", "FontSemibold");
        });

    return builder.Build();
}

As you can see, we don't use the actual font name here, we just use a shared naming convention for the font file and alias.

This approach is not mandatory, the FontFamily can also be specified in a style definition in the client-specific Styles.xaml resource dictionary using the actual names of the fonts. However the approach described here will make our lives a lot easier, since it allows us to use fonts by a shared naming convention everywhere in the app equally. We can simply specify the FontFamily like we normally would anywhere in our app and see the text in a different font depending on the selected client configuration:

<Label
    Text="Welcome!"
    FontFamily="FontSemibold"
    FontSize="36" />

In the next section we'll see what it all looks like when we actually run the app after quickly setting up a page that uses the client-specific resources we've supplied.

Running the app

Let's put it all together with a simple ContentPage that has the client's app logo, a label and a button, with a custom font and a client-specific background color:

<ContentPage
  x:Class="MauiWhiteLabelling.Views.MainPage"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
  BackgroundColor="{StaticResource Primary}"
  Shell.BackgroundColor="{StaticResource Primary}"
  Shell.NavBarIsVisible="False">

  <Grid>
    <VerticalStackLayout
      Padding="20,40"
      Spacing="40"
      VerticalOptions="Start"
      HorizontalOptions="Center">
      <Image
        Source="logo.png"
        WidthRequest="80"
        HeightRequest="80"
        HorizontalOptions="Center"
        VerticalOptions="Center" />
      <Label
        Text="Welcome!"
        FontFamily="FontSemibold"
        FontSize="36"
        HorizontalOptions="Center"
        VerticalOptions="Center" />
      <Button Text="Press me" Clicked="Button_OnClicked" />
    </VerticalStackLayout>
  </Grid>

</ContentPage>

Running this app now will yield three different results for the different client configurations, which is exactly what we wanted:

🎉 Isn't this awesome? With a simple setup and a few tricks, we managed to white-label an app for three different client configurations. Rock and roll 🤘!

However, sometimes, clients also want some unique or custom behavior. Now, that can be done just as well. Let me show you how in the next section.

Custom Behavior

We can create custom behavior for every client, e.g. by using compile constants or feature toggles. Compile constants can be defined in the client .props file as follows:

<Project InitialTargets="CopyResourceFiles">
  <PropertyGroup>
    <!-- skipping other stuff for brevity -->
    <!-- Compilation Constants for Client A -->
    <DefineConstants>$(DefineConstants);CLIENT_A</DefineConstants>
  </PropertyGroup>
  <ItemGroup>
    <!-- skipping assets for brevity -->
  </ItemGroup>
</Project>

With this in place, we can then instruct the compiler to modify the behavior of a method or anything else (even enable or disable entire features altogether) for a specific client. To keep things simple, I'll only show a small example here. The following code shows an event handler for a button's Clicked event on the MainPage:

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }

    private async void Button_OnClicked(object? sender, EventArgs e)
    {
#if DEFAULT_APP
        await DisplayAlert("Default App", "This is the default app", "OK");
#elif CLIENT_A
        await DisplayAlert("Client A", "This is client A", "OK");
#elif CLIENT_B
        await DisplayAlert("Client B", "This is client B", "OK");
#endif
    }
}

When the button is clicked, it will show a different text message based on the selected client configuration:

✨Whoohoo, we have a fully customized app!

Summary and next steps

I'm super excited about how easy it was to white-label a .NET MAUI app once I figured out all the necessary steps. I've demonstrated that it's possible to rebrand an app for different clients while maintaining the same code base and without having to frequently modify files and configurations.

A next step would be to include client-specific translation resources using .resx files, which could either be achieved by also copying the resource files into a single, shared location using the InitialTargets step or by using some kind of lookup mechanism (e.g. with a custom markup extension). If I find the time, I might investigate how to achieve this in the most straightforward way I can think of.

If you're wondering how I've set the client-specific status bar color on Android without having modified or included the AndroidManifest.xml file in my demonstration, check out the App.xaml.cs file in the repository that goes along with this post.

I hope this is useful to you. If you enjoyed this blog post, then you may follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post as well as my MAUI Samples repository, so you don't miss out on any future posts and developments.

Thanks for reading until here, and remember: sharing is caring!

Attributions

MauiWhiteLabelling project created using Matt Lacey's MAUI App Accelerator.

Jar with while label image generated using Microsoft Copilot/DALL-E.

Social media apps like Instagram use full-page scrollable video controls called "reels" (named after the device used to store film - or garden hoses) which allow the user to swipe or scroll up and down in order to switch between videos (or other content).

In this blog post, I will demonstrate how you can easily add a feature like a video reel to your own .NET MAUI app in a few simple steps. The idea is that we can scroll up and down and the video that becomes visible will start playing while the previously playing video gets stopped. All we need for this is a CollectionView and the MediaElement from the MAUI Community Toolkit (MCT).

After defining the model, we'll first have a look at how we can accomplish the desired layout, which is a full-page view that allows to swipe up and down and always stops at the next element. Afterwards, we'll implement the automatic play/stop functionality.

This post is based on a Stack Overflow answer that I recently wrote.

As always, you can have a look at the full code in the sample repository on GitHub.

Let's do it!

Model

The model for the reel is quite simple, we just need to create a VideoModel with a few properties, e.g. Title, VideoUri and IsPlaying:

public partial class VideoModel(string title, string videoUri) : ObservableObject
{
    public string Title { get; } = title;
    public string VideoUri { get; } = videoUri;

    [ObservableProperty]
    private bool _isPlaying;
}

The IsPlaying property is an auto-generated observable property, which we will need later on to control the automatic play/stop functionality.

ViewModel

In the ViewModel, we can define several instances of VideoModel using some sample video files that are stored locally in the repository, like so:

public partial class ReelViewModel : ObservableObject
{
    private const string FrogVideo = "https://github.com/ewerspej/maui-samples/blob/main/assets/frog.mp4?raw=true";
    private const string BuckVideo = "https://github.com/ewerspej/maui-samples/blob/main/assets/bigbuckbunny.mp4?raw=true";

    [ObservableProperty]
    private ObservableCollection<VideoModel> _videos;

    public ReelViewModel()
    {
        Videos =
        [
            new VideoModel("First", FrogVideo),
            new VideoModel("Second", BuckVideo),
            new VideoModel("Third", FrogVideo),
            new VideoModel("Fourth", BuckVideo),
            new VideoModel("Fifth", FrogVideo),
            new VideoModel("Sixth", BuckVideo)
        ];
    }
}

Later on, we can then bind to the Videos collection in XAML.

Basic Layout

In order to create the reel, we first need to add a CollectionView inside a Grid. The CollectionView will host the VideoModel instances. We want only a single item to be visible at a time, so we'll add a LinearItemsLayout and give the layout in the DataTemplate the sameHeightRequest as the CollectionView. In order to make the scrolling of the CollectionView stop at the next element, we'll also need to use snap points.

<Grid>

  <CollectionView
    HeightRequest="500"
    HorizontalOptions="Fill"
    VerticalOptions="Center"
    ItemsSource="{Binding Videos}"
    Scrolled="ItemsView_OnScrolled">

    <CollectionView.ItemsLayout>
      <LinearItemsLayout
        Orientation="Vertical"
        SnapPointsType="MandatorySingle"
        SnapPointsAlignment="Center" />
    </CollectionView.ItemsLayout>

    <CollectionView.ItemTemplate>
      <DataTemplate x:DataType="models:VideoModel">
        <Grid
          HeightRequest="500"
          HorizontalOptions="Fill"
          BackgroundColor="LightGreen">

          <Label
            Text="{Binding Title}"
            VerticalOptions="Center"
            HorizontalOptions="Center"
            FontSize="Title" />

        </Grid>
      </DataTemplate>
    </CollectionView.ItemTemplate>

  </CollectionView>

</Grid>

The result should something like this and we can scroll back and forth between the elements, with always only a single item visible at a time:

That's already pretty neat. Next, let's add the video player and the automatic play/stop functionality.

Automatic Play/Stop

Before we can implement the play/stop functionality, we need to install the CommunityToolkit.Maui.MediaElement package from nuget.org and initialize the MediaElement in our MauiProgram class before we can use it:

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement() // add this line

In order to automatically play a video that is hosted in a MediaElement, we need to work with a little trick. Since the MediaElement doesn't expose any bindable and settable IsPlaying property, we need to add that ourselves by extending the class with a BindableProperty:

public class ExtendedMediaElement : MediaElement
{
    public bool IsPlaying
    {
        get => (bool)GetValue(IsPlayingProperty);
        set => SetValue(IsPlayingProperty, value);
    }

    public static readonly BindableProperty IsPlayingProperty = BindableProperty.Create(nameof(IsPlaying), typeof(bool), typeof(ExtendedMediaElement), false, propertyChanged: OnIsPlayingPropertyChanged);

    private static void OnIsPlayingPropertyChanged(BindableObject bindable, object oldValue, object newValue)
    {
        var mediaElement = (ExtendedMediaElement)bindable;

        if (newValue is true)
        {
            mediaElement.Play();
        }
        else
        {
            mediaElement.Stop();
        }
    }
}

By using the OnIsPlayingPropertyChanged event handler, we can decide whether to play or stop the video whenever the IsPlaying property gets updated (via a binding).

With this in place, we can now add our ExtendedMediaElement to the XAML:

<DataTemplate x:DataType="models:VideoModel">
  <Grid
    HeightRequest="{Binding Height, Source={x:Reference Reels}}"
    HorizontalOptions="Fill">

    <media:ExtendedMediaElement
      Aspect="Fill"
      Source="{Binding VideoUri}"
      ShouldAutoPlay="False"
      ShouldLoopPlayback="True"
      ShouldShowPlaybackControls="False"
      IsPlaying="{Binding IsPlaying}" />

    <Label
      Text="{Binding Title}"
      VerticalOptions="Center"
      HorizontalOptions="Center"
      FontSize="Title" />

  </Grid>
</DataTemplate>

Now, a video is only played and stopped whenever the IsPlaying property of the associated VideoModel instance changes.

However, we're not entirely done yet, one important part is still missing. We want the videos to automatically start and stop whenever an element is scrolled into and out of view. For this, we need to hook up an event handler for the Scrolled event of the CollectionView, where we then update the IsPlaying property of each item in the underlying collection:

<CollectionView
  HeightRequest="{Binding Height, Source={x:Reference Reels}}"
  HorizontalOptions="Fill"
  VerticalOptions="Center"
  ItemsSource="{Binding Videos}"
  Scrolled="ItemsView_OnScrolled">

  <!-- ... -->

</CollectionView>

The event handler lives in the code-behind of our page and iterates through the Videos collection to update the IsPlaying property of the VideoModel instances:

public partial class ReelPage : ContentPage
{
    private readonly ReelViewModel _vm;

    public ReelPage(ReelViewModel vm)
    {
        InitializeComponent();
        BindingContext = _vm = vm;
    }

    private void ItemsView_OnScrolled(object sender, ItemsViewScrolledEventArgs e)
    {
        var itemIndex = e.CenterItemIndex;

        _vm.Videos[itemIndex].IsPlaying = true;

        foreach (var myModel in _vm.Videos)
        {
            if (myModel != _vm.Videos[itemIndex])
            {
                myModel.IsPlaying = false;
            }
        }
    }
}

Almost there. Now, the automatic play/stop should already be working. Let's touch up the XAML a little bit and have a look at the final result next.

Final Full-Page Layout

Last, but not least, in order to have the CollectionView take up the entire available space of the page, we can simply bind the HeightRequest of the CollectionView as well as the Grid in the DataTemplate to the rendered Height of the page to end up with the following final layout:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage
  x:Class="MauiSamples.Views.ReelPage"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
  xmlns:models="clr-namespace:MauiSamples.Models"
  xmlns:viewModels="clr-namespace:MauiSamples.ViewModels"
  xmlns:media="clr-namespace:MauiSamples.CustomControls.Media"
  x:Name="Reels"
  x:DataType="viewModels:ReelViewModel"
  Shell.NavBarIsVisible="False">

  <Grid>

    <CollectionView
      HeightRequest="{Binding Height, Source={x:Reference Reels}}"
      HorizontalOptions="Fill"
      VerticalOptions="Center"
      ItemsSource="{Binding Videos}"
      Scrolled="ItemsView_OnScrolled">

      <CollectionView.ItemsLayout>
        <LinearItemsLayout
          Orientation="Vertical"
          SnapPointsType="MandatorySingle"
          SnapPointsAlignment="Center" />
      </CollectionView.ItemsLayout>

      <CollectionView.ItemTemplate>
        <DataTemplate x:DataType="models:VideoModel">
          <Grid
            HeightRequest="{Binding Height, Source={x:Reference Reels}}"
            HorizontalOptions="Fill">

            <media:ExtendedMediaElement
              Aspect="AspectFill"
              Source="{Binding VideoUri}"
              ShouldAutoPlay="False"
              ShouldLoopPlayback="True"
              ShouldShowPlaybackControls="False"
              IsPlaying="{Binding IsPlaying}" />

            <Label
              Text="{Binding Title}"
              VerticalOptions="Center"
              HorizontalOptions="Center"
              FontSize="Title" />

          </Grid>
        </DataTemplate>
      </CollectionView.ItemTemplate>

    </CollectionView>

  </Grid>

</ContentPage>

Now, when we run the app, we have a full-page reel control:

🏆 Fantastic, I'm excited about the result.

Conclusions and next steps

As I demonstrated here, adding a scrollable video control similar to Instagram's reels to your .NET MAUI app is quite simple. A neat addition to this would be to make the entire page fullscreen, but that would be too much for a single blog post. The main focus here was supposed to be on how to combine the CollectionView and the MediaElement to create a reel and that's surprisingly easy to achieve.

Note: I didn't touch on any issues regarding caching or performance in this post. When the list of videos gets very long or when items are incrementally loaded, e.g. when using the infinite scroll capabilities of CollectionView, we might observe performance degradation, which should then be addressed separately.
Thanks to Gerald Versluis for pointing this out.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts and developments. And remember that sharing is caring.

Attributions

Title photo by Markus Spiske on Unsplash

In December of 2023, I introduced the epj.RouteGenerator package which provides a facility to have route identifiers for .NET-based frontend applications auto-generated for you, taking away a few pain points with string-based route navigation and maintenance hassles.

This is a follow up post. You can find the original blog post here. If you're unfamiliar with Route Generator, please read that first. Gerald Versluis also made a great YouTube video showing the Route Generator in action.

Since then, one thing that I have been frequently asked was whether it would be possible to add automatic registration of routes to the route generator, as to further simplify and reduce the amount of manually written code in .NET apps.

Now, my intention is to keep the route generator independent from specific UI frameworks, so that it can be used with any kind of .NET-based application that uses routes for navigation. Therefore, in order to provide full support of automatic route registration, say in .NET MAUI, it would be required to do two things:

1. Gather the type information, e.g. the fully qualified type name

2. Add a MAUI-specific layer with a registration method

For now, I decided to focus on the first step only, because it will already make things a lot easier while remaining framework-independent. The second step is a little bit more tricky as the generator shouldn't have MAUI-specific knowledge. To overcome this limitation, creating another library that builds on top of epj.RouteGenerator, for example something like epj.RouteGenerator.Maui, would be required. Writing such library that exposes all kinds of useful utility methods specifically target at .NET MAUI will require some time and design considerations.

Here are the good news though: The first step is already done with the latest preview version of the Route Generator (1.0.1-alpha2 at the time of writing), which is already available for download on nuget.org.

Let's see what that means and how to use it 🤩.

Route/Type Map

On top of the read-only AllRoutes collection, the generated Routes class now also exposes a read-only dictionary called RouteTypeMap which maps the routes to their respective Type:

// <auto-generated/>
using System.Collections.ObjectModel;

namespace RouteGeneratorSample
{
    public static class Routes
    {
        public const string MainPage = "MainPage";
        public const string VolvoPage = "VolvoPage";
        public const string AudiPage = "AudiPage";

        private static List<string> allRoutes = new()
        {
            MainPage,
            VolvoPage,
            AudiPage,
        };

        public static ReadOnlyCollection<string> AllRoutes => allRoutes.AsReadOnly();

        // NEW:
        private static Dictionary<string, Type> routeTypeMap = new()
        {
            { MainPage, typeof(RouteGeneratorSample.MainPage) },
            { VolvoPage, typeof(RouteGeneratorSample.Cars.VolvoPage) },
            { AudiPage, typeof(RouteGeneratorSample.Cars.AudiPage) },
        };

        public static ReadOnlyDictionary<string, Type> RouteTypeMap => routeTypeMap.AsReadOnly();
    }
}

Now, this type information can be used to register routes, for example in .NET MAUI, without the source generator requiring specific knowledge about the UI framework.

Route Registration in .NET MAUI

Usually, we would need to register each route manually by typing out each registration call for every route and type. This is typically done in AppShell.xaml.cs similar to this:

using System.Diagnostics;

namespace RouteGeneratorSample;

public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();

        Routing.RegisterRoute(nameof(MainPage), typeof(MainPage));
        Routing.RegisterRoute(nameof(VolvoPage), typeof(VolvoPage));
        Routing.RegisterRoute(nameof(AudiPage), typeof(AudiPage));
    }
}

With the new Routes.RouteTypeMap dictionary, we can now register routes (semi-) automatically - all you need to do is iterate over the map like this:

foreach (var route in Routes.RouteTypeMap)
{
    Routing.RegisterRoute(route.Key, route.Value);
}

💪 That's it! No more manual typing of each route name and type for registration.

Extra Routes

What about extra routes? For example, if a route name doesn't match a type name, then what? Route Generator has got you covered, as well! The [ExtraRoute] attribute now features a second argument which can be used to specify the type that should be used for the route using typeof(ClassName):

namespace RouteGeneratorSample;

// pass the type for the route to the ExtraRoute attribute,
// this will make sure to include the type in the Routes.RouteTypeMap;
// the key will be "YetAnotherRoute" and the value the type of MainPage

[AutoRoutes("Page")]
[ExtraRoute("YetAnotherRoute", typeof(MainPage))] 
public static class MauiProgram
{
    // ...
}

Like this, the Routes.YetAnotherRoute identifier is used to associate a route to the MainPage in the example above. The resulting auto-generated Routes.g.cs class will then look as follows:

// <auto-generated/>
using System.Collections.ObjectModel;

namespace RouteGeneratorSample
{
    public static class Routes
    {
        public const string MainPage = "MainPage";
        public const string VolvoPage = "VolvoPage";
        public const string AudiPage = "AudiPage";
        public const string YetAnotherRoute = "YetAnotherRoute";

        private static List<string> allRoutes = new()
        {
            MainPage,
            VolvoPage,
            AudiPage,
            YetAnotherRoute
        };

        public static ReadOnlyCollection<string> AllRoutes => allRoutes.AsReadOnly();

        private static Dictionary<string, Type> routeTypeMap = new()
        {
            { MainPage, typeof(RouteGeneratorSample.MainPage) },
            { VolvoPage, typeof(RouteGeneratorSample.Cars.VolvoPage) },
            { AudiPage, typeof(RouteGeneratorSample.Cars.AudiPage) },
            { YetAnotherRoute, typeof(RouteGeneratorSample.MainPage) },
        };

        public static ReadOnlyDictionary<string, Type> RouteTypeMap => routeTypeMap.AsReadOnly();
    }
}

Now, the Routes.YetAnotherRoute identifier can be used to navigate to the MainPage using await Shell.Current.GoToAsync(Routes.YetAnotherRoute) or similar.

Please note that if you specify an extra route that doesn't match with an existing type name without explicitly specifying the target type, that extra route will not be included in the Routes.RouteTypeMap, because the type would be undefined. The Route Generator will emit a warning in this case.

Conclusions and next steps

In this follow-up post I have demonstrated some of the further development possibilities for the Route Generator for .NET. Being able to register route names and types automatically can further reduce manually typed code and offering a way to facilitate this seemed like a wonderful idea, so that's what I did.

If you have feedback or suggestions for improvements or additional features, please don't hesitate to get in touch or post an issue in the GitHub repository.

If you enjoyed this blog post, then follow me on LinkedIn and subscribe to this blog so you don't miss out on any future posts. If this is useful to you, maybe also consider starring the GitHub repository of the Route Generator. Thank you very much 💖.

Modern .NET applications have adopted the concept of routes for navigation. Usually, these routes are string-based, which has a couple of implications. One of the problems is the volatility of route names, which I am addressing in this blog post.

A while ago, when working on a .NET MAUI application with some colleagues, I realized that I could simplify our job and at the same time gain more stability and confidence in our string-based route navigation by having route identifiers automatically generated for us. This is how the idea for the Route Generator was born, which I am going to introduce here today.

Although this post and the sample project focus on .NET MAUI, the concepts and the Route Generator can be applied to different contexts and UI frameworks.

First, we'll have a look at which problems the Route Generator is supposed to solve and then we'll see how simple it is to use the Route Generator in your own project.

If you're interested in seeing the generator in action or want to have a look at the implementation, it's open source and the repository including the sample project can be found on GitHub.

Problems

Since routes are often string-based, route names are volatile by nature. For example, if a route is called "SomePage", but later gets renamed to "XyzPage", then this may create a problem, because it potentially breaks the navigation when the new name isn't used in routing calls. Often, developers resort to using nameof(SomePage) to circumvent this issue. Therefore, instead of registering a route using a verbatim string

Routing.RegisterRoute("SomePage", typeof(SomePage));

we can often see something like this:

Routing.RegisterRoute(nameof(SomePage), typeof(SomePage));

where SomePage is a class that represents some type of page that can be navigated to.

This is usually done, because it avoids issues when SomePage gets renamed or deleted. Changes are instantly noticeable, because the project doesn't compile anymore if an unknown symbol is used in the nameof(SomePage) and typeof(SomePage) calls. However, since renaming operations usually would also update the symbol usages, changing the name of a page shouldn't actually produce any immediate problems. And if for some reason it does, then the compiler lets us know that something is broken and we can go ahead and fix it.

All this is not an issue when it comes to route registration. However, it very much becomes a problem when performing string-based route navigation, especially when applying the MVVM pattern. If we want to perform navigation in the ViewModel (or even in the code-behind), the calling code must either have knowledge of the type and call nameof(SomePage) or, again, use a verbatim string instead, i.e. "SomePage":

// Approach #1. Problem: caller depends on SomePage type
await Shell.Current.GoToAsync($"/{nameof(SomePage)}");

// Approach #2. Problem: verbatim route is volatile
await Shell.Current.GoToAsync("/SomePage");

In the first approach, we would introduce a dependency on the SomePage class for the caller. This usually is less of an issue when performing navigation exclusively from within the code-behind of a XAML-based UI application (depending on the app architecture). It definitely is a violation of the MVVM pattern, though, when doing this inside of a ViewModel and potentially makes the ViewModel untestable (with regards to unit tests), because the ViewModel would have a dependency on the View.

The second approach uses a verbatim string instead of using nameof(SomePage). This seems fine at first glance, but introduces another issue: Routes aren't reliable (volatile). Imagine you have an app with tens or even hundreds of potential routes and you use verbatim strings for route navigation, then you may quickly end up with hours of debugging and looking for the culprit, when the route name has changed from "SomePage" to "XyzPage". The following code would still compile, but navigation will certainly fail:

// compiles, but the route "SomePage" won't be found during runtime
// if it has previously been renamed to "XyzPage"
await Shell.Current.GoToAsync("/SomePage");

Typically, frameworks like .NET MAUI will emit an error informing the developer that a route couldn't be found. Developers sometimes also wrap navigation statements in try-catch-blocks to catch possible navigation exceptions, which only prevents the app from crashing, but it doesn't solve the navigation problem.

Suboptimal workarounds

We can attempt to work around this, e.g. by adding a static class that contains all route names by referencing the page classes inside of it:

namespace MyApp;

public static class Routes
{
    public const string SomePage = nameof(SomeFeature.View.SomePage);
    public const string AnotherPage = nameof(AnotherFeature.View.AnotherPage);
}

This seems to work even with the MVVM pattern, but note that we actually introduce a transitive dependency by using nameof(SomePage), etc. in the static class.

While nameof() actually produces a compile-time constant, there is an indirect dependency on the page classes during compilation. Therefore, we technically end up with a violation of the MVVM pattern, after all. The dependency on SomePage may be "gone" from the ViewModel and may not prevent unit tests anymore, but now it just has become implicit instead of explicit, which is even worse from a dependency management perspective, because it's hidden.

If we do this, we could at least rename the SomePage class and our navigation would still work. This still is problematic, though, because essentially, if we rename the SomePage class to XyzPage and don't update the Routes constants, we would end up with a Routes class looking like this:

namespace MyApp;

public static class Routes
{
    public const string SomePage = nameof(SomeFeature.View.XyzPage);
    public const string AnotherPage = nameof(AnotherFeature.View.AnotherPage);
}

This is awkward, because we would still use the Routes.SomePage identifier for navigation, but it actually navigates to XyzPage - the route name doesn't match with the identifier anymore, which may lead to a lot of confusion:

// will navigate to XyzPage now...
await Shell.Current.GoToAsync($"/{Routes.SomePage}");

This isn't pretty or advisable, because it's utterly inconsistent.

Now, another tempting approach would then be to just use constant strings directly instead of using nameof(SomePage) in order to remove the transitive dependencies:

public static class Routes
{
    public const string SomePage = "SomePage";
    public const string AnotherPage = "AnotherPage";
}

While this works, the route identifiers would be again be highly volatile, because renaming the SomePage class wouldn't be reflected in the static Routes class unless a search-and-replace operation is performed afterwards in order to also rename the symbol and update the constant string value.

Personally, I prefer that a project fails to compile when something changed over noticing changes only during runtime. If a breaking change (renamings usually are breaking changes) is introduced, I would like to know and be able to react to it directly instead of waiting for a bug to be found or an exception to occur during runtime.

So, how can we use constant route identifiers while avoiding invalid routes then in order to prevent ending up in navigation hell?

Enter Route Generator

Enter Route Generator. It's an incremental source generator that produces a static Routes class like above, always based on the currently available pages in a project. Now, in order to only generate routes for classes that actually represent pages, the generator takes an argument to specify a naming convention for routes.

"How is this different from manually typing a static Routes class?" you might ask. Well, that's a great question and the answer is simple:

Any changes are immediately reflected in the Routes class when a page gets added, removed or renamed. Renaming a page class will automatically lead to compiler errors in places where a constant route identifier was used before, because it won't exist anymore. This doesn't happen when you manually implement such a class.

For example, when renaming the SomePage class to XyzPage, the following

public static class Routes
{
    public const string SomePage = "SomePage";
    public const string AnotherPage = "AnotherPage";
}

will become

public static class Routes
{
    public const string XyzPage = "XyzPage";
    public const string AnotherPage = "AnotherPage";
}

This is perfect, because if we previously used

// will fail to compile, because Routes.SomePage doesn't exist anymore
// after renaming it to XyzPage
await Shell.Current.GoToAsync($"/{Routes.SomePage}");

we now will have to update the code to fix the resulting compiler error:

await Shell.Current.GoToAsync($"/{Routes.XyzPage}");

Let's look at how you can add the Route Generator and use it in your project next.

How to use Route Generator

The Route Generator, which implements the IIncrementalGenerator interface, is still in preview at the time of writing and can be downloaded and installed from nuget.org. Just add the epj.RouteGenerator package to your project (you may need to enable the "Include prerelease" check box in the Nuget Package Manager):

Then, in order to have routes generated, all you need to do is use the [AutoRoutes("SomeSuffix")] attribute from the epj.RouteGenerator namespace anywhere in the target project where your pages are defined.

While the attribute can be added to any class within the target project, I highly recommend using it to decorate your MauiProgram class, if you use .NET MAUI:

using epj.RouteGenerator;

namespace RouteGeneratorSample;

// use this attribute to have Routes generated using the provided suffix
[AutoRoutes("Page")]
public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

        return builder.Build();
    }
}

Note that you can only use a single instance of the [AutoRoutes("Suffix")] attribute. When the Route Generator finds this attribute, it uses the provided suffix as a naming convention and looks for any classes whose names end in this suffix.

A common way to name pages is to use the "Page" suffix like above, but you can use any other naming convention, as well. The generator does not provide a default, so you will always have to specify your suffix with the attribute. Once added, route identifiers are automatically generated.

The generated static Routes class will be located in the same root namespace of the class that was decorated with it:

// <auto-generated/>
namespace RouteGeneratorSample
{
    public static class Routes
    {
        public const string SomePage = "SomePage";
    }
}

While you can also use the identifiers of the auto-generated Routes class to register routes (usually done in AppShell.xaml.cs when using .NET MAUI), this is not mandatory or necessary:

// both ways to register routes work and are equally valid
Routing.RegisterRoute(nameof(SomePage), typeof(SomePage));
Routing.RegisterRoute(Routes.AnotherPage, typeof(AnotherPage));

The important thing is that you can now use the generated identifiers for navigation without having to worry about volatile route names anymore:

await Shell.Current.GoToAsync($"/{Routes.SomePage}");

This works, because as soon as you rename a class, the route identifiers are regenerated.

Extra Routes

Now, you might encounter situations where routes do not follow the specified naming convention. To cover for this scenario, the Route Generator actually provides a second attribute that allows you to specify extra route names manually.

Imagine you have a page that is simply called Dashboard and thus doesn't follow the naming convention using the "Page" suffix of the remaining pages, then you can specify this route identifier explicitly:

// generate routes based on "Page" suffix
// and also add "Dashboard" as an extra route explicitly
[AutoRoutes("Page")]
[ExtraRoute("Dashboard")]
public static class MauiProgram
{
    // ...
}

Now, the Dashboard identifier will also be included in the generated routes:

public static class Routes
{
    public const string SomePage = "SomePage";
    public const string AnotherPage = "AnotherPage";
    public const string Dashboard = "Dashboard";
}

Although this is the same as manually typing the identifiers and strings, the Route Generator makes sure that the Routes are always up-to-update and you'll see compiler errors whenever a page gets renamed or removed.

A quick note about using Shell.Current

If you're using .NET MAUI or Xamarin.Forms, then you may be inclined to directly access Shell.Current to perform any string-based route navigation:

await Shell.Current.GoToAsync($"/{Routes.SomePage}");

While this is acceptable when performing navigation exclusively in the code-behind, I recommend hiding any calls to the different overloads of the GoToAsync() method behind an interface and inject that into your ViewModel. This will remove the Shell.Current dependency and your ViewModel remains MVVM-compliant and unit-testable, because you'll be able to mock the navigation:

private readonly INavigationService _navigationService;

public MyViewModel(INavigationService navigationService)
{
    _navigationService = navigationService;
}

public async Task OpenSomePageAsync()
{
    await _navigationService.GoToAsync($"/{Routes.SomePage}");
}

You can find an example of this INavigationService and its implementation in the sample project of the Route Generator repository.

Conclusions and next steps

In my quest for maintainable and less boilerplate code, I have come across source generators a while ago and this blog post is my latest addition during this journey. This time I have written about the first source generator that I have developed and published myself. (It turns out that writing source generators is pretty straightforward when you know what you need.)

String-based route navigation can be a finicky thing and changing route names and adjusting navigation calls can be quite tedious. If approached naively with verbatim strings, it can also be highly error-prone, which is why I have developed the Route Generator. I have shown you how to use it and what problems you can solve with it. I hope this is useful for you and reduces the same pain that I have been experiencing when using string-based route navigation in the past.

A big thank you to Gerald Versluis (who also made a cool video about the Route Generator) for proof-reading this blog post for me (again). 💝

This blog post was written and published as part of the 2023 .NET Advent Calendar by Dustin Moris.

If you enjoyed this blog post, then follow me on LinkedIn and subscribe to this blog so you don't miss out on any future posts. If this is useful to you, maybe also consider starring the GitHub repository of the Route Generator. Thank you very much.

Cross-platform development is amazing, you only need to write the code once and then you can deploy to multiple platforms all from the same code base. Or so the theory goes. In reality, each platform has specific, native capabilities and APIs which sometimes need to be handled separately.

In my series about multi-targeting I've already touched on this topic, but the focus was on platform-specific APIs. Each platform has a different look-and-feel and sometimes you want things to look native or you want UI elements to look a certain way on a specific platform, like having a green underline on Android and a red underline on iOS or different icons and logos. There's a plethora of ways to customize how your app looks, such as control customization using handlers and markup extensions to name just a few.

Sometimes, styling or customizing individual controls just isn't enough, though. What if you need an entire part of a page to look very different on each platform (or device type) like someone asked in this Stack Overflow question: "Can we also have platform-specific XAML?" The answer is simple: Yes, we certainly can!

In this blog post, I'll show you a few ways how you can use custom XAML files in your app based on the platform or device type. One of the obvious choices would be to use multi-targeting. Unfortunately, .NET's multi-targeting currently doesn't support conditional XAML compilation or proper exclusion of XAML files based on the target platform (yet). Therefore, I'll show other approaches that work well for me.

To keep things simple, I'll only focus on custom views. Custom platform-specific pages can also be instantiated, which can be seen in my answer to the Stack Overflow question above as well as in my sample repository.

First, we'll look into two code-behind approaches, one using a runtime decision and another one using conditional compilation. After that, we'll explore a purely XAML-based approach. For the latter, we'll use different XAML files than for the first two approaches, so that the different approaches remain distinct in the sample code.

Code-behind approaches

Since this post is about XAML, let's start with a simple layout. Here, we have a VerticalStackLayout and it has an x:Name set so that we can manipulate the contents of it by accessing it via the VerticalLayout identifier in the code-behind.

<Grid RowDefinitions="*,4*">

  <VerticalStackLayout
    Grid.Row="0"
    x:Name="VerticalLayout" />

</Grid>

In the next two subsections, we'll see how we can add different XAML views to this layout based on the target platform.

Runtime decision

The simplest way to show platform-specific views is to make the appropriate calls in the code-behind based on the current runtime platform:

if (DeviceInfo.Platform == DevicePlatform.Android)
{
    VerticalLayout.Add(new Android.ViewAndroid());
}
else if (DeviceInfo.Platform == DevicePlatform.iOS)
{
    VerticalLayout.Add(new iOS.ViewiOS());
}

The downside of this approach is that the resulting code will be available on all target platforms.

Conditional compilation

An alternative and slightly better approach compared to the runtime decision is to use conditional compilation instead:

#if ANDROID
    VerticalLayout.Add(new Android.ViewAndroid());
#elif IOS
    VerticalLayout.Add(new iOS.ViewiOS());
#endif

The advantage of this is that only the appropriate calls end up in the compiled app code for each target platform and no decision needs to be taken during runtime.

XAML-only approach

It's also possible to show only the relevant parts of the UI based on the current runtime platform by only using XAML and no C# code by taking advantage of <OnPlatform>:

<Grid RowDefinitions="*,4*">

  <ContentView
    Grid.Row="1"
    Padding="20">

    <OnPlatform x:TypeArguments="View">
      <On Platform="Android">
        <android:ImageViewAndroid />
      </On>
      <On Platform="iOS">
        <iOs:ImageViewiOS />
      </On>
    </OnPlatform>

  </ContentView>

</Grid>

Here, we have a ContentView that serves as a container and we control its content by using the <OnPlatform> class and providing different views for each platform. It's important to include the x:TypeArguments="View" attribute, because we need to tell <OnPlatform> what the return type is as the ContentView class only accepts View instances as its Content. It's really as simple as that!

Note: This is equivalent to the runtime decision approach in the code-behind, meaning that all views of all platforms will be included in the app bundle.

It's also possible to use <OnIdiom> to provide different views depending on the device type (e.g. tablet, phone, desktop):

<Grid RowDefinitions="*,4*">

  <ContentView
    Grid.Row="1"
    Padding="20">

    <OnIdiom x:TypeArguments="View">
      <On Idiom="Tablet">
        <tablet:TabletView />
      </On>
      <On Idiom="Phone">
        <phone:PhoneView />
      </On>
    </OnIdiom>

  </ContentView>

</Grid>

Result

This is what it will look like on iOS and Android using the different approaches I demonstrated above. The "Hello from iOS" and "Hello from Android" parts come from the code-behind approaches while the logos come from the XAML-only approach.

Notes

As I have mentioned already in the introduction, multi-targeting specifically for XAML isn't really supported (yet), unfortunately. I have spent a fair share of hours trying to figure out how to accomplish this and although I have found a potential solution, it comes with several drawbacks, which is why I decided not to show it as of now. If future versions of .NET support multi-targeting for XAML or if I manage to figure out a well-working solution, I will write a follow-up on this topic.

Bear in mind that due to the nature of the implementation of the approaches above and the fact that multi-targeting currently isn't supported for XAML, only the code-behind is subject to conditional compilation. This means that all XAML code of your app project will be shipped to all target platforms, even the unused XAML which is specific to other target platforms (or device types).

Conclusions and next steps

As we have seen, it's actually quite easy to have platform-specific XAML in our .NET MAUI applications by using runtime decisions (either in C# or XAML) or conditional compilation.

Although it's not possible (yet) to use conditional compilation for XAML or even filename and folder-based multi-targeting for XAML files, the presented approaches can help you elevate the user experience of your cross-platform app by providing platform-specific views with ease. I hope you learned something useful today. Enjoy building awesome cross-platform apps with platform-specific views with .NET MAUI!

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts and developments.

Accordions are brilliant, and I am not talking about the Austrian-developed musical instrument, which is popular for singing sea shanties in Germany (whether those are 'brilliant' is a matter of musical taste). I am talking about the type of user control that can be used to expand and collapse sections of content in user interfaces, such as in mobile apps and websites. By allowing the user to navigate content quickly without having to scroll endlessly back and forth, they enhance the user experience of any application and website that features a lot of content that can be split up into sections or sub-sections.

What makes an accordion? Essentially, an accordion is just a collection of expanders that can show and hide their content through user interaction. Many accordions are implemented in such a way that only one single expander of the collection can be expanded at a time, while the remaining expanders are in their collapsed state. When the user selects one of the expanders, it will expand its content while any open expander will collapse its content in that moment.

In the following sections, I will demonstrate three ways how you can implement an accordion that you can tailor to your own needs using my recently published and highly customizable expander control for .NET MAUI. The result will look like this:

Note: You can also use any other Expander control as the base of an accordion as long as it allows you to expand and collapse it programmatically. So, although this post focusses on how this can be done using my own Expander control, the general idea applies to any other appropriate implementation of an Expander.

You can find the sample code from this blog post in the GitHub repository of the expander control.

Note: This blog post uses the MVVM Source Generators of the .NET Community Toolkit to keep the code samples short. Use of the Source Generators is entirely optional.

Excursion: Why implement a new Expander control?

Recently, while porting an app from Xamarin.Forms to .NET MAUI, I came across a problem with the Expander control of the MAUI Community Toolkit (MCT). The Expander of the MCT behaves differently than the Expander of the Xamarin.Forms Community Toolkit (XCT).

This difference imposed a problem, because I couldn't use the Expander for an accordion control anymore in the way that I needed it. Usually, this calls for a bug report or a feature request. However, the differences in the control seem to be deliberate and the implementations differ quite a bit. Also, I needed a solution fast and it felt like a neat addition to my toolbox of open source controls for MAUI.

So, I whipped up my own little Expander control instead and using that, I am going to show you how you can use it to implement your own accordion control. Apart from being easy to use, one of the treats of this Expander is that it comes with simple collapse and expand animations built-in (at the time of writing these are still experimental).

Installing the Expander

The first thing we need to do before we can implement the accordion is adding the epj.Expander.Maui package (version 1.0.2 at the time of writing) from nuget.org to our MAUI app project:

Once that is done, you can optionally enable animations, which requires an explicit opt-in at the time of writing. In order to do this, simply put the following call anywhere in your app, ideally in MauiProgram.cs or App.xaml.cs:

Expander.EnableAnimations();

Now, that the Expander is installed and configured, we can implement the accordion.

Implementing the accordion

There are various use cases and different ways how to approach this. I will show three scenarios that I regard as the most common ones in the following sub-sections. As a general outline, all three accordion implementations will consist of a few instances of the Expander control contained inside of a VerticalStackLayout.

While the first approach will look at an implementation that works without data binding (not using a ViewModel), which is mainly useful for View-only scenarios, e.g. displaying static text, the second example will show a mix of data binding (using a ViewModel) and controlling the accordion's segments from the View's code-behind. Last but not least, the third approach will demonstrate how to control the state of the accordion purely based on data binding (using a ViewModel).

Version 1: View-only accordion

In this first example, the accordion will be built using three explicit, static instances of the Expander. The entire presentation and interaction is fully controlled by the View. This is useful when working with static content, such as long text or images that are not dynamically loaded.

For this, we need to take the following steps:

1. Add several Expander instances to a VerticalStackLayout

2. Provide an x:Name to the VerticalStackLayout to be able to access it from the code-behind

3. Add an event handler for the HeaderTapped event to the code-behind to be used by each Expander

The XAML of our View could look something like this, for example:

<VerticalStackLayout
  x:Name="AccordionLayout"
  Spacing="6">

  <maui:Expander
    HeaderTapped="Expander_OnHeaderTapped"
    Animated="True">
    <maui:Expander.HeaderContent>
      <Grid
        HeightRequest="80"
        BackgroundColor="Orange">
        <Label
          Text="Expander #1"
          FontSize="Title"
          VerticalOptions="Center"
          HorizontalOptions="Center" />
      </Grid>
    </maui:Expander.HeaderContent>
    <Grid
      HeightRequest="200"
      BackgroundColor="DarkSlateGray">
      <Label
        Text="This is the content of the first expander!"
        VerticalOptions="Center"
        HorizontalOptions="Center" />
    </Grid>
  </maui:Expander>

  <maui:Expander
    HeaderTapped="Expander_OnHeaderTapped"
    Animated="True">
    <maui:Expander.HeaderContent>
      <Grid
        HeightRequest="80"
        BackgroundColor="Orange">
        <Label
          Text="Expander #2"
          FontSize="Title"
          VerticalOptions="Center"
          HorizontalOptions="Center" />
      </Grid>
    </maui:Expander.HeaderContent>
    <Grid
      HeightRequest="200"
      BackgroundColor="DarkSlateGray">
      <Label
        Text="This is the content of the second expander!"
        VerticalOptions="Center"
        HorizontalOptions="Center" />
    </Grid>
  </maui:Expander>

  <maui:Expander
    HeaderTapped="Expander_OnHeaderTapped"
    Animated="True">
    <maui:Expander.HeaderContent>
      <Grid
        HeightRequest="80"
        BackgroundColor="Orange">
        <Label
          Text="Expander #3"
          FontSize="Title"
          VerticalOptions="Center"
          HorizontalOptions="Center" />
      </Grid>
    </maui:Expander.HeaderContent>
    <Grid
      HeightRequest="200"
      BackgroundColor="DarkSlateGray">
      <Label
        Text="This is the content of the third expander!"
        VerticalOptions="Center"
        HorizontalOptions="Center" />
    </Grid>
  </maui:Expander>

</VerticalStackLayout>

Each expander can already be expanded and collapsed separately. Now, in order to add the accordion-style functionality where only one expander is allowed to be in the expanded state at a time, all we need to do is adding the event handler for the HeaderTapped event, which is already set to a method name in the XAML above:

private void Expander_OnHeaderTapped(object sender, ExpandedEventArgs e)
{
    if (sender is not Expander expander)
    {
        return;
    }

    foreach (var child in AccordionLayout.Children)
    {
        if (child is not Expander other)
        {
            continue;
        }

        if (other != expander)
        {
            other.IsExpanded = false;
        }
    }
}

In this event handler, we simply iterate through the child elements of the VerticalStackLayout (which we've called AccordionLayout using the x:Name attribute), and check if the current element is an expander. If it is an expander, we compare it to the expander instance that invoked the event. If the other expander is not the same as the current expander, we simply set its IsExpanded property to false. This will collapse all expanders except for the one that has just been selected by the user.

That's all we need to do, the final result should look something like this:

Version 2: Hybrid accordion

In this second example, the accordion will be built by dynamically populating the content using data binding while controlling the interaction from the View. This is useful when the content comes from some form of (external) data source and needs to be loaded dynamically. Here, we keep the user interaction and the business logic strictly separate.

For this approach, we will need to do the following:

1. Create a simple Model and a ViewModel

2. Add a VerticalStackLayout and use MAUI's BindableLayout to dynamically bind it to the ViewModel

3. Provide an x:Name to the VerticalStackLayout to be able to access it from the code-behind

4. Add a DataTemplate using the Expander as the templated control

5. Add an event handler for the HeaderTapped event to the code-behind which will be used by each Expander instance

The Model and ViewModel can be very simple, we basically just need a List of objects to bind to. In this case, I chose to create a simple PersonTuple Model class as well as a HybridAccordionViewModel as the ViewModel. The PersonTuple is just a tuple of two strings and the HybridAccordionViewModel simply holds an observable property which is a List<PersonTuple>:

public class PersonTuple : Tuple<string, string>
{
    public PersonTuple(string item1, string item2) : base(item1, item2) { }
}

public partial class HybridAccordionViewModel : ObservableObject
{
    [ObservableProperty]
    private List<PersonTuple> _people;

    public HybridAccordionViewModel()
    {
        People = new List<PersonTuple>
        {
            new("Jane", "Wants to be an actress"),
            new("John", "Wants to be a rock musician"),
            new("Jasmine", "Wants to be a heart surgeon")
        };
    }
}

With this set up, the next thing we need is the View. The XAML in this example is much shorter, because we dynamically create the Expander instances via the BindableLayout.ItemTemplate which is attached to a VerticalStackLayout:

<VerticalStackLayout
  x:Name="AccordionLayout"
  Spacing="6"
  BindableLayout.ItemsSource="{Binding People}">
  <BindableLayout.ItemTemplate>
    <DataTemplate x:DataType="{x:Type hybrid:PersonTuple}">

      <maui:Expander
        Animated="True"
        HeaderTapped="Expander_OnHeaderTapped">
        <maui:Expander.HeaderContent>
          <Grid
            HeightRequest="80"
            BackgroundColor="Orange">
            <Label
              Text="{Binding Item1}"
              FontSize="Title"
              VerticalOptions="Center"
              HorizontalOptions="Center" />
          </Grid>
        </maui:Expander.HeaderContent>
        <Grid
          HeightRequest="200"
          BackgroundColor="DarkSlateGray">
          <Label
            Text="{Binding Item2}"
            VerticalOptions="Center"
            HorizontalOptions="Center" />
        </Grid>
      </maui:Expander>

    </DataTemplate>
  </BindableLayout.ItemTemplate>
</VerticalStackLayout>

Here, we're telling the DataTemplate that the data type (indicated by x:DataType) is the previously created PersonTuple class (which is also useful for compiled bindings). Then, we can bind to Item1 and Item2 of the tuple, the first item holds the name and the second one some additional info about a person.

Last, but not least, we need to set up the event handler (which is identical to the one from the previous example), and set the BindingContext in the code-behind of the Page to the ViewModel:

public partial class HybridAccordionPage : ContentPage
{
    public HybridAccordionPage()
    {
        InitializeComponent();
        BindingContext = new HybridAccordionViewModel();
    }

    private void Expander_OnHeaderTapped(object sender, ExpandedEventArgs e)
    {
        if (sender is not Expander expander)
        {
            return;
        }

        foreach (var child in AccordionLayout.Children)
        {
            if (child is not Expander other)
            {
                continue;
            }

            if (other != expander)
            {
                other.IsExpanded = false;
            }
        }
    }
}

Just like that, we're already done with the hybrid approach, which combines data-binding and view-based control over the state of the Expander instances.

Like in the previous example, the finished accordion should look like this:

Version 3: Data binding-controlled accordion

In this third and last example, the accordion will be built by populating the content dynamically while also controlling the entire interaction from within the ViewModel using data binding only. This is useful when the user interaction directly affects the business logic, e.g. by updating the status of an object (such as item selection). The beauty of this approach is that the ViewModel still doesn't know anything about the user interaction or the View, at all - thanks to the MVVM pattern and data binding.

In order to achieve this, we need do these things:

1. Create a Model with a Selected property

2. Create a simple ViewModel that holds a list of objects to bind to

3. Add a SelectItemCommand to the ViewModel to update the item selection

4. Add a VerticalStackLayout and use the BindableLayout to dynamically bind to the ViewModel

5. Add a DataTemplate using the Expander as the templated control

6. Bind the IsExpanded property of the Expander to the Selected property of the Model class

The Model class I have created for this is called PersonModel and has three observable properties:

public partial class PersonModel : ObservableObject
{
    [ObservableProperty]
    private string _name;

    [ObservableProperty]
    private string _description;

    [ObservableProperty]
    private bool _selected;
}

This is then used in the ViewModel, similar to the previous example. The ViewModel is called DataBindingAccordionViewModel, and it holds a List<PersonModel and exposes the SelectItemCommand mentioned above:

public partial class DataBindingAccordionViewModel : ObservableObject
{
    [ObservableProperty]
    private List<PersonModel> _people;

    public DataBindingAccordionViewModel()
    {
        People = new List<PersonModel>
        {
            new()
            {
                Name = "Jane",
                Description = "Wants to be an actress"
            },
            new()
            {
                Name = "John",
                Description = "Wants to be a rock musician"
            },
            new()
            {
                Name = "Jasmine",
                Description = "Wants to be a heart surgeon"
            },
        };
    }

    [RelayCommand]
    private void SelectItem(PersonModel item)
    {
        item.Selected = !item.Selected;

        foreach (var person in People)
        {
            if (person != item)
            {
                person.Selected = false;
            }
        }
    }
}

Note: The SelectItemCommand is auto-generated from the SelectItem() method via the [RelayCommand] code generator attribute

The XAML of the View looks quite similar to the previous example, but this time there is no event handler and instead the Command property of the Expander binds to the SelectItemCommand of the ViewModel and the current instance of the PersonModel is used as the argument for the CommandParameter property of the Expander. Additionally, the IsExpanded property of the Expander binds to the Selected property of the Model:

<VerticalStackLayout
  Spacing="6"
  BindableLayout.ItemsSource="{Binding People}">
  <BindableLayout.ItemTemplate>
    <DataTemplate x:DataType="dataBinding:PersonModel">

      <maui:Expander
        Animated="True"
        Command="{Binding SelectItemCommand, Source={RelativeSource AncestorType={x:Type dataBinding:DataBindingAccordionViewModel}}}"
        CommandParameter="{Binding .}"
        IsExpanded="{Binding Selected}">
        <maui:Expander.HeaderContent>
          <Grid
            HeightRequest="80"
            BackgroundColor="Orange">
            <Label
              Text="{Binding Name}"
              FontSize="Title"
              VerticalOptions="Center"
              HorizontalOptions="Center" />
          </Grid>
        </maui:Expander.HeaderContent>
        <Grid
          HeightRequest="200"
          BackgroundColor="DarkSlateGray">
          <Label
            Text="{Binding Description}"
            VerticalOptions="Center"
            HorizontalOptions="Center" />
        </Grid>
      </maui:Expander>

    </DataTemplate>
  </BindableLayout.ItemTemplate>
</VerticalStackLayout>

In the code-behind, we only need to set the BindingContext to the ViewModel:

public DataBindingAccordionPage()
{
    InitializeComponent();
    BindingContext = new DataBindingAccordionViewModel();
}

Now, when we run this, it should look like this, but this time, everything is entirely controlled by the ViewModel:

Conclusions and Next Steps

It's incredibly easy to enhance the user experience of your .NET MAUI app by using Expanders and Accordion controls. I have demonstrated three different approaches for the implementation of an Accordion that you can apply based on the requirements and use cases of your app, so that your app users will spend less time scrolling and can find the content they're looking for faster.

I hope this is useful for you. If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository of this post and also check out my MAUI Samples repository, so you don't miss out on any future posts and developments.

Attributions

Title photo by Dominik Vanyi on Unsplash

In this article, I will show you how to leverage MAUI's built-in dependency injection capabilities to provide dependencies to your Views and ViewModels.

I absolutely love the Dependency Inversion Principle (DIP), it is by far my favorite principle from SOLID, and .NET MAUI makes it very easy to apply Inversion of Control (IoC) with it, because as a first class-citizen, Dependency Injection (DI) already comes built-in with Shell apps. Like ASP.NET Core, .NET MAUI also uses .NET's Dependency Injection pattern.

SOLID stands for:

• SRP = Single Responsibility Principle

• OCP = Open/Closed Principle

• LSP = Liskov Substitution Principle

• ISP = Interface Segregation Principle

• DIP = Dependency Inversion Principle

Uff, a lot of fancy acronyms and buzz words. While DIP, IoC and DI are not all exactly the same, they express and address different aspects of the same idea: Loose coupling. Instead of having hard dependencies in our code, which make it unflexible and difficult to maintain and test, the idea is to invert the control of the dependencies by hiding implementation details and only depending on interfaces or contracts instead.

Specific implementations of those dependencies are then injected. This can be done via constructor arguments, IoC containers, the builder pattern or specific setter methods. In this blog post, we will explore how to leverage Shell's built-in dependency injection, which uses a combination of the first three approaches.

This is entirely optional, of course. If you want, you can also use any other IoC container, there are plenty of great DI frameworks and IoC containers out there for .NET, like TinyIoC, SimpleInjector and Prism.

As always, you can find the code from this blog post in the sample repository on GitHub.

Note: This post focusses on dependency injection in .NET MAUI and is not a general discussion or tutorial about what DI is. If you want to learn more about DI patterns (and anti-patterns) and good software design in general, I highly recommend reading "Dependency Injection - Principles, Practices and Patterns" by Steven van Deursen and Mark Seemann.

Setting

For this example, we'll assume that we have a MainPage, a MainViewModel and an IDeviceService which is consumed by the MainViewModel. The MainViewModel somehow needs to be passed into the MainPage to serve as its BindingContext and the IDeviceService needs to be passed into the MainViewModel.

One of the most common ways to inject dependencies is via constructor injection, which we will mainly focus on today. Typically, this would look as follows:

public MainPage(MainViewModel viewModel)
{
    InitializeComponent();
    BindingContext = viewModel;
}

Here, we have defined the MainPage constructor which takes in a MainViewModel as a parameter, so our dependency gets injected via the constructor and can then be used in the class.

Similarly, the MainViewModel constructor takes in an instance of an IDeviceService implementation:

private readonly IDeviceService _deviceService;

public MainViewModel(IDeviceService deviceService)
{
    _deviceService = deviceService;
}

Without the use of a DI service, we would have to manually set up all the constructor calls and somehow manage which dependency goes where. For example, we would have to do the following in order to instantiate the MainPage in the App.xaml.cs:

public App()
{
    InitializeComponent();
    var deviceService = DeviceService.Instance;
    var viewModel = new MainViewModel(deviceService);
    MainPage = new MainPage(viewModel);
}

This works perfectly fine as long as the app is small and doesn't use Shell; but, what if we have many different pages and want to use Shell to build our app hierarchy using routes and <ShellContent> objects?

One thing we definitely couldn't do is the following, because in XAML you cannot provide constructor parameters to a DataTemplate:

<Shell
  x:Class="MauiSamples.AppShell"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
  xmlns:views="clr-namespace:MauiSamples.Views">

  <TabBar>
    <Tab Title="Home">
      <ShellContent
        Title="Home"
        ContentTemplate="{DataTemplate views:MainPage}"
        Route="MainPage" />
    </Tab>
</Shell>

The MainPage takes a MainViewModel instance as a constructor parameter, but we cannot provide that in XAML.

This is where MAUI's built-in dependency injection comes in. It uses its own IoC container and performs the resolution of the dependencies for us automatically, provided that we register all the required dependencies.

So, let's have a look at how registration works.

Registration

In MAUI, we use the builder pattern, which is a common approach for app configuration in modern .NET applications and technologies. It makes the configuration of features and dependencies very straightforward and keeps it all in a single place.

The MauiProgram.cs is the place where the app is usually configured and built. There, you will find something like this:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        })

    return builder.Build();
}

The builder object provides a Services collection where all dependencies get registered. This is how we let MAUI know that we have classes that have dependencies or that are dependencies for other classes.

Registering a new dependency is very easy and just takes a single line of code anywhere before the return builder.Build() call:

builder.Services.AddSingleton<MainViewModel>();

return builder.Build();

The code above is used to register the MainViewModel class. However, we also need to register the MainPage as well for the automatic resolution to work:

builder.Services.AddSingleton<MainViewModel>();
builder.Services.AddSingleton<MainPage>();

return builder.Build();

So, how does resolution work?

Resolution

There are two types of dependency resolution in MAUI apps: automatic and explicit.

Automatic resolution uses constructor injection without explicitly requesting the dependency from the IoC container, while explicit resolution occurs on demand by explicitly requesting a specific dependency from the IoC container.

Automatic Resolution with Shell

As we've already seen above, this type of resolution works - as the name suggests - completely automatically by providing the required dependencies to the constructor:

private readonly IDeviceService _deviceService;

public MainViewModel(IDeviceService deviceService)
{
    _deviceService = deviceService;
}

Shell takes care of this for you as long as you register the dependency's type as well as the type that uses this dependency, e.g. MainViewModel and an implementation of IDeviceService.

Note: Only Shell apps support automatic constructor injection.

This is pretty cool, because we do not have to pass around our dependencies ourselves, Shell takes care of it and manages the lifetime and handles the injection for us.

Explicit Resolution

If your class only exposes a parameterless constructor, then Shell cannot inject dependencies automatically for you. Or if you don't use Shell, because you want to use a FlyoutPage or implement navigation completely manually without using routes, then you also cannot use the automatic resolution mechanism. Therefore, we need an explicit way to resolve dependencies.

Note: I have included the following approaches to show that they are viable options. However, if you need to resolve dependencies manually in many different places or you have complex scenarios with deep dependency trees, you may want to use an independent DI framework or IoC container.

Accessing the IServiceProvider

Imagine our MainViewModel for some reason doesn't provide a constructor with the IDeviceService parameter:

private readonly IDeviceService _deviceService;

public MainViewModel() { }

In that case, we need to resolve the dependency manually by directly accessing the IoC container, e.g. in the constructor. One way to do this is the following, where we access the IServiceProvider (i.e. the Services object) via the MauiContext provided by our current MainPage:

private readonly IDeviceService _deviceService;

public MainViewModel()
{
    _deviceService = Application.Current.MainPage
        .Handler
        .MauiContext
        .Services  // IServiceProvider
        .GetService<IDeviceService>();
}

One downside of this approach is that we have a dependency on the Application and the MainPage in our MainViewModel, which kind of defeats the purpose of using IoC in .NET applications following the MVVM pattern. This also makes automatic testing tricky, because if we want write unit tests for our MainViewModel, we shouldn't have any dependencies on the Application or the MainPage.

Alternatively, we can also pass down the IServiceProvider via the constructor (either through automatic resolution or by manually injecting it in the constructor call) and then resolve the required dependencies manually:

private readonly IDeviceService _deviceService;
private readonly IAudioService _audioService;

public MainViewModel(IServiceProvider provider)
{
    _deviceService = provider.GetService<IDeviceService>();
    _audioService = provider.GetService<IAudioService>();
}

This slightly different approach allows us to keep the constructor signature short and allows us to use mocking frameworks with unit tests. This approach also works with Shell's automatic resolution without having to manually register the IServiceProvider.

😓 That'll work, but it's not pretty and we have to always pass down the IServiceProvider. Isn't there a better way? As you may have guessed: There is. 🤩

ServiceHelper to the rescue!

If you don't want to or cannot use any constructor injection, then there is a better way to deal with the IServiceProvider, which is to create a static ServiceHelper class:

public static class ServiceHelper
{
    public static IServiceProvider Services { get; private set; }

    public static void Initialize(IServiceProvider serviceProvider) => 
        Services = serviceProvider;

    public static T GetService<T>() => Services.GetService<T>();
}

Then, in your MauiProgram.cs you just need to call the Initialize method and pass in the IServiceProvider instance that the MauiApp class exposes once it was built:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    // ...

    builder.Services.AddSingleton<IDeviceService>(DeviceService.Instance);
    builder.Services.AddSingleton<MainViewModel>();
    builder.Services.AddSingleton<MainPage>();

    var app = builder.Build();

    //we must initialize our service helper before using it
    ServiceHelper.Initialize(app.Services);

    return app;
}

Then, in order to resolve the dependencies, you can access the static helper and call the GetService<T>() method:

private readonly IDeviceService _deviceService;
private readonly IAudioService _audioService;

public MainViewModel()
{
    _deviceService = ServiceHelper.GetService<IDeviceService>();
    _audioService = ServiceHelper.GetService<IAudioService>();
}

The beauty of this approach is that we don't need to pass down the IServiceProvider in every single constructor call when we're not using constructor parameters and at the same time we can configure the ServiceHelper using a fake or mock implementation of IServiceProvider when writing unit tests.

Awesome! 🏆

Note: I am aware that the ServiceHelper is an implementation of the Service Locator pattern, which is often regarded as an anti-pattern. However, in certain scenarios, especially with regards to .NET-baseed UI technologies, the Service Locator pattern is a necessity.

Lifetime of Dependencies

As you may have noticed before, we have so far registered the dependencies using a method called AddSingleton<T>(). This group of methods can be used to register a single instance (hence singleton) of a class, which means that every time a dependency gets resolved, the exact same instance will be provided by the IoC container during the entire lifetime of the app.

There are three different lifetime modes for dependencies:

• Singleton

• Transient

• Scoped

The first one, as already mentioned, registers a single instance which will be kept alive during the entire lifetime of our app. This is done via the AddSingleton<T>() methods.

Note: Here, the term singleton does not mean the Singleton Design Pattern.

The second mode is called transient and means that whenever a dependency registered with this mode gets resolved, a fresh instance of the registered type is provided. Transients can be registered using the AddTransient<T>() method(s).

Last but not least, there is the scoped mode, which is a little tricky to understand. Basically, scoped services or dependencies share the same lifetime as the Page or object that resolves them. If a non-singleton Page is closed or an object goes out of scope, so does the scoped dependency. This means resolving the same dependency multiple times within the same scope will always yield the same instance, while resolving the same dependency in different scopes will yield different instances. This can be particularly useful when components (e.g. Views) of the same Page share the same dependencies while different Pages should each have their own instance. Scoped dependencies can be registered using the AddScoped<T>() method(s).

Note: There are multiple methods for each type, because you can register contracts (e.g. interfaces and abstract base classes) together with a specific type as well as instances and factories.

Personally, I do not need the scoped mode very often, I prefer the singleton and transient modes as they are sufficient for the more common scenarios.

Common Pitfalls and Gotchas!

There are a couple of common mistakes and issues that I have noticed some people struggling with over the last months, there have been various Stack Overflow questions related to these problems. To make your life easier, I want to address a couple of them here.

Always register all dependencies

Make sure to always register all dependencies including any classes that require these dependencies, otherwise you may see strange exceptions and errors.

One common mistake that I see people make very often is that they register their ViewModels, but they don't register the Pages that use those ViewModels in their constructor and then they see the following runtime error:

System.MissingMethodException: 'No parameterless constructor defined for type 'MauiSamples.Views.MainPage'.'

This can be resolved by registering the MainPage along with the MainViewModel:

builder.Services.AddSingleton<MainViewModel>();
// do NOT forget to also register the MainPage!
builder.Services.AddSingleton<MainPage>();

The same applies to any other dependencies that are automatically resolved. If you have a ViewModel that takes a dependency as a constructor parameter, then you need to register the ViewModel and all of its dependencies.

Automatic constructor injection

Automatic resolution only works in the context of Shell, because Shell takes care of construction for you. If you use constructor injection without Shell by manually creating instances of your classes through explicit constructor calls, then you need to specify the dependencies in the constructor call yourself.

For example, when you use automatic resolution in your MAUI Shell app, but you also write unit tests for your ViewModel, which has no parameterless constructor, then you need to provide the dependencies (e.g. by using mocks or fakes) yourself:

[Test]
public void SomeMethod_ArgumentsAreValid_ReturnsTrue()
{
    //arrange
    var deviceServiceMock = new Mock<IDeviceService>();
    var vm = new MainViewModel(deviceServiceMock.Object);

    //act
    var result = vm.SomeMethod(1,2,3);

    //assert
    Assert.That(result, Is.True);
}

The same applies when you manually create Page instances instead of using routes, which then leads to the creation of a Navigation Stack, which is not governed by Shell.

Resolving unknown types

If you attempt to resolve a type that has not been registered, you will see an exception. My recommendation is to not "swallow" this exception by using a catch-all clause. Instead, you should let your app crash in this case, because mandatory dependencies are required for the correct functioning of an app and it's usually the developer's fault when the required dependencies don't get registered. Fail early, fail often is the premise here.

Adding dependencies during runtime

Unfortunately, it's not possible to register, replace or update dependencies during the lifetime of a .NET MAUI app, because the service collection cannot be modified after the application is built. Bummer. If you have a scenario where you need to modify the dependencies frequently, e.g. based on user settings, etc. then you can either register a service provider that can handle this for you or you can use a third-party DI framework like the ones I've mentioned earlier.

Conclusions and Next Steps

Dependency injection is a powerful first-class citizen in .NET MAUI and comes directly built-in, which is awesome, because we don't have to use any third-party frameworks or libraries, as long as we do not need to do anything beyond the restrictions and limitations of the built-in dependency injection mechanism.

Today, I have shown you how to leverage Shell's automatic constructor injection as well as ways to manually resolve dependencies. I might write another blog article on dependency injection and unit tests in .NET MAUI in the future. There are viable solutions to this problem, e.g. by mocking the IServiceProvider and using it with the static ServiceHelper class. Let me know if this is something you would like to read more about.

I hope this is useful for you. If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts and developments.

Many mobile applications come with their own, custom title styling. This is important, because the title bar (or navigation bar, I will use the terms interchangeably here) plays a vital role in brand recognition since it is visible at the top of an app.

In this blog post, I will show you how you can customize the navigation bar of a .NET MAUI Shell app. The goal is to add a custom font, title and some buttons to it. The final result will look like this:

You can find the example code for this blog post in my MAUI Samples repository.

Prerequisites

Before we can start with the customization of the TitleView, we need to add some fonts. I'm using MaterialIconsOutlined-Regular.otf for the icons (available in the Google Material Icons GitHub repository) and Strande2.ttf for the Title.

Adding font files couldn't be simpler in .NET MAUI, we just need to add them to the Resources/Fonts/ directory of our MAUI app project and register them:

It's not necessary to set the Build Action for each file to MauiFont separately, because this happens automatically as long as the files are added to the Fonts directory. We can see why this works when we edit the .csproj file, where we will find the following:

<!-- Custom Fonts -->
<MauiFont Include="Resources\Fonts\*" />

This means that adding the font files to the Fonts directory is all we need to do, they will be picked up as MauiFont files automatically.

Then, we just need to register the fonts in our MauiProgram.cs and we're good to go:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                fonts.AddFont("MaterialIconsOutlined-Regular.otf", "MaterialIconsOutlined-Regular");
                fonts.AddFont("MaterialIcons-Regular.ttf", "MaterialIcons-Regular");
                fonts.AddFont("Strande2.ttf", "Strande2");
            });

        return builder.Build();
    }
}

We can now access the fonts by their name (excluding the file extension). More on that a bit further down.

First, it's time to start with the customization of the TitleView.

Customizing the Title Bar

Let's start with the background color, then we'll customize the title and finally, we'll add some buttons.

Background Color

In a MAUI Shell app, we can access and control the style of the navigation bar in the root of any ContentPage.

In order to change the background color of the navigation bar, we can simply set the Shell.BackgroundColor to any valid value, either a named color (e.g. "DarkGreen") or a hex code (such as "#01AB67"):

<ContentPage
  x:Class="MauiSamples.Views.MainPage"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  Shell.BackgroundColor="DarkGreen">
  <!-- ... -->
</ContentPage>

This will give us the following:

Cool, we have a green background. Next, we'll change the font and text.

Title Font and Text

In a MAUI Shell app, you can set an entirely custom TitleView, which means that you can add all kinds of views into the TitleView, such as Layouts, Labels, Buttons, Images, and so on. In this blog post, I'll keep it simple, so we'll just add a HorizontalStackLayout with a single Label.

Since we've already added our custom font, we can now use that in the Label by setting the FontFamily="Strande2". We can set the custom TitleView like this by setting the Shell.TitleView property:

<Shell.TitleView>
  <HorizontalStackLayout VerticalOptions="Fill">
    <Label
      Text="Welcome to MAUI"
      FontFamily="Strande2"
      TextColor="White"
      VerticalTextAlignment="Center"
      VerticalOptions="Center"
      HeightRequest="50"
      FontSize="Medium" />
  </HorizontalStackLayout>
</Shell.TitleView>

Our TitleView now looks like this with a green background, as well as a custom font and title:

The only thing missing are the buttons. Let's do that next using ToolbarItems.

Toolbar Items

MAUI gives us different options to add buttons to the navigation bar. One of them would be to add more elements to the HorizontalStackLayout inside our custom TitleView. Another way is to use ToolbarItems, which is what we'll do for the buttons.

While adding Buttons and Images to the TitleView directly gives us more control over their appearance, especially their position, ToolbarItems have the advantage that they position themselves according to the order they are defined in. They are right-aligned by default, with the first item being the left-most. This means that new items will be added to the right, while existing items are shifted to the left.

ToolbarItems can either use text or icons. For icons, the ToolbarItem class comes with an IconImageSource property, which is of type ImageSource. This means that we can also use a FontImageSource to provide the icon for our buttons based on a custom font.

You can find more information on Icon Fonts in MAUI in the official documentation.

Let's add the first button using such a FontImageSource by using the MaterialIconsOutlined-Regular icon font:

<ContentPage.ToolbarItems>
  <ToolbarItem Command="{Binding SetLowBrightnessCommand}">
    <ToolbarItem.IconImageSource>
      <FontImageSource
        FontFamily="MaterialIconsOutlined-Regular"
        Glyph="&#xe51c;"/>
    </ToolbarItem.IconImageSource>
  </ToolbarItem>
</ContentPage.ToolbarItems>

The FontFamily property is used to select the icon font and the Glyph property is used to set select the specific icon. The ToolbarItem also supports binding to a Command from our ViewModel.

Note: Google offers a user-friendly cheat sheet to view the Material Symblos and Icons including their code points. The code point of the Glyph in this example is e51c. Glyphs are individual characters from a character set or font and use the "&#xCODE;" notation.

Adding the first ToolbarItem gives us the following:

As you can see, the ToolbarItem is completely right-aligned, we didn't have to specify the size or position for that.

Let's add another ToolbarItem below the first one in the XAML code to see what happens:

<ContentPage.ToolbarItems>
  <ToolbarItem Command="{Binding SetLowBrightnessCommand}">
    <ToolbarItem.IconImageSource>
      <FontImageSource
        FontFamily="MaterialIconsOutlined-Regular"
        Glyph="&#xe51c;"/>
    </ToolbarItem.IconImageSource>
  </ToolbarItem>
  <ToolbarItem Command="{Binding SetHighBrightnessCommand}">
    <ToolbarItem.IconImageSource>
      <FontImageSource
        FontFamily="MaterialIconsOutlined-Regular"
        Glyph="&#xe518;"/>
    </ToolbarItem.IconImageSource>
  </ToolbarItem>
</ContentPage.ToolbarItems>

This gives us the following result:

As expected, the first ToolbarItem shifted to the left, the second one got added right to it and the entire collection of ToolbarItems remains right-aligned.

Customizing the Toolbar Items

Each ToolbarItem can be configured based on your needs. For example, you can set different colors for each FontIconSource and even change the size of each:

<ContentPage.ToolbarItems>
  <ToolbarItem Command="{Binding SetLowBrightnessCommand}">
    <ToolbarItem.IconImageSource>
      <FontImageSource
        FontFamily="MaterialIconsOutlined-Regular"
        Glyph="&#xe51c;"
        Color="LightBlue"
        Size="20"/>
    </ToolbarItem.IconImageSource>
  </ToolbarItem>
  <ToolbarItem Command="{Binding SetHighBrightnessCommand}">
    <ToolbarItem.IconImageSource>
      <FontImageSource
        FontFamily="MaterialIconsOutlined-Regular"
        Glyph="&#xe518;"
        Color="LightPink"
        Size="32"/>
    </ToolbarItem.IconImageSource>
  </ToolbarItem>
</ContentPage.ToolbarItems>

This will result in something like below:

As you can see, those items have different sizes and colors - pretty cool!

Secondary Toolbar Items

Adding more and more items would eventually leave no more space for the title, which would at some point get covered by ToolbarItems:

Therefore, if we wanted to add more items, we can do so by placing them into a secondary toolbar menu. Secondary ToolbarItems can be defined by setting their Order property to Secondary:

  <ContentPage.ToolbarItems>
    <!-- ... -->
    <ToolbarItem
      Order="Secondary"
      Text="Item 3" />
    <ToolbarItem
      Order="Secondary"
      Text="Item 4" />
    </ToolbarItem>
  </ContentPage.ToolbarItems>

If secondary ToolbarItems are defined, a little burger menu icon appears on the right of the tool bar:

The secondary items only become visible after tapping the burger menu:

Note: Secondary-level ToolbarItems do not support icons, only text will be shown.

And that's it, we're done. 🏆 Awesome, you just learned how to customize the TitleView of a .NET MAUI Shell app! 💪

Conclusion and next steps

Using custom fonts, a custom TitleView and some ToolbarItems, we can quickly mesh up our own customizable title bar to make our app stand out. I hope you learned something new today.

There are several different ways to customize the look and feel of the navigation bar (or title bar) in a MAUI app and I've just shown you one way of doing it with the least amount of effort. Platform-specific customizations are also possible, but that would require an entire article on its own (let me know if you're interested in such an article!).

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts and developments.

When developing mobile apps user experience (UX) is key. Today, we will have a look at the role device orientation plays for user experience and how you can take advantage of .NET MAUI's built-in capabilities.

While Portrait mode has become the default mode for mobile apps, because we often stare at the screen while holding the device in one hand, it may be a good idea to offer a Landscape version of your User Interface (UI) as well. Landscape mode greatly increases the user experience of an app, because the screen width is just too small in Portrait mode when dealing with images, videos and other types of horizontally organized graphics and data. Landscape mode enables your users to view such information and data in a more user-friendly and orientation optimized way.

In this blog article, I will how you how to respond to the device orientation in your .NET MAUI app using state triggers and update the layout entirely in XAML markup - no C# code required. As always, you can find the full code for this post in my sample repository.

Note: The concepts in this article are largely applicable to Xamarin.Forms as well.

Portrait and Landscape

Let's have a look at the sample app, which I have extended with a page that displays a video (using the MediaElement from the Community Toolkit) and two custom buttons, one to play and another one to pause the video.

Portrait Mode:

When the device is in Portrait mode, the page looks fine, the video takes up the entire width of the screen and the buttons are located below the video, as expected.

Landscape Mode:

In Landscape mode, however, the video is extremely small and the buttons are still stacked horizontally below the video, which doesn't look great and provides a poor user experience.

This happens, because the same Layout is used for both Portrait and Landscape. Instead, let's move the video to the left side of the screen and stack the buttons vertically on the right side when the device is in Landscape mode to look like this:

First, let's have a look at the layout of the page and then make a few changes to it to achieve the desired result.

Page Layout

I have used a Grid to place the video at the top and the buttons at the bottom of the page, where the top row takes up one third of the available space and the bottom row takes up two thirds of the available space by defining them as follows: RowDefinitions="*,2*".

The MediaElement, which acts as the video player, is placed into the first row, first column of the Grid by setting the attached properties Grid.Row="0" and Grid.Column="0". This will be useful later on.

The buttons are located inside of a StackLayout which has its Orientation property set to "Horizontal", which means that they will be placed next to each other horizontally. The StackLayout itself is placed in the second row, first column of the Grid.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:views="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MauiSamples.Views.VideoPage"
             Shell.NavBarIsVisible="False">

  <Grid
    RowDefinitions="*,2*"
    ColumnDefinitions="*">

    <views:MediaElement
      Grid.Row="0"
      Grid.Column="0"
      x:Name="VideoPlayer"
      HorizontalOptions="Fill"
      Source="https://github.com/ewerspej/maui-samples/blob/main/assets/frog113403.mp4?raw=true"
      ShouldShowPlaybackControls="False" />

    <StackLayout
      Grid.Row="1"
      Grid.Column="0"
      VerticalOptions="Center"
      HorizontalOptions="Center"
      Spacing="20"
      Orientation="Horizontal">
      <Button
        HorizontalOptions="Center"
        Text="Play"
        Pressed="OnPlayPressed" />
      <Button
        HorizontalOptions="Center"
        Text="Pause"
        Pressed="OnPausePressed" />
    </StackLayout>

  </Grid>
</ContentPage>

This layout currently only looks great in Portrait mode, but not in Landscape as we've seen above. Let's fix it so that it looks prettier and more user friendly.

The best part is, we don't need to write a single line of C# code for this and we also don't need completely separate layouts, either. Instead, we can simply modify the existing layout based on the device orientation using styles and triggers. Let me show you how to do that next.

Hello, OrientationStateTrigger!

Time to introduce you to a type of trigger called OrientationStateTrigger. This trigger comes built-in with .NET MAUI (and Xamarin.Forms) and allows you to use Visual States and Styles to modify the visual appearance as well as the layout properties of a View.

Defining Styles and Triggers

For each Visual Element that we need to update based on the device orientation, we can add a Style inside of a ResourceDictionary which we add to our VideoPage:

<ContentPage.Resources>
  <ResourceDictionary>
    <Style TargetType="Grid" x:Key="VideoGridStyle">
    </Style>
    <Style TargetType="StackLayout" x:Key="ButtonStackStyle">
    </Style>
  </ResourceDictionary>
</ContentPage.Resources>

Inside of these styles, we can define the different Visual States that we want to use and attach an OrientationStateTrigger to each. These triggers are then used to apply the associated styles.

Each style receives a setter that defines the different visual states, in our case those visual states will be "Portrait" and "Landscape". Then, inside of each visual state, we can add the appropriate OrientationStateTrigger for the applicable device orientation:

<ContentPage.Resources>
  <ResourceDictionary>
    <Style TargetType="Grid" x:Key="VideoGridStyle">
      <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
          <VisualStateGroup>
            <VisualState x:Name="Portrait">
              <VisualState.StateTriggers>
                <OrientationStateTrigger Orientation="Portrait" />
              </VisualState.StateTriggers>
            </VisualState>
            <VisualState x:Name="Landscape">
              <VisualState.StateTriggers>
                <OrientationStateTrigger Orientation="Landscape" />
              </VisualState.StateTriggers>
            </VisualState>
          </VisualStateGroup>
        </VisualStateGroupList>
      </Setter>
    </Style>
    <!-- ... -->
  </ResourceDictionary>
</ContentPage.Resources>

Once the triggers are setup, the setters of the visual states for our Layout elements can be added. We'll do this for the Grid and the StackLayout styles, one after the other, next.

Visual State Setters for the Grid

For our Grid, we need to change the RowDefinitions and ColumnDefinitions based on the device orientation. Instead of having two rows and a single column, we now need a single row and two columns, which we can achieve by adding the following setters:

<ContentPage.Resources>
  <ResourceDictionary>
    <Style TargetType="Grid" x:Key="VideoGridStyle">
      <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
          <VisualStateGroup>
            <VisualState x:Name="Portrait">
              <VisualState.StateTriggers>
                <OrientationStateTrigger Orientation="Portrait" />
              </VisualState.StateTriggers>
              <VisualState.Setters>
                <Setter Property="RowDefinitions" Value="*,2*" />
                <Setter Property="ColumnDefinitions" Value="*" />
              </VisualState.Setters>
            </VisualState>
            <VisualState x:Name="Landscape">
              <VisualState.StateTriggers>
                <OrientationStateTrigger Orientation="Landscape" />
              </VisualState.StateTriggers>
              <VisualState.Setters>
                <Setter Property="RowDefinitions" Value="*" />
                <Setter Property="ColumnDefinitions" Value="2*,*" />
              </VisualState.Setters>
            </VisualState>
          </VisualStateGroup>
        </VisualStateGroupList>
      </Setter>
    </Style>
    <!-- ... -->
  </ResourceDictionary>
</ContentPage.Resources>

Visual State Setters for the StackLayout

The StackLayout on the other hand needs to change not only its orientation, but also its location inside of the Grid based on the device orientation.

For Portrait mode, the Orientation property must be set to "Horizontal" while it needs to be set to "Vertical" in Landscape mode. In Portrait mode, the StackLayout will be in the second row, first column of the Grid, while it needs to be in the first row, second column of the Grid in Landscape mode. We can achieve this by defining the following setters for the StackLayout:

<ContentPage.Resources>
  <ResourceDictionary>
    <!-- ... -->
    <Style TargetType="StackLayout" x:Key="ButtonStackStyle">
      <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
          <VisualStateGroup>
            <VisualState x:Name="Portrait">
              <VisualState.StateTriggers>
                <OrientationStateTrigger Orientation="Portrait" />
              </VisualState.StateTriggers>
              <VisualState.Setters>
                <Setter Property="Orientation" Value="Horizontal" />
                <Setter Property="Grid.Row" Value="1" />
                <Setter Property="Grid.Column" Value="0" />
              </VisualState.Setters>
            </VisualState>
            <VisualState x:Name="Landscape">
              <VisualState.StateTriggers>
                <OrientationStateTrigger Orientation="Landscape" />
              </VisualState.StateTriggers>
              <VisualState.Setters>
                <Setter Property="Orientation" Value="Vertical" />
                <Setter Property="Grid.Row" Value="0" />
                <Setter Property="Grid.Column" Value="1" />
              </VisualState.Setters>
            </VisualState>
          </VisualStateGroup>
        </VisualStateGroupList>
      </Setter>
    </Style>
  </ResourceDictionary>
</ContentPage.Resources>

Applying the Styles

Last, but not least, we need to apply the styles that we just defined to the Grid and the StackLayout in our page. Note that the styles are named, which means that they must be explicitly assigned to a visual element in order to take effect:

<Grid
  Style="{StaticResource VideoGridStyle}">

  <views:MediaElement
    Grid.Row="0"
    Grid.Column="0"
    Margin="0"
    x:Name="VideoPlayer"
    HorizontalOptions="Fill"
    Source="https://github.com/ewerspej/maui-samples/blob/main/assets/frog113403.mp4?raw=true"
    ShouldShowPlaybackControls="False" />

  <StackLayout
    VerticalOptions="Center"
    HorizontalOptions="Center"
    Spacing="20"
    Style="{StaticResource ButtonStackStyle}">
    <Button
      HorizontalOptions="Center"
      Text="Play"
      Pressed="OnPlayPressed" />
    <Button
      HorizontalOptions="Center"
      Text="Pause"
      Pressed="OnPausePressed" />
  </StackLayout>

</Grid>

Important: In order to apply the styles correctly, we need to make some modifications to the existing views in our page:

The RowDefinitions and ColumnDefinitions assignments of the Grid will be removed, just like the Orientation as well as the Grid.Row and Grid.Column settings of the StackLayout. This is necessary, because property setters that are applied directly on a VisualElement always take precedence over any applied styles, which would prevent the OrientationStateTriggers to update these properties using the defined styles.

The MediaElement itself does not receive any styles or additional property setters, because it already is set up correctly for both device orientations, which is why it keeps its original settings for Grid.Row and Grid.Column (remember when I wrote further up that setting both row and column properties will be useful later on - this is later on). It will always remain in the first row, first column - independent of the device orientation. This way, we can keep things simple.

Result

Now, when we run the app again and rotate the device into Landscape mode, the video will be located on the left side taking up much of the available vertical space, while the buttons are now stacked vertically on the right:

🏆 Awesome, this looks so much better! OrientationStateTrigger FTW! 💪

Conclusion and next steps

Using state triggers and styles, we can easily add responsive layouts to our app based on the device orientation and thus offer a rich user experience for both Portrait and Landscape modes - entirely in XAML, no C# code required.

Combining this approach with some other tricks as well as some platform-specific code, we can even build immersive user experiences, such as full-screen mode, which requires some additional work and will be covered in a separate article.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts and developments.

Welcome to the third part of my mini-series about MVVM Source Generators for C# .NET and the awesomeness of the MVVM Community Toolkit. So far, we have seen how we can save ourselves from writing too much boilerplate code when applying the MVVM pattern in .NET-based app technologies and UI frameworks.

In this part, I will give a short overview of yet another two amazing Source Generators which can be used to control the executability of Commands. In classic MVVM without Source Generators this would usually be done using the CanExecute predicate of a Command, which enables or disables it. Even with Source Generators you can still achieve exactly the same behavior as you could with classic MVVM implementations.

In this scenario, we do not actually save as much boilerplate code as with the other Source Generators that I have explored previously. However, the attributes we will use are required in situations where you need to enable and disable Commands based on specific conditions, such as the validity of the CommandParameter or of properties in the ViewModel when using Source Generators.

Special thanks to my colleague and friend Marco Seraphin for pointing out that this topic would be a great addition to my blog. Marco has inspired this article and has helped by reviewing it.

Like in my previous posts on the topic, I am using a .NET MAUI project (check out the sample repository) to demonstrate the functionality, but since the MVVM Community Toolkit is independent from UI frameworks, the same things apply to technologies like Windows Presentation Foundation (WPF) and Xamarin.Forms.

Setting

I am reusing the project from the sample repository with the address label printing functionality. In the previous post I have added an ActivityIndicator as well as a Stepper control to the project to demonstrate busyness using AsyncRelayCommand.

If you remember from before, the Button to trigger the PrintAddressCommand was always enabled, but nothing would happen if the number of copies was set to 0. Since Commands can have a CanExecute predicate, which is used to determine whether they can be executed or not, they can also be used to enable and disable buttons automatically.

So, for the updated setting, I want the Button only to be enabled when the Command is actually executable, otherwise it should be disabled and thus be grayed out when the number of copies is 0 and the address is empty:

Therefore, I have added a new method to the AddressViewModel which can be used as the CanExecute predicate for the PrintAddressCommand:

private bool CanPrint(string address) => Copies > 0 && !string.IsNullOrWhiteSpace(address);

This method checks if the argument that is passed into the Command is valid (for simplicity, I am only checking for null and whitespaces or an empty string) and if the number of copies to print is larger than 0.

When using the CanPrint() method as a predicate in the classic version of the AddressViewModel, the Command would then look like follows:

private IAsyncRelayCommand _printAddressCommand;
public IAsyncRelayCommand PrintAddressCommand => _printAddressCommand ??= new AsyncRelayCommand<string>(PrintAddressAsync, canExecute: CanPrint);

Our Button in the XAML of our UI has also been updated to pass in the address as a CommandParameter:

<Button
    Command="{Binding PrintAddressCommand}"
    CommandParameter="{Binding FullAddress}"
    Text="Print Address" />

In this case, I am simply passing in the FullAddress property.

Note: I have used the FullAddress property as a CommandParameter only for demonstration purposes. Since it's a property of the same ViewModel as the Command, I could have also directly accessed the property inside of the CanPrint() method instead of passing it in.

This already suffices to enable and disable the Button automatically, we cannot use the IsEnabled property of the Button in this setting and it's also not required.

Important: In .NET MAUI and Xamarin.Forms, you should not use the IsEnabled property when using Commands, because it will automatically be overridden when binding to a Command. Find more information in the official documentation.

Controlling Executability

Generally, the CanExecute predicate is only evaluated by the Command during instantiation or when an argument is passed to the Command via the CommandParameter property. In the latter case, the CanExecute predicate is evaluated each time that the CommandParameter, which our Button binds to, changes.

Important: The method which is used for the predicate must return a bool and optionally may have exactly one input parameter which must correspond to the CommandParameter.

However, there are also scenarios in which the predicate depends on properties which are not passed in as an argument of the CommandParameter. In these situations, we need to manually inform the Command that something has changed and that its executability should be re-evaluated.

Let's explore how this is usually done using classic MVVM in .NET and then let's have a look at how this can be done using the previously introduced Source Generators.

Using Classic MVVM

When using the classic MVVM approach to update the Command and re-evaluate its executability, the ViewModel (stripped down to the relevant bits only) would look as follows:

private IAsyncRelayCommand _printAddressCommand;
public IAsyncRelayCommand PrintAddressCommand => _printAddressCommand ??= new AsyncRelayCommand<string>(PrintAddressAsync, canExecute: CanPrint);

private async Task PrintAddressAsync(string address)
{
    await Task.Delay(TimeSpan.FromSeconds(2));
    OnPrintAddress?.Invoke(address);
}

private bool CanPrint(string address) => Copies > 0 && !string.IsNullOrWhiteSpace(address);

private int _copies;
public int Copies
{
    get => _copies;
    set
    {
        if (value == _copies)
        {
            return;
        }

        OnPropertyChanging();
        _copies = value;
        OnPropertyChanged();

        PrintAddressCommand.NotifyCanExecuteChanged();
    }
}

Here, we pass the CanPrint() method, which exists in both versions equally, as an argument to the Command's canExecute parameter. The CanExecute predicate of the Command is evaluated each time when the CommandParameter, the address string, changes and it is also re-evaluated when the Copies property changes, because the Command gets notified by calling NotifyCanExecuteChanged() on it.

This already isn't much code thanks to the NotifyCanExecuteChanged() method that the IRelayCommand interface provides.

Using MVVM Source Generators

Since the Source Generators largely take care of the implementation of properties and commands for us, we need a way to pass in the canExecute parameter to the Command. We also need a way to trigger an update on the Command to re-evaluate its executability. The first attribute might look familiar from prior usage and the second one also has similarities with another attribute that we've already explored before. It's time to look at [RelayCommand] again and then we'll do a short dive into [NotifyCanExecuteChangedFor].

Revisiting [RelayCommand]

In order to configure and update the executability of a Command via the canExecute parameter, the [RelayCommand] attribute comes with an optional property of type string?, which conveniently is called CanExecute and which is used to provide the name of the method that is used to evaluate the executability of the Command:

[RelayCommand(CanExecute = nameof(CanPrint))]
private async Task PrintAddressAsync(string address) { /* ... */ }

The main difference compared to the classic approach is that we pass in the name of the method to the Source Generator instead of the method itself.

Under the hood, the Source Generator actually generates a Command which looks remarkably similar to the one from the ViewModel without Source Generators:

partial class AddressViewModelSourceGen
{
    /// <summary>The backing field for <see cref="PrintAddressCommand"/>.</summary>
    [global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.RelayCommandGenerator", "8.1.0.0")]
    private global::CommunityToolkit.Mvvm.Input.AsyncRelayCommand<string>? printAddressCommand;
    /// <summary>Gets an <see cref="global::CommunityToolkit.Mvvm.Input.IAsyncRelayCommand{T}"/> instance wrapping <see cref="PrintAddressAsync"/>.</summary>
    [global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.RelayCommandGenerator", "8.1.0.0")]
    [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
    public global::CommunityToolkit.Mvvm.Input.IAsyncRelayCommand<string> PrintAddressCommand => printAddressCommand ??= new global::CommunityToolkit.Mvvm.Input.AsyncRelayCommand<string>(new global::System.Func<string, global::System.Threading.Tasks.Task>(PrintAddressAsync), CanPrint);
}

As we can see, the name of the method is simply used by the Source Generator to insert it as text into the generated code file and serves as the argument for the canExecute parameter (all the way at the end, where it says CanPrint).

Since the generated Command is of type AsyncRelayCommand<string>, any arguments passed into a Command as a CommandParameter are forwarded to the PrintAddressAsync() and CanPrint() methods respectively.

With this in place, the executability of the Command will be re-evaluated every time that the CommandParameter of our Button changes. But how do we notify the Command about changes to the Copies property from the ViewModel?

Introducing [NotifyCanExecuteChangedFor]

When a property changes and we want to notify subscribers that another property, e.g. a getter-only one, likely has changed as well, we can use the [NotifyPropertyChangedFor] attribute when using Source Generators. Fortunately, a similar attribute exists for commands: [NotifyCanExecuteChangedFor], which also works in the same fashion.

The [NotifyCanExecuteChangedFor] attribute is used to decorate any property which may be required to determine the executability of a Command and takes the name of the Command as an argument:

[ObservableProperty]
[NotifyCanExecuteChangedFor(nameof(PrintAddressCommand))]
private int _copies;

This is all we need to do in order to trigger a re-evaluation of the CanExecute predicate attached to the PrintAddressCommand. Every time that the auto-generated Copies property gets updated, the re-evaluation takes place.

Under the hood, this also looks highly familiar: At the end of the auto-generated property's setter, the NotifyCanExecuteChanged() method is called on the auto-generated PrintAddressCommand:

/// <inheritdoc cref="_copies"/>
[global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.ObservablePropertyGenerator", "8.1.0.0")]
[global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
public int Copies
{
    get => _copies;
    set
    {
        if (!global::System.Collections.Generic.EqualityComparer<int>.Default.Equals(_copies, value))
        {
            OnCopiesChanging(value);
            OnPropertyChanging(global::CommunityToolkit.Mvvm.ComponentModel.__Internals.__KnownINotifyPropertyChangingArgs.Copies);
            _copies = value;
            OnCopiesChanged(value);
            OnPropertyChanged(global::CommunityToolkit.Mvvm.ComponentModel.__Internals.__KnownINotifyPropertyChangedArgs.Copies);
            PrintAddressCommand.NotifyCanExecuteChanged();
        }
    }
}

This is exactly what I have also done in the ViewModel that does not use the Source Generators of the MVVM Community Toolkit: First, the equality comparison of the backing field and the new value takes place, followed by the notification that the property is about to change, then the backing field gets updated, which is then followed by the notification that the property has just changed and finally, the CanExecuteChanged event of the PrintAddressCommand is raised by calling NotifyCanExecuteChanged().

ViewModel with Source Generators

The completed version of the ViewModel (again stripped down to the relevant bits only) using Source Generators looks as follows:

[RelayCommand(CanExecute = nameof(CanPrint))]
private async Task PrintAddressAsync(string address)
{
    await Task.Delay(TimeSpan.FromSeconds(2));
    OnPrintAddress?.Invoke(address);
}

private bool CanPrint(string address) => Copies > 0 && !string.IsNullOrWhiteSpace(address);

[ObservableProperty]
[NotifyCanExecuteChangedFor(nameof(PrintAddressCommand))]
private int _copies;

Amazing, this looks (c)lean and beautiful. My developer heart is happy - again 💖.

Running the sample

In both versions, we can now run the sample app and see that the Button is only enabled when the address is not empty and at least one copy is set to be printed:

Perfect! 💪 There's no need to do without the functionality that CanExecute provides when using auto-generated commands, because the MVVM Source Generators have us covered here, as well.

Conclusions and next steps

Evaluating the executability of commands is still possible like before even with Source Generators. We can still write exactly the same kind of logic like we did before while saving loads of valuable time and tremendously reducing the risk of bugs, especially when dealing with a multitude of different properties and commands.

Source Generators can help you with decreasing the amount of boilerplate code and make ViewModels much more legible and comprehensible, provided you have a basic understanding of the MVVM pattern. At the same time, you do not have to live without your favorite MVVM features and interfaces, since they are all compatible and complementary, with and without using Source Generators - mix and match, if you will.

In my humble opinion, this is all relatively straightforward, as long as you have a working understanding of the MVVM pattern and its implementation in .NET. I hope that you learned something again from this article.

Last but not least, my friend and colleague Marco has his own sample repository on GitHub with another example using the CanExecute predicate, check it out if you like.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts and developments.

If you have already used modern .NET-based UI frameworks like Xamarin.Forms and .NET MAUI before, you are likely familiar with a common concept called data binding. This concept is used to access data from a data source (such as properties inside a ViewModel) from within the user interface and react to changes that may occur during runtime. Classic data binding in .NET based applications comes with a couple of drawbacks, though.

Worst of all, they are slow and inefficient, because classic bindings are resolved during runtime using reflection, which means that the binding source and target are scanned for matching properties and commands. Secondly, because of this runtime resolution, binding expressions are not evaluated during compile-time. This means that any incorrect bindings will only be noticed during runtime and potentially cause a crash or at the least a somewhat malfunctioning application. Finding these types of bugs can turn out to be a time consuming and finicky task. Lastly, classic bindings require some additional work in order to get useful code-completion suggestions and error messages in the XAML editor window.

Enter compiled bindings. In order to speed up data binding and provide compile-time evaluation of binding expressions (and also allow Intellisense and other tools to provide useful suggestions during design-time), compiled bindings were introduced. According to Microsoft, compiled bindings are up to 20 times (!) faster than classic bindings**. You should definitely use them**, if you can**.**

Disclaimer: This focus of this article is on compiled bindings in Xamarin.Forms and .NET MAUI. However, compiled bindings also exist in Windows Presentation Foundation (WPF), but they work quite differently and won't be covered in this blog article.

For this blog post, I will use a .NET MAUI project (check out the sample repository), but these concepts largely apply also to Xamarin.Forms.

Example ViewModel

For the bindings in this article, I will use the following, simplified ViewModel (you can find the full code in the sample repository), which has a property called Items of type ObservableCollection<BindingItem> , an AddItemCommand to add new items and a RemoveItemCommand to remove either the last item or a specific item, depending on the CommandParameter that is passed in of type BindingItem:

public partial class BindingsViewModel : ObservableObject
{
    [ObservableProperty]
    private ObservableCollection<BindingItem> _items = new();

    private int _counter = 0;

    [RelayCommand]
    private void AddItem()
    {
        Items.Add(new BindingItem
        {
            Name = $"Item {_counter}",
            Count = _counter
        });

        _counter++;
    }

    [RelayCommand]
    private void RemoveItem(BindingItem item = null)
    {
        if (Items.Count == 0)
        {
            return;
        }

        if (item == null)
        {
            Items.Remove(Items.Last());
            return;
        }

        Items.Remove(item);
    }
}

Setting up Compiled Bindings

The central component for compiled bindings is the x:DataType attribute, which exists in both Xamarin.Forms and .NET MAUI. Basically, all we need to do is setting the BindingContext property and the x:DataType attribute in the View and we're good to go (almost at least - there are some common pitfalls that I'll explain further down).

Note: For compiled bindings to be usable, you need make sure that XAML compilation is enabled in your project, which is the default for .NET MAUI. For Xamarin.Forms it needs to be explicitly enabled, either globally or locally. More recent versions of Xamarin.Forms also have XAML compilation enabled by default when using the official XAML templates.

DataType and BindingContext

First, we need to set the x:DataType attribute of our ContentPage or ContentView on the root node in the XAML file to the underlying data type of the BindingContext of our View, which usually is a ViewModel:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage
  x:Class="MauiSamples.Views.BindingsPage"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
  xmlns:viewModels="clr-namespace:MauiSamples.ViewModels"
  x:DataType="viewModels:BindingsViewModel">
  <!-- ... -->
</ContentPage>

Here, I pass the name of the ViewModel including its namespace, so that it's fully qualified, because only fully-qualified names can be used in XAML compilation.

Once this is done, we still need to set the BindingContext for the View in the code-behind (the View's .xaml.cs file):

public partial class BindingsPage : ContentPage
{
    public BindingsPage(BindingsViewModel viewModel)
    {
        InitializeComponent();
        BindingContext = viewModel;
    }
}

Done. This is all we need in order to set up compiled bindings. Pretty simple 😊.

Technically, this could also be done entirely in XAML, but I'll stick to the more common way of setting the BindingContext in the code-behind, which is also what I recommend to you, because in real world applications, you would typically use dependency injection to pass a ViewModel instance into the View instead of instantiating it yourself in the View's XAML or code-behind.

Note: The x:DataType can be defined on any level in the XAML hierarchy and then only applies downward from that level in the XAML tree. However, it is recommended to set the x:DataType on the root level and then redefine it on deeper nested elements, if necessary (more on this further down).

Using Bindings

Now, with the x:DataType and the BindingContext set, we can go ahead and bind to the properties and commands of our ViewModel as usual:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage
  x:Class="MauiSamples.Views.BindingsPage"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
  xmlns:models="clr-namespace:MauiSamples.Models"
  xmlns:viewModels="clr-namespace:MauiSamples.ViewModels"
  x:DataType="viewModels:BindingsViewModel">

  <Grid
    RowDefinitions="*, auto"
    RowSpacing="8">

    <ListView
      Grid.Row="0"
      ItemsSource="{Binding Items}">
      <!-- ... -->
    </ListView>

    <HorizontalStackLayout
      Grid.Row="1">
      <Button
        Command="{Binding AddItemCommand}"
        Text="Add Item" />
      <Button
        Command="{Binding RemoveItemCommand}"
        Text="Remove Last" />
    </HorizontalStackLayout>

  </Grid>

</ContentPage>

Design-time Hints

Apart from the massive boost in binding performance, one of the main differences between compiled bindings and classic bindings is that Visual Studio (as well as plugins and extensions or any other modern IDE) now recognizes the properties and commands and can provide suggestions and errors for the bindings to us during design-time, which means that we can already see in the text editor when something isn't set correctly even before compiling and running the app:

Here, we can see that AddItem is inaccessible, because it's a private method and doesn't exist as a command. The correct name of the command to bind to is AddItemCommand (since we are using MVVM Source Generators here). If we would try to run the app like this, we would receive compiler errors, which wouldn't happen with classic bindings.

Note: I am using the JetBrains ReSharper extension for Visual Studio (no affiliation), which provides the Inlay Hints for the data context in XAML (notice the (BindingsViewModel).Path=). This is additionally useful, because I can directly see what my current BindingContext is.

Nested Data Contexts

There are various common scenarios, where the data context in the View hierarchy changes. On the root level of our View, we have a ViewModel set as the data context (meaning it's set as the BindingContext), but we may have other types that we are using in our ViewModel that are represented in our View hierarchy based on a DataTemplate.

The most common case is when we have a binding to a List or Collection of items of a specific type in our ViewModel, such as the ObservableCollection<BindingItem> in the BindingsViewModel. Using classic bindings, our View only knows at runtime, through reflection, what type the items in the List or Collection have.

With compiled bindings, we can already tell the View at compile-time, before the actual BindingContext is set (which only occurs during runtime), what type the BindingContext will have. Now, this BindingContext usually applies to the entire ContentPage or ContentView that we're dealing with.

This is problematic, because the data context of a DataTemplate usually is inferred from the type of the items that are contained inside of a List or Collection.

In the following situation, the DataTemplate will assume that the data context has not changed and will fail to bind to the Name property of the BindingItem element, because the x:DataType currently applies to the entire View:

 <ContentPage
  x:Class="MauiSamples.Views.BindingsPage"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
  xmlns:models="clr-namespace:MauiSamples.Models"
  xmlns:viewModels="clr-namespace:MauiSamples.ViewModels"
  x:DataType="viewModels:BindingsViewModel">

  <Grid
    RowDefinitions="*, auto"
    RowSpacing="8">

    <ListView
      Grid.Row="0"
      ItemsSource="{Binding Items}">
      <ListView.ItemTemplate>
        <DataTemplate>
          <ViewCell>
            <Grid
              Padding="8"
              ColumnDefinitions="*,*">
              <Label
                Grid.Column="0"
                HorizontalOptions="Start"
                Text="{Binding Name}"
                VerticalTextAlignment="Center" />
            </Grid>
          </ViewCell>
        </DataTemplate>
      </ListView.ItemTemplate>
    </ListView>
  <!-- ... -->
  </Grid>
</ContentPage>

When we try to build and run this, we'll receive the following compiler error:

Error XFC0045 Binding: Property "Name" not found on "MauiSamples.ViewModels.BindingsViewModel".

This is because the Name property doesn't exist in the BindingsViewModel, but belongs to the BindingItem model class instead.

In order to resolve this, we can redefine the x:DataType anywhere in the View hierarchy. For this, all we need to do is specify the BindingItem class as the x:DataType on the DataTemplate and then the bindings will work as expected:

<ContentPage
  x:Class="MauiSamples.Views.BindingsPage"
  xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
  xmlns:models="clr-namespace:MauiSamples.Models"
  xmlns:viewModels="clr-namespace:MauiSamples.ViewModels"
  x:DataType="viewModels:BindingsViewModel">

  <Grid
    RowDefinitions="*, auto"
    RowSpacing="8">

    <ListView
      Grid.Row="0"
      ItemsSource="{Binding Items}">
      <ListView.ItemTemplate>
        <!-- redefining the DataType here -->
        <DataTemplate x:DataType="models:BindingItem">
          <ViewCell>
            <Grid
              Padding="8"
              ColumnDefinitions="*,*">
              <Label
                Grid.Column="0"
                HorizontalOptions="Start"
                Text="{Binding Name}"
                VerticalTextAlignment="Center" />
            </Grid>
          </ViewCell>
        </DataTemplate>
      </ListView.ItemTemplate>
    </ListView>
  <!-- ... -->
  </Grid>
</ContentPage>

When we run the app now, we'll see that our bindings work correctly and we can add and remove items using the provided buttons:

Neat, we can now use compiled bindings and redefine the x:DataType on any level of the View hierarchy based on the structure of our ViewModel 😃. Which leads us to parent bindings, which are also affected by the x:DataType.

Relative Bindings

Instead of just removing the last item, it would be great if we could also remove any individual item in the ObservableCollection. For this, we need to add a button next to the label in the DataTemplate, bind to the RemoveItemCommand and pass the item itself as the CommandParameter:

But wait, the RemoveItemCommand cannot be found 😱 and the design-time inlay hint already shows us why: The data context is currently set to BindingItem, because we specified that as the data type for our DataTemplate earlier:

<DataTemplate x:DataType="models:BindingItem">

Note: This issue applies to classic bindings and compiled bindings alike. So does the solution for the issue. The difference is that we can now already identify the problem during design-time or compile-time instead of noticing the problem during runtime only.

This is where relative bindings come in. When trying to bind to a property or command of a parent data context, such as our BindingsViewModel, we need to ensure that the binding is set to the correct Binding Source, specified via the Source attribute of a binding expression. In our case, we need to specify a RelativeSource with an AncestorType which is set our BindingsViewModel:

<Button
  Grid.Column="1"
  Text="Remove"
  BackgroundColor="Red"
  Command="{Binding RemoveItemCommand, Source={RelativeSource AncestorType={x:Type viewModels:BindingsViewModel}}}"
  CommandParameter="{Binding .}" />

By doing this, we're telling the binding mechanism to look higher up in the View hierarchy for a data context that matches the type of the specified RelativeSource.

Now, the error is gone and we can build and run the app successfully and add and remove items as much as we like, even individual ones:

Awesome, our bindings work and we can now benefit from the performance boost as well as the compile-time (and also design-time) evaluation of binding expressions that compiled bindings provide 🏆.

Conclusions and next steps

Compiled bindings are awesome and highly convenient. Especially the performance boost and the compile-time (as well as design-time) evaluation of binding expressions are gold.

You cannot only speed up your application using compiled bindings, but you can also reduce your debugging efforts and focus on developing quality features instead of hunting for bugs that turn out to be binding errors, which often are difficult to identify without IDE support.

Have you used compiled bindings before? Did you run into any issues with them? Let me know and I'll be happy to write another blog post to explore bindings even further.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts.

Welcome to the second article of my mini-series about MVVM Source Generators for C# .NET. In the previous post, I discussed the basics and most important features that the MVVM Community Toolkit provides, specifically attributes that can be used to automatically generate properties and commands.

In this second part, I will show you how to intercept property setters in order to provide custom behavior, which you might be used to from developing ViewModels entirely by hand without using Source Generators. By intercepting the setters, we can define custom functionality that can be executed right before and right after changing the backing field of a property.

Last but not least, I will also demonstrate the beauty of auto-generated RelayCommands. In the past, developers added a lot of busy flags (properties) to their ViewModels in order to show some kind of busyness indicator (such as an ActivityIndicator, also known as a spinner) that informs the user that a longer operation is currently taking place.

Like in the previous post, I am using a .NET MAUI project (check out the sample repository) to demonstrate the functionality, but since the MVVM Community Toolkit is independent from UI frameworks, the same things apply to technologies like Windows Presentation Foundation (WPF) and Xamarin.Forms.

Updated scenario

In order to demonstrate customized property setters as well as the awesome new way to indicate activity (or busyness) without flags, I have added a Stepper control to the UI from the previous post to simulate the selection of how many copies of the address label should be printed. When the number of copies is set to 0 the popup won't open. I have also added an ActivityIndicator to be displayed while the popup is being opened:

The AddressViewModel receives two new properties which are called Copies and IsBusy and the PrintAddress() method will be changed to return an async Task in order to simulate a longer running operation:

private int _copies;
public int Copies
{
    get => _copies;
    set => SetField(ref _copies, value);
}

private bool _isBusy;
public bool IsBusy
{
    get => _isBusy;
    set => SetField(ref _isBusy, value);
}

private async Task PrintAddressAsync()
{
    IsBusy = true;

    await Task.Delay(TimeSpan.FromSeconds(2));

    OnPrintAddress?.Invoke(FullAddress);

    IsBusy = false;
}

The ActivityIndicator is bound to the IsBusy flag in the XAML:

<ActivityIndicator
  IsVisible="{Binding IsBusy}"
  IsRunning="{Binding IsBusy}"/>

In the next steps, we will add some custom functionality to the setter of the Copies property before addressing the busy flags. We'll first look at how this is usually done without Source Generators followed by how you can take advantage of the MVVM goodness that the Source Generators provide without having to live without customized property setters.

Custom Property Setters

Using the previously introduced Source Generator attributes may have left some readers who have working MVVM experience with some open questions. For example, there are situations where you would not only add an observable property that raises the PropertyChanging or PropertyChanged events, but you might actually need to customize the property setter to execute additional functionality if and when the property is either about to change or has just changed.

Opinion: In my humble opinion, it's a bad practice to add a lot of functionality to a property setter. By adding a lot of complex statements or even loops to a setter, you're effectively mixing concerns, which makes them difficult to maintain. In the end, a setter is a like a method that updates a value and should have no unexpected side-effects. Adding a lot of extra functionality that belongs into a separate method can lead to the violation of the Single Responsibility Principle (SRP) and should be avoided.

Executing logic in classic setters

Let's say we want to execute some additional logic in the setter of our Copies property, e.g. to log the current and new values to the console, and also notify subscribers about the changing state. Usually, without Source Generators we would write something like this:

private int _copies;
public int Copies
{
    get => _copies;
    set
    {
        if (value == _copies)
        {
            return;
        }

        //do something before property is changing
        Console.WriteLine($"Property {nameof(Copies)} is about to change. Current value: {Copies}, new value: {value}");
        OnPropertyChanging();        

        _copies = value;

        //do something after property changed
        Console.WriteLine($"Property {nameof(Copies)} is has changed. Current value: {Copies}, new value: {value}");
        OnPropertyChanged();
    }
}

Note: For simplicity's sake I went with logging something to the console here instead of some advanced logic. Of course, it's also possible to execute some complex logic inside a property setter, although I recommend separating concerns whenever possible.

Now, how can we achieve something similar using the Source Generators, though?

Executing logic in auto-generated setters

As it turns out, it's actually quite easy to add custom behavior to auto-generated property setters, because the MVVM Source Generators graciously provide partial methods (signature only) for us which we can "hook" into, meaning we can provide an implementation body for these methods.

Let's add the Copies property in the MVVM Source Generator way and then look at what is actually being generated for us. This is the property with the [ObservableProperty] attribute:

[ObservableProperty]
private int _copies;

If you remember from the previous post, in the Under the hood section, there are two methods, specifically, which are generated for us based on the property's name when using the ObservableObject base class together with the [ObservableProperty] attribute:

• partial void On[PropertyName]Changing(<type> value)

• partial void On[PropertyName]Changed(<type> value)

For the Copies property these auto-generated methods look like this:

/// <summary>Executes the logic for when <see cref="Copies"/> is changing.</summary>
[global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.ObservablePropertyGenerator", "8.1.0.0")]
partial void OnCopiesChanging(int value);

/// <summary>Executes the logic for when <see cref="Copies"/> just changed.</summary>
[global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.ObservablePropertyGenerator", "8.1.0.0")]
partial void OnCopiesChanged(int value);

As we can see, these methods are actually partial methods that don't define a body. We will take advantage of that a bit further down, but first let's have a look at when and where those methods are invoked. This is the auto-generated property:

/// <inheritdoc cref="_copies"/>
[global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.ObservablePropertyGenerator", "8.1.0.0")]
[global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
public int Copies
{
    get => _copies;
    set
    {
        if (!global::System.Collections.Generic.EqualityComparer<int>.Default.Equals(_copies, value))
        {
            OnCopiesChanging(value);
            OnPropertyChanging(global::CommunityToolkit.Mvvm.ComponentModel.__Internals.__KnownINotifyPropertyChangingArgs.Copies);
            _copies = value;
            OnCopiesChanged(value);
            OnPropertyChanged(global::CommunityToolkit.Mvvm.ComponentModel.__Internals.__KnownINotifyPropertyChangedArgs.Copies);
        }
    }
}

Right in beginning of the setter, the equality of the _copies backing field and the new value is checked. Only if this comparison evaluates to false, meaning that the values are different, the setter logic is executed.

First, the OnCopiesChanging() method is invoked with the new value as an argument. Since the method doesn't actually have a body, nothing happens - yet. That call is followed by raising the PropertyChanging event of the INotifyPropertyChanging interface.

Second, the value of the _copies backing field gets updated before OnCopiesChanged() is invoked using the new value as an argument. This is followed by raising the PropertyChanged event of the INotifyPropertyChanged interface.

This means that we can "hook" into the setter by providing implementation bodies for the OnCopiesChanging() and OnCopiesChanged() methods in order to achieve the same functionality as we did without the Source Generators:

[ObservableProperty]
private int _copies;

partial void OnCopiesChanging(int value)
{
    Console.WriteLine($"Property {nameof(Copies)} is about to change. Current value: {Copies}, new value: {value}");
}

partial void OnCopiesChanged(int value)
{
    Console.WriteLine($"Property {nameof(Copies)} is has changed. Current value: {Copies}, new value: {value}");
}

That's it. That's all we have to do in order to add custom functionality for our property setters. If we wanted to, we could even access other properties or run some fancy logic. Yeah! 🎉

Mixing approaches

For common and simple scenarios, the MVVM Source Generators are the easiest way to minimize your coding efforts and increase productivity by reducing this repetitive task to a minimum, but what about non-standard properties that require some special logic which cannot be achieved using the MVVM Source Generators?

In the rare case that you really cannot achieve some highly specialized behavior using the auto-generated properties, such as executing logic inside of getters, or inside setters independent of the result of the equality comparison, you can still implement your properties like you would have without using Source Generators. It is completely valid to mix the two approaches and use the best of both worlds.

Nothing stops you from implementing one property using a Source Generator attribute and another one by implementing it completely manually:

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(IsOfLegalAge))]
private int _age;

public bool IsOfLegalAge => Nationality == Nation.USA ? Age >= 21 : Age >= 18;

private Nation _nationality;
public Nation Nationality
{
    get => _nationality;
    set
    {
        if(!SetField(ref _nationality)) return;
        OnPropertyChanged(nameof(IsOfLegalAge));
    }
}

Goodbye, busy flags

In the beginning of this article, I have introduced an IsBusy property that is used to show or hide an ActivityIndicator and it is set manually at the beginning and at the end of the PrintAddressAsync() method:

private async Task PrintAddressAsync()
{
    IsBusy = true;

    await Task.Delay(TimeSpan.FromSeconds(2));

    OnPrintAddress?.Invoke(FullAddress);

    IsBusy = false;
}

This is a common scenario in many ViewModels, but often you need to have various flags to indicate busyness for different operations and sometimes you just cannot reuse the same flag for that.

Problems of busy flags

Doing this is problematic, because it scatters the code with flags and you may even run into issues when you have some complex logic that is running in the method that your command invokes.

I have often encountered bugs where busy flags have not been reset correctly, because a developer decided to (rightfully!) jump out of a method early if a certain condition isn't met and the developer (it might have been myself on occasion) forgot to set the flag to false again when the method returns early from execution.

Take the following scenario as an example:

private async Task PrintAddressAsync()
{
    IsBusy = true;

    if (Copies < 1) return;

    await Task.Delay(TimeSpan.FromSeconds(2));

    OnPrintAddress?.Invoke(FullAddress);

    IsBusy = false;
}

Here, IsBusy would remain true although the method has already returned, if the value of Copies is smaller than 1. The ActivityIndicator would keep spinning forever (figuratively). This can be remedied in a couple of different ways, but none of them are pretty.

For example, we could set the IsBusy flag to false in multiple locations in our code, or we could decide to wrap that code, either by using try-finally blocks or with an extra method which is executed between the two statements that update the IsBusy property.

Option 1: Set flag in multiple locations

private async Task PrintAddressAsync()
{
    IsBusy = true;

    if (Copies < 1)
    {
        IsBusy = false;
        return;
    }

    await Task.Delay(TimeSpan.FromSeconds(2));

    OnPrintAddress?.Invoke(FullAddress);

    IsBusy = false;
}

This is ugly and error-prone, because we may easily forget to add the required statements to all possible code branches that return early from execution.

Option 2: Use a try-finally block

private async Task PrintAddressAsync()
{
    try
    {
        IsBusy = true;

        if (Copies < 1) return;

        await Task.Delay(TimeSpan.FromSeconds(2));

        OnPrintAddress?.Invoke(FullAddress);
    }
    finally
    {
        IsBusy = false;
    }
}

This solution is abusing try-finally blocks for non-intended purposes, but it will work.

Note: Usually, you would use a finally block to clean up resources

Option 3: Introduce a separate method

private async Task PrintAddressAsync()
{
    IsBusy = true;

    await PrintAsync();

    IsBusy = false;
}

private async Task PrintAsync()
{
    if (Copies < 1) return;

    await Task.Delay(TimeSpan.FromSeconds(2));

    OnPrintAddress?.Invoke(FullAddress);
}

This is by far the best option when using flags, but it's still not pretty having to deal with several different busy flags in more elaborate ViewModels.

Introducing AsyncRelayCommand

There is a solution to this and it's called AsyncRelayCommand.

The [RelayCommand] attribute of the MVVM Source Generators will generate different types of commands for us depending on the method signature.

When using a void method it will create a regular RelayCommand, but when the return type is an async Task, for example, it will actually generate an AsyncRelayCommand for us:

//this will create a RelayCommand called "PrintAddressCommand"
[RelayCommand]
private void PrintAddress() {} 

//this will create an AsyncRelayCommand called "PrintAddressCommand"
[RelayCommand]
private async Task PrintAddressAsync() {}

Important: When using async methods, it's common practice to use the "Async" suffix for the method name, e.g. PrintAddressAsync(). However, the Source Generators will recognize the suffix and remove it from the command name, so the command will still be called PrintAddressCommand (instead of PrintAddressAsyncCommand).

This is splendid, because the AsyncRelayCommand comes with its own type of busy flag in the form of a property called IsRunning. We can use this property instead of implementing our own IsBusy property. All we need to do is change the bindings of the ActivityIndicator from IsBusy to PrintAddressCommand.IsRunning:

<ActivityIndicator
  IsVisible="{Binding PrintAddressCommand.IsRunning}"
  IsRunning="{Binding PrintAddressCommand.IsRunning}"/>

Note: Buttons in .NET MAUI automatically use the IsRunning flag when their Command property is bound to an asynchronous command. This is useful, because the button will be disabled until the command finishes execution.

We don't need to set any busy flags in the ViewModel anymore:

[RelayCommand]
private async Task PrintAddressAsync()
{
    if (Copies < 1) return;

    await Task.Delay(TimeSpan.FromSeconds(2));

    OnPrintAddress?.Invoke(FullAddress);
}

👋 Goodbye, busy flags - AsyncRelayCommand FTW! I love it! 🤩

Conclusions and next steps

Writing clean and maintainable ViewModels has never been easier thanks to the Source Generators of the MVVM Community Toolkit. We can still write exactly the same kind of logic like we did before while saving loads of valuable time and tremendously reducing the risk of bugs.

Source Generators can help you with decreasing the amount of boilerplate code and make ViewModels much more legible and comprehensible, provided you have a basic understanding of the MVVM pattern.

It's easier than ever to quickly write up a ViewModel with many different properties and set up commands and bindings with busy indicators without sacrificing any of the flexibility of manually implementing the INotifyPropertyChanging and INotifyPropertyChanged interfaces.

I hope you're just as excited as I am about this major development in the .NET realm. James Montemagno has recently summarized these amazing features of the MVVM Community Toolkit in another great YouTube video which is definitely worth checking out, as well.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts.

I am a huge fan of the Model-View-ViewModel pattern (MVVM) and it's no surprise to me that it keeps gaining popularity (even outside of .NET development). When applied correctly, it helps with writing Clean Code so that the resulting code is easy to read, understand, test and maintain.

In this blog article, which is part of a mini series on MVVM Source Generators, I will show how you can take advantage of the MVVM Community Toolkit and why you should use Source Generators in your development projects.

Important: This article assumes prior knowledge about the MVVM pattern and how it is used in .NET applications.

If you are completely new to MVVM, please consider familiarizing yourself with it first and learn about the INotifyPropertyChanged interface as well as data bindings and commands. There is a popular introductory video for MVVM on YouTube by James Montemagno.

I strongly believe that newcomers should first learn how to implement MVVM in .NET in the conventional way before taking shortcuts using Source Generators in order to avoid frustration.

For the reason of convenience (and because I cannot get enough of it), I will use a .NET MAUI project (check out the sample repository), but the ViewModel could be from any other .NET based application, since the MVVM Community Toolkit is agnostic to application and UI development frameworks such as WPF, Xamarin.Forms or .NET MAUI. Therefore, even if you're not familiar yet with .NET MAUI, you will still want to keep reading on.

Why use Source Generators?

While the MVVM pattern is a fantastic way to write maintainable and unit-testable applications, it requires a lot of boilerplate code. For every property and every command, we need to implement a backing field, setters and getters and raise an event to notify the UI that something has changed, like so:

private string _firstName;
public string FirstName
{
    get => _firstName;
    set
    {
        if (_firstName.Equals(value))
        {
            return;
        }

        _firstName = value;
        OnPropertyChanged();
    }
}

This can quickly become expensive, because on top of the actual business logic there is a lot of additional code that needs to be maintained. This costs valuable development time and increases the risk of bugs, e.g. because developers like to use copy/paste a lot and may occasionally forget to update the backing fields.

Anecdote: A former colleague of mine used to call this behavior "copy pasta" as a loose reference to the messiness of spaghetti code

In order to avoid those common mistakes and help with the Don't Repeat Yourself (DRY) principle, the MVVM Community Toolkit helps us to reduce the amount of this boilerplate code. It does so in several ways:

• It provides default implementations of the INotifyPropertyChanged and INotifyPropertyChanging interfaces (e.g. ObservableObject).

• It comes with SetProperty() methods which set the backing field for a property and raise the PropertyChanged and PropertyChanging events for us, but only if the new value differs from the current value of the backing field.

• Instead of fully implementing each property and each command with all their backing fields, setters and getters, we can just let the Source Generators do it for us.

This drastically reduces development time and our code files look much cleaner. So, by using Source Generators, our code from above can actually be reduced to writing a one-liner like this one:

[ObservableProperty] private string _firstName;

Before getting deeper into this and learning about how all this works, let's have a look at a common ViewModel that implements the INotifyPropertyChanged interface and after that, we'll see how it changes when we use MVVM Source Generators.

Setting

Let's assume that we want to implement an application that let's us enter a name and address to generate an address label. The application should have a live preview for the label which updates automatically when any of the input data changes as well as a printing function (we won't actually print anything; instead, for simplicity, I just open a popup displaying the entered data).

Our ViewModel therefore needs a couple of properties and a command:

public string FirstName { get; set; }
public string LastName { get; set; }
public string StreetAddress { get; set; }
public string PostCode { get; set; }
public string City { get; set; }
public string FullAddress { get; }
public ICommand PrintAddressCommand { get; }

We can bind to those properties and the command in our XAML and this will not change throughout this blog post, even with the Source Generators:

<Label Text="{Binding FullAddress}" />
<Button Text="Print Address" Command="{Binding PrintAddressCommand}" />

Whenever the FirstName, LastName, StreetAddress, PostCode or City property changes, the FullAddress property should be live-updated in our View, which looks like this:

When the Print Address button is clicked, the PrintAddressCommand will open a popup that displays the address (which we will see further down).

Note: I am skipping the rest of the UI code and only focus on the ViewModel in this blog post. If you want to see the whole code in action including the actual Views, check out the sample repository.

Let's have a look at what the fully implemented ViewModel looks like.

Full ViewModel without Source Generators

I've called it AddressViewModel and implemented the INotifyPropertyChanged interface without using any of the existing helper classes, just to demonstrate what a manually implemented ViewModel commonly looks (or better used to look) like:

using System.ComponentModel;
using System.Runtime.CompilerServices;
using System.Text;
using System.Windows.Input;

namespace MauiSamples.ViewModels;

public sealed class AddressViewModel : INotifyPropertyChanged
{
    public delegate void PrintAddressDelegate(string address);
    public PrintAddressDelegate OnPrintAddress = null;

    private ICommand _showAddressCommand;
    public ICommand ShowAddressCommand => _showAddressCommand ??= new Command(PrintAddress);

    private string _firstName;
    public string FirstName
    {
        get => _firstName;
        set
        {
            if (SetField(ref _firstName, value))
            {
                OnPropertyChanged(nameof(FullAddress));
            }
        }
    }

    private string _lastName;
    public string LastName
    {
        get => _lastName;
        set
        {
            if (SetField(ref _lastName, value))
            {
                OnPropertyChanged(nameof(FullAddress));
            }
        }
    }

    private string _streetAddress;
    public string StreetAddress
    {
        get => _streetAddress;
        set
        {
            if (SetField(ref _streetAddress, value))
            {
                OnPropertyChanged(nameof(FullAddress));
            }
        }
    }

    private string _postCode;
    public string PostCode
    {
        get => _postCode;
        set
        {
            if (SetField(ref _postCode, value))
            {
                OnPropertyChanged(nameof(FullAddress));
            }
        }
    }

    private string _city;
    public string City
    {
        get => _city;
        set
        {
            if (SetField(ref _city, value))
            {
                OnPropertyChanged(nameof(FullAddress));
            }
        }
    }

    public string FullAddress
    {
        get
        {
            var stringBuilder = new StringBuilder();

            stringBuilder
                .AppendLine($"{FirstName} {LastName}")
                .AppendLine(StreetAddress)
                .AppendLine($"{PostCode} {City}");

            return stringBuilder.ToString();
        }
    }

    private void PrintAddress()
    {
        OnPrintAddress?.Invoke(FullAddress);
    }

    public event PropertyChangedEventHandler PropertyChanged;

    private void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }

    private bool SetField<T>(ref T field, T value, [CallerMemberName] string propertyName = null)
    {
        if (EqualityComparer<T>.Default.Equals(field, value))
        {
            return false;
        }

        field = value;
        OnPropertyChanged(propertyName);
        return true;
    }
}

Uff, that's a lot of code for just a couple of properties and one measly command! So much repetition... It could be even worse, if the equality comparison had been implemented separately in each property, as well.

The code above technically is fine and sound, but doing the same thing over and over again for all the different ViewModels an application might have, eventually becomes quite tedious and is error-prone.

Note: For the example scenario, we don't need the INotifyPropertyChanging interface, so I didn't implement that here.

Before we can reduce the amount of code and use the Source Generators, we have to set up a few things and understand how to use the MVVM Community Toolkit. Let's do that next.

How to use the MVVM Community Toolkit

Setup

Before we can start, we need to download and install the CommunityToolkit.MVVM package from nuget.org in our C# project. At the time of writing, the latest stable release is 8.0.0, but we will already dig into the 8.1.0-preview2, so let's install that one (make sure to tick the Include prerelease checkbox next to the search bar), because it comes with some additional features (which I will explore in a separate blog post):

Disclaimer: Preview packages may be unstable or come with breaking changes

Once installed, we can pull in the required classes and attributes by adding the following using statement to a ViewModel:

using CommunityToolkit.Mvvm.ComponentModel;

Note: The MVVM Community Toolkit also provides regular MVVM functionality and base classes that can be used to simplify ViewModels and I highly recommend using it with or without the Source Generators.

Afterwards, we can use the ObservableObject class as a base class or use the [INotifyPropertyChanged] attribute on a partial class to automagically generate the INotifyPropertyChanged implementation for us.

Use the ObservableObject base class if your class does not need to inherit from another base class:

using CommunityToolkit.Mvvm.ComponentModel;

namespace MauiSamples.ViewModels;

public partial class AddressViewModel : ObservableObject { /*...*/ }

Otherwise, if your class already inherits from another base class (C# only supports single inheritance), then you can use the [INotifyPropertyChanged] attribute (and optionally also the [INotifyPropertyChanging] attribute) instead:

using CommunityToolkit.Mvvm.ComponentModel;

namespace MauiSamples.ViewModels;

[INotifyPropertyChanged]
[INotifyPropertyChanging] //optional
public partial class AddressViewModel : SomeOtherBaseClass { /*...*/ }

Note: When using the [INotifyPropertyChanged] attribute or ObservableObject base class, your class must be declared as partial, because Source Generators create code that complements the class. The [INotifyPropertyChanged] attribute should only be used when your ViewModel already inherits from another base class.

Attributes

The MVVM Community Toolkit uses C# attributes to let the MVVM Source Generators know that something should be auto-generated. Attributes can be placed above or in front of fields and method signatures.

When using the Source Generators, you'll probably be using the following attributes more frequently than any of the others:

[ObservableProperty]

This attribute is used to auto-generate a property for a backing field. The resulting property, by convention, always begins with an uppercase letter. Backing fields must be declared private and start with a lowercase letter or with an underscore (_):

//generates a property called "Age"
[ObservableProperty]
private int age; 

//generates a property called "Year"
[ObservableProperty] private int _year;

We only specify the backing fields for the properties, but to access them, we still need to use the appropriate property identifiers. They can be bound to via accessing the Age and Year from within the XAML code:

<Label Text="{Binding Age}" />
<Label Text="{Binding Year}" />

[RelayCommand]

In order to auto-generate a command, you can simply place this attribute above or in front of a method. The resulting command will have the same name as the method, but with the Command suffix:

//generates a RelayCommand called "SayHelloCommand"
[RelayCommand]
private void SayHello()
{
    Console.WriteLine("Hello);
}

The [RelayCommand] attribute can also be used on asynchronous methods, which will actually create an instance of AsyncRelayCommand under the hood, which is very convenient when using MVVM with .NET MAUI:

//generates an AsyncRelayCommand called "SayHelloAsyncCommand"
[RelayCommand] private async Task SayHelloAsync()
{
    await MessageService.ShowMessageAsync("Hello");
}

The resulting commands can be bound to via accessing SayHelloCommand and SayHelloAsyncCommand from the XAML code:

<Button Command="{Binding SayHelloCommand}" />
<Button Command="{Binding SayHelloAsyncCommand}" />

[NotifyPropertyChangedFor]

Sometimes, you also want to inform the consumer of property that another property has changed as well and that any bindings should be updated. That's what [NotifyPropertyChangedFor] attribute is for and it only works in combination with the [ObservableProperty] attribute. While the other attributes do not require an argument, this one requires the name of the property for which a PropertyChanged event should be raised:

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(FullName))]
private string _firstName;

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(FullName))]
private string _lastName;

//a PropertyChanged event will be raised for this property
//whenever either the FirstName or LastName property changes
public string FullName => $"{FirstName} {LastName}";

Updating the ViewModel with Source Generators

Now that we've learned about how the Source Generators can be used, let's apply them to reduce the size of our AddressViewModel step-by-step.

Hint: In the sample repository, I've actually added both versions of the ViewModel, so that you can compare them.

Properties

For each of the properties, we will change the following:

private string _firstName;
public string FirstName
{
    get => _firstName;
    set
    {
        if (SetField(ref _firstName, value))
        {
            OnPropertyChanged(nameof(FullAddress));
        }
    }
}

into:

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(FullAddress))]
private string _firstName;

and so forth.

Command

We can safely remove the following:

private ICommand _showAddressCommand;
public ICommand ShowAddressCommand => _showAddressCommand ??= new Command(PrintAddress);

and instead simply add the [RelayCommand] attribute above the PrintAddress() method:

[RelayCommand]
private void PrintAddress()
{
    OnPrintAddress?.Invoke(FullAddress);
}

Resulting ViewModel with Source Generators

The final result for the AddressViewModel with all the changes looks like this:

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using System.Text;

namespace MauiSamples.ViewModels;

public partial class AddressViewModel : ObservableObject
{
    public delegate void PrintAddressDelegate(string address);
    public PrintAddressDelegate OnPrintAddress = null;

    [ObservableProperty]
    [NotifyPropertyChangedFor(nameof(FullAddress))]
    private string _firstName;

    [ObservableProperty]
    [NotifyPropertyChangedFor(nameof(FullAddress))]
    private string _lastName;

    [ObservableProperty]
    [NotifyPropertyChangedFor(nameof(FullAddress))]
    private string _streetAddress;

    [ObservableProperty]
    [NotifyPropertyChangedFor(nameof(FullAddress))]
    private string _postCode;

    [ObservableProperty]
    [NotifyPropertyChangedFor(nameof(FullAddress))]
    private string _city;

    public string FullAddress
    {
        get
        {
            var stringBuilder = new StringBuilder();

            stringBuilder
                .AppendLine($"{FirstName} {LastName}")
                .AppendLine(StreetAddress)
                .AppendLine($"{PostCode} {City}");

            return stringBuilder.ToString();
        }
    }

    [RelayCommand]
    private void PrintAddress()
    {
        OnPrintAddress?.Invoke(FullAddress);
    }
}

🎉 WOW, we've just saved about 50% of the lines of code compared to the initial version of the ViewModel. Pretty impressive, isn't it?

When we run the code again, our application still behaves exactly like before. Pressing the button will open the popup with the address:

Awesome, MVVM Source Generators FTW! 🏆

Under the hood

Now, what actually happens when the properties and commands are generated? Since we've marked our ViewModel as being a partial class, the Source Generators can create more parts for it in separate files, like the properties and commands based on the attributes we've provided.

Since Source Generators in C# are built on top of the Code Analyzers of the .NET Compiler Platform (Roslyn), they run after making an edit to an open C# file. That way, the generated sources are always available to the C# compiler. We can find the auto-generated files (which always end in .g.cs) for our project in the Solution Explorer under Dependencies -> net7.0 -> Analyzers -> CommunityToolkit.Mvvm.SourceGenerators.

If we select the ObservablePropertyGenerator we can find a file ending in AddressViewModel.g.cs, which contains our auto-generated properties with their setters and getters, e.g. for our FirstName property:

partial class AddressViewModel
{
    /// <inheritdoc cref="_firstName"/>
    [global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.ObservablePropertyGenerator", "8.1.0.0")]
    [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
    public string FirstName
    {
        get => _firstName;
        set
        {
            if (!global::System.Collections.Generic.EqualityComparer<string>.Default.Equals(_firstName, value))
            {
                OnFirstNameChanging(value);
                OnPropertyChanging(global::CommunityToolkit.Mvvm.ComponentModel.__Internals.__KnownINotifyPropertyChangingArgs.FirstName);
                _firstName = value;
                OnFirstNameChanged(value);
                OnPropertyChanged(global::CommunityToolkit.Mvvm.ComponentModel.__Internals.__KnownINotifyPropertyChangedArgs.FirstName);
                OnPropertyChanged(global::CommunityToolkit.Mvvm.ComponentModel.__Internals.__KnownINotifyPropertyChangedArgs.FullAddress);
            }
        }
    }

    // ...
}

As we can see, a default EqualityComparer is used for the _firstName backing field which is of type string. Only if the strings of the backing field and the value object differ, the PropertyChanging event is raised before updating the backing field to the provided value. Once the backing field was updated, the PropertyChanged event is raised, but not just for our FirstName property, it is also raised for the FullAddress property, because we added the [NotifyPropertyChangedFor(nameof(FullAddress))] attribute above our _firstName backing field.

If you look closely, you'll notice that there are not just OnPropertyChanging() and OnPropertyChanged() method calls, but also calls to an OnFirstNameChanging() and an OnFirstNameChanged() method. The first two methods raise the PropertyChanging and PropertyChanged events respectively, while the other two are actually partial methods without a body, which are declared further down in the auto-generated source file:

/// <summary>Executes the logic for when <see cref="FirstName"/> is changing.</summary>
[global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.ObservablePropertyGenerator", "8.1.0.0")]
partial void OnFirstNameChanging(string value);
/// <summary>Executes the logic for when <see cref="FirstName"/> just changed.</summary>
[global::System.CodeDom.Compiler.GeneratedCode("CommunityToolkit.Mvvm.SourceGenerators.ObservablePropertyGenerator", "8.1.0.0")]
partial void OnFirstNameChanged(string value);

💡 These can be used to add custom functionality to our auto-generated property setters. How this can be done will be part of an upcoming blog post, so stay tuned!

Note: The OnPropertyChanging() and OnFirstNameChanging() methods were created in this example, because the ViewModel inherits from ObservableObject, which implements both the INotifyPropertyChanging and the INotifyPropertyChanged interfaces.

Conclusion and next steps

Reducing boilerplate code in your MVVM application has become even simpler now with the MVVM Source Generators of the MVVM Community Toolkit. As I have demonstrated, they are very convenient and super easy to use - provided that you are already somewhat familiar with the MVVM pattern in .NET applications and know what you are doing.

So far, I have shown the most straightforward and simple use cases with the common [ObservableProperty], [RelayCommand] and [NotifyPropertyChangedFor] attributes. If you would like to learn more about this topic, then stay tuned, because I will soon write another blog post about advanced scenarios, such as adding custom functionality to auto-generated property setters and how to get rid of annoying busy flags that technically don't belong into the business logic 🤯.

Microsoft's brilliant James Montemagno also made a cool YouTube video about the MVVM Source Generators of the MVVM Community Toolkit. Check it out, if you like. It helped me get started, as well.

A big thank you to Gerald Versluis for reviewing this blog post for me. Your input was truly valuable. 💝

This blog post was written and published as part of the 2022 .NET Advent Calendar by Dustin Moris.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts.

Sometimes, when you're developing an app, you find yourself in need of a specific control but you just can't manage to find the right one, because the available ones do not offer some of the features that you're looking for. This happens to me quite often and in that case, I tend to just write up my own little custom control.

Building controls using just XAML in .NET MAUI (or Xamarin.Forms) is a common thing that most mobile developers frequently do. However, sometimes you need more control over the look and feel and for that you can use drawn controls instead of reusing existing XAML elements or platform-specific native controls.

In this blog post, I will demonstrate how you can easily draw up your own custom controls for .NET MAUI using SkiaSharp and what you need to do in order to make it reusable - all without needing to write custom handlers, mappers or renderers. Last but not least, I will also show you how Visual Studio 2022 17.4 helps you with creating a nuget package (.nupgk) that you can upload to nuget.org to share it with the world.

While you can use .NET MAUI's GraphicsView which provides a drawing canvas, I personally prefer drawing controls with SkiaSharp.

In this blog post, I am going to refer to a different GitHub repository than the usual one. Step-by-step, we will be building this Progress Bar control which I have already developed and published: https://github.com/ewerspej/epj.ProgressBar.Maui.

Goal

Let's develop a simple but customizable Progress Bar control that will look like this:

The colors of the base and the progress should be customizable. It will also be possible to set the width and height for the Progress Bar.

Setup

In order to begin, we need a new solution with two projects inside. The first one will be a new .NET MAUI App project which will serve as our test bed to see our custom control in action. The second one will be a .NET MAUI Class Library project. This is where we will actually implement our custom control.

Note: A common approach is to place the solution and the sample project in a separate folder, e.g. sample, while the library project resides in its own src (or source or whatever you prefer to call it) folder. The reason to do this is simple: We want to separate our sample code from our library, which makes it easier to navigate and maintain, but that's not a must, it's merely a matter of choice and convenience.

Sample Solution

First, we create a new folder called ProgressBar and inside that, we create another folder called sample before we start up Visual Studio 2022 17.4 and create a new project by selecting .NET MAUI App from the templates:

In the next dialog, we choose the sample folder from before as the directory for our new project. We can place the solution and the project in the same folder here to keep the folder structure simple. We click our way through the project creation wizard and should end up with a folder structure similar to this:

• \ProgressBar\sample\ProgressBarSample

Note: As mentioned above, this is not a must, you can also leave out the sample directory to keep the path short.

ProgressBar Project

Now, we can add the project for the Progress Bar control in the separate src folder. With the solution still open in Visual Studio, we right click on it and select Add -> New Project. From the templates, we select .NET MAUI Class Library this time:

On the following page of the wizard we need to provide a name for the class library as well as a location. For the name, I will use ProgressBar.Maui, but this is just an example. Normally, you would choose some kind of appropriate package name. For the location, I will choose the src folder and select Create to finish the setup:

Once the class library project is created, we end up with a folder structure similar to this:

• \ProgressBar\sample\ProgressBarSample
• \ProgressBar\src\ProgressBar.Maui

Note: In our class library project, we will find a folder structure similar to that of a .NET MAUI App, with a Platform folder for platform-specific code, which can be used to call APIs on Android, iOS, etc. and to create platform-specific handlers, if necessary. In our case, we won't need any of that. Therefore, it's safe to remove the Platform folder and its contents, if you wish to do so.

In the ProgressBar.Maui project, let's rename the Class1.cs file to ProgressBar.cs and also change the class name to ProgressBar.

We also need to add a Project Reference to the ProgressBar.Maui project to our ProgressBarSample project so that we can use any classes from that in our App. To do this, right-click on ProgressBarSample and select Add -> Project Reference, then select the class library project.

Adding SkiaSharp

Next, we need to add SkiaSharp to our class library project. For this, we add the following packages in the NuGet package manager (right-click on the ProgressBar.Maui project and select Manage NuGet Packages):

• SkiaSharp.Views.Maui.Controls (version 2.88.3 at time of writing)
• SkiaSharp.Views.Maui.Core (version 2.88.3 at time of writing)

Once installed, we can use the SKCanvasView as a base class for our control. After that, our class should look like this:

using SkiaSharp.Views.Maui.Controls;

namespace ProgressBar.Maui;

// All the code in this file is included in all platforms.
public class ProgressBar : SKCanvasView
{
}

Handler Registration

Before we advance to the actual implementation, we need to register a handler for our control. This is required, because otherwise MAUI doesn't know how to render the control for each platform.

We don't actually need our own platform-specific handlers since we inherit directly from SKCanvasView without additional requirements. Therefore, we can conveniently use the existing SKCanvasViewHandler from SkiaSharp, because it takes care of everything for us already.

In order to be able register the handler for our control, we need to create a static class inside our ProgressBar.Maui project that I usually call Registration. Inside that class, we create an extension method called UseProgressHandler() where we add the handler to the MauiAppBuilder:

using SkiaSharp.Views.Maui.Handlers;

namespace ProgressBar.Maui;

public static class Registration
{
    public static MauiAppBuilder UseProgressBar(this MauiAppBuilder builder)
    {
        builder.ConfigureMauiHandlers(h =>
        {
            h.AddHandler<ProgressBar, SKCanvasViewHandler>();
        });

        return builder;
    }
}

This can now be used in our ProgressBarSample project's MauiProgram class as follows:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseProgressBar() //add this line
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

        return builder.Build();
    }
}

That's it, we're all set up to actually implement our custom Progress Bar control.

Adding the control to XAML

Before implementing the details, let's already add our ProgressBar to a XAML Page or View, so that we can use that to see what we are actually developing. To do this, we simply import the namespace from our class library and add the control to the layout:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:maui="clr-namespace:ProgressBar.Maui;assembly=ProgressBar.Maui"
             x:Class="ProgressBarSample.MainPage">

  <VerticalStackLayout
            Spacing="25"
            Padding="30,0"
            VerticalOptions="Center">

    <maui:ProgressBar
      WidthRequest="250"
      HeightRequest="5" />

  </VerticalStackLayout>

</ContentPage>

We cannot set any custom properties, yet, because we haven't actually implemented anything so far, but we will already provide values for the WidthRequest and HeightRequest that each control inherits from VisualElement so that our Progress Bar has a defined size.

Note: We're not going to implement additional sizing properties, our Progress Bar will simply size itself automatically based on the allocated size of the control.

Implementing the Progress Bar

Now, we can use the empty class that we created earlier to implement the drawing logic for our Progress Bar control.

Setting up the Canvas for drawing

Before we can draw anything, we need to set up our canvas. First, we add a few private fields to store the canvas and some additional information about our drawing surface:

public class ProgressBar : SKCanvasView
{
    // actual canvas instance to draw on
    private SKCanvas _canvas; 

    // rectangle which will be used to draw the Progress Bar
    private SKRect _drawRect; 

    // holds information about the dimensions, etc.
    private SKImageInfo _info;
}

All the drawing will be done in the OnPaintSurface() method, which we need to override it from our base class. That's where we actually set up our canvas and the drawing rectangle that will contain the progress bar:

protected override void OnPaintSurface(SKPaintSurfaceEventArgs e)
{
    base.OnPaintSurface(e);

    _canvas = e.Surface.Canvas;
    _canvas.Clear(); // clears the canvas for every frame
    _info = e.Info;
    _drawRect = new SKRect(0, 0, _info.Width, _info.Height);

    //...
}

Every time OnPaintSurface() gets called our control will be drawn. Therefore, we request the canvas to draw on and call Clear() on it. Otherwise, we would draw on top of what has been drawn already before.

Adding the Progress and Color properties

Next, let's add the properties for the progress value and the colors. Our Progress property will be of type float, because SkiaSharp uses float and thus we don't need to use any typecasts. We also add BaseColor and ProgressColor properties of type Color (Microsoft.Maui.Graphics.Color). Our properties will be bindable and should look like this:

public float Progress
{
    get => (float)GetValue(ProgressProperty);
    set => SetValue(ProgressProperty, value);
}

public Color ProgressColor
{
    get => (Color)GetValue(ProgressColorProperty);
    set => SetValue(ProgressColorProperty, value);
}

public Color BaseColor
{
    get => (Color)GetValue(BaseColorProperty);
    set => SetValue(BaseColorProperty, value);
}

public static readonly BindableProperty ProgressProperty = BindableProperty.Create(
    nameof(Progress), typeof(float), typeof(ProgressBar), 0.0f, propertyChanged: OnBindablePropertyChanged);

public static readonly BindableProperty ProgressColorProperty = BindableProperty.Create(
    nameof(ProgressColor), typeof(Color), typeof(ProgressBar), Colors.Orange, propertyChanged: OnBindablePropertyChanged);

public static readonly BindableProperty BaseColorProperty = BindableProperty.Create(
    nameof(BaseColor), typeof(Color), typeof(ProgressBar), Colors.LightGray, propertyChanged: OnBindablePropertyChanged);

In order to be able to update the drawn control whenever any of the properties change, we need to call InvalidateSurface() ourselves which we do in a PropertyChanged event handler:

private static void OnBindablePropertyChanged(BindableObject bindable, object oldValue, object newValue)
{
    ((ProgressBar)bindable).InvalidateSurface();
}

Note: SkiaSharp renders the entire control each time OnPaintSurface() is called. This usually happens, when the surface gets invalidated. In order to avoid unnecessary (and expensive) rendering cycles, it's important to limit how often InvalidateSurface() gets called.

Now, we can start drawing the actual control.

Drawing the base

First, we draw the base. For this, we create a new method DrawBase() so that our OnPaintSurface() method doesn't get too crowded. In that new method, we create an instance of SKPath and we add our _drawRect to it, because that's the shape we want to draw as a path. Then, we draw the path by calling DrawPath() on the _canvas and pass the path as well as a SKPaint object which holds information about how to draw the base. We want to fill the entire rectangle with the BaseColor:

private void DrawBase()
{
    using var basePath = new SKPath();

    basePath.AddRect(_drawRect);

    _canvas.DrawPath(basePath, new SKPaint
    {
        Style = SKPaintStyle.Fill,
        Color = BaseColor.ToSKColor(),
        IsAntialias = true
    });
}

Now, we can call DrawBase() at the end of our OnPaintSurface() override:

protected override void OnPaintSurface(SKPaintSurfaceEventArgs e)
{
    base.OnPaintSurface(e);

    _canvas = e.Surface.Canvas; 
    _canvas.Clear(); // clears the canvas for every frame
    _info = e.Info; 
    _drawRect = new SKRect(0, 0, _info.Width, _info.Height);

    DrawBase();
}

When we run our app, we will already see a gray bar:

Great. Let's add some progress!

Drawing the progress

Similar to drawing the base, we will create a new method called DrawProgress(). We will add a rectangle and a SKPaint again, but this time we use the Progress property to determine the width the of the bar which will indicate the actual progress:

private void DrawProgress()
{
    using var progressPath = new SKPath();

    var progressRect = new SKRect(0, 0, _info.Width * Progress, _info.Height);

    progressPath.AddRect(progressRect);

    _canvas.DrawPath(progressPath, new SKPaint
    {
        Style = SKPaintStyle.Fill,
        IsAntialias = true,
        Color = ProgressColor.ToSKColor()
    });
}

In order to draw the actual progress, we must not forget to call our DrawProgress() method in OnPaintSurface():

protected override void OnPaintSurface(SKPaintSurfaceEventArgs e)
{
    base.OnPaintSurface(e);

     _canvas = e.Surface.Canvas;
    _canvas.Clear(); // clears the canvas for every frame
    _info = e.Info;
    _drawRect = new SKRect(0, 0, _info.Width, _info.Height);

    DrawBase();
    DrawProgress();
}

Important: DrawProgress() must be called after DrawBase(), because on a canvas, everything is drawn on top of each other. If we would make the calls the other way around, we wouldn't be able to see the progress being drawn, because the base would cover it entirely.

Before running the app again, let's update our XAML and set the Progress property to a value between 0.0 and 1.0, e.g. 0.4:

<maui:ProgressBar
  WidthRequest="250"
  HeightRequest="5"
  Progress="0.4"/>

Now, when we run the app again, we will see the ProgressBar filling 40% of its entire width:

The progress color is Orange, because that's the default value we provided to our BindableProperty. We can change this by setting the ProgressColor property in our XAML to some other color:

<maui:ProgressBar
  WidthRequest="250"
  HeightRequest="5"
  Progress="0.4"
  ProgressColor="DeepSkyBlue"/>

Then it will look like this (thanks to Hot Reload, we don't even need to restart the app to do this):

🤩 Awesome, our control is ready for use. The Progress value and any of the other properties can be used to bind to a ViewModel or to be set to dynamic or static resources.

Note: You can find the full code including color gradients and animations on GitHub. The complete control is also available on nuget.org.

NuGet

Sharing is caring! In the Open Source realm it's great to sometimes give back to the Community. Personally, I find it rewarding to contribute something useful. It also helps with development projects and to show some of your skills.

If you happen to feel the urge to share your own custom control but struggle with setting up a .nuspec file and create a .nupkg file using the NuGet CLI, fear no more, Visual Studio 2022 17.4 comes to the rescue 🦸🏽‍♂️.

When you right-click on the MAUI Library project (ProgressBar.Maui in our case), select Properties and navigate to the Package section. Turn on package creation by enabling the checkbox where it says Generate NuGet package on build. Set a couple of more properties like the version, title, description and authors and you're good to go:

These settings will actually just update the .csproj file and add the following properties to the main PropertyGroup:

<GeneratePackageOnBuild>True</GeneratePackageOnBuild>
<Title>My Amazing Progress Bar</Title>
<Version>1.0.0</Version>
<Authors>YourName</Authors>
<Description>A really cool ProgressBar for .NET MAUI</Description>

When you create a build, Visual Studio will automatically generate a NuGet package for you in the bin folder, which can be used to upload and share your custom control on nuget.org.

Important: Always use Release mode for NuGet packages, never upload Debug versions to nuget.org!

Conclusions and next steps

As I have shown, it is very easy to quickly develop customizable controls by drawing on a canvas without the need of any platform-specific handlers or mappers for .NET MAUI (or renderers when you're familiar with Xamarin.Forms) using SkiaSharp. Visual Studio even makes it easy to share your custom controls with the world without a lot of hazzle.

In future blog posts, I will write about using MAUI Graphics and ways to customize and extend existing controls. In the meanwhile, if you would like to learn more about drawn controls in .NET MAUI, you can also check out Javier Suárez Ruiz's session from .NET Conf 2021.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts. Don't forget to share this with your friends and colleagues who are interested in learning about this topic. Thank you for reading and sharing 💝

Welcome to Part 2 of my mini-series about Multi-Targeting in .NET MAUI!

In Part 1, I have explored and demonstrated the built-in functionality of the default .NET MAUI single-project approach providing platform-specific implementations inside the different platform folders. For simple uses cases this approach is completely appropriate and for many scenarios it is absolutely sufficient. However, as soon as unit tests and more complex scenarios come into play, such as database access or user authentication, we might need to take a different approach.

Attention: I have upgraded the sample project from .NET 6.0 to .NET 7.0 which has been released a few days ago. Gerald Versluis has a short blog article about how to do exactly that.

In Part 2, I am now going to show what happens to our previous implementation when we add a Unit Test project to our solution and how to solve the arising issues. We will use filename-based Multi-Targeting for this. I am not going to take a deep dive into Unit Tests here, because that is an entire topic on its own.

Note: I will write a blog post about Unit Tests in the future. Until then, you may want to check out the video by Gerald about how to add a Unit Test project for your MAUI app.

Unit Tests require a different Target Platform

Looking back at Part 1, the following platforms were targeted by our single-project:

• Android
• iOS
• MacCatalyst
• Windows

However, as soon as a Unit Test project is added and a project reference is set to our single project, we will see the following issue (I personally prefer NUnit, but the approach is identical for xUNit, I have tried this with both testing frameworks):

😱 The project reference is invalid!

We can also find the following error message in the Error List:

Project MauiSamples is not compatible with net7.0 (.NETCoreApp,Version=v7.0). Project MauiSamples supports:
  - net7.0-android33.0 (.NETCoreApp,Version=v7.0)
  - net7.0-ios16.0 (.NETCoreApp,Version=v7.0)
  - net7.0-maccatalyst15.4 (.NETCoreApp,Version=v7.0)
  - net7.0-windows10.0.19041 (.NETCoreApp,Version=v7.0)    MauiSamples.Tests

This message tells us the following: None of the targets is supported by the MauiSamples.Tests project that was added.

The reason for this is that Unit Test projects should be platform agnostic and NUnit (as well as xUnit) projects target plain .NET, but none of the platform-specific flavors:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- the test project can only reference plain .NET (net7.0 in this case) -->
    <TargetFramework>net7.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Maui.Dependencies" Version="6.0.547" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.3.2" />
    <PackageReference Include="Moq" Version="4.18.2" />
    <PackageReference Include="NUnit" Version="3.13.3" />
    <PackageReference Include="NUnit3TestAdapter" Version="4.2.1" />
    <PackageReference Include="NUnit.Analyzers" Version="3.3.0" />
    <PackageReference Include="coverlet.collector" Version="3.1.2" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\MauiSamples\MauiSamples.csproj" />
  </ItemGroup>

</Project>

Essentially, we are missing the net7.0 platform target in the configuration of our MAUI project. This can easily be resolved by adding net7.0 as another target platform to our MAUI single-project (MauiSamples.csproj in the example). We also need to add an extra condition to the OutputType, because our Unit Test project expects a Dynamic Link Library (.dll) and not an Executable (.exe):

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- add net7.0 target framework here -->
    <TargetFrameworks>net7.0;net7.0-android;net7.0-ios;net7.0-maccatalyst</TargetFrameworks>
    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net7.0-windows10.0.19041.0</TargetFrameworks>

    <!-- add this condition as well -->
    <OutputType Condition="'$(TargetFramework)' != 'net7.0'">Exe</OutputType>

    <!-- skipping other settings -->
</Project>

After making these changes our project reference finally is valid 🥳:

Limitations of the built-in approach

But wait, something else seems to be wrong: Our build still fails with a new error 😱:

Error    CS1061    'MainPage' does not contain a definition for 'SayHello' and no accessible extension method 'SayHello' accepting a first argument of type 'MainPage' could be found (are you missing a using directive or an assembly reference?)    MauiSamples (net7.0)

That's because we did not provide an implementation of the SayHello() extension method for our new net7.0 target platform. We've hit a limitation of the single-project's built-in approach for Multi-Targeting, because there is no directory for non-platform-specific implementations.

In order to remedy this, we can go back to using a preprocessor directive after all:

    private async void Button_OnPressed(object sender, EventArgs e)
    {
#if ANDROID || IOS || MACCATALYST || WINDOWS
        await this.SayHello();
#endif
    }

😓 Bummer! That's what we tried to get rid of in the first place (despite it now being shorter than before). At least, we can write unit tests for our business logic now and still end up with a cleaner setup than what we initially started with in Part 1. A trade-off? Not in the least. Just keep reading.

Solution

Back to square one (regarding the avoidance of preprocessor directives)? Not at all. It's merely a limitation of the .NET MAUI single-project setup. The solution for this is filename (and/or folder) based Multi-Targeting.

The official documentation for this is very useful and I recommend studying it if you want to get a better understanding of what the conditions in the following paragraphs mean. However, I am going to make some alterations to the solution proposed in the official documentation, because we don't want to be limited to a specific major version of .NET.

Instead of continuing with the SayHello() example, I will get into actual platform-specific APIs now and how they can be called from within a ViewModel. That way, we can compare the different approaches within the same solution in the sample repository.

Filename-based Multi-Targeting

When dealing with different platforms, especially when writing services or using platform-specific APIs that share a common interface, it makes sense to group the different implementations together. The default Multi-Targeting approach does not give us this option, while the filename-based approach does. Let's have a look at how this works.

First, we need to update our project file and add the following <ItemGroup> elements:

<!-- Android -->
<ItemGroup Condition="$(TargetFramework.StartsWith('net')) == true AND $(TargetFramework.Contains('-android')) != true">
  <Compile Remove="**\**\*.Android.cs" />
  <None Include="**\**\*.Android.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<!-- iOS -->
<ItemGroup Condition="$(TargetFramework.StartsWith('net')) == true AND $(TargetFramework.Contains('-ios')) != true">
  <Compile Remove="**\**\*.iOS.cs" />
  <None Include="**\**\*.iOS.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<!-- Mac Catalyst -->
<ItemGroup Condition="$(TargetFramework.StartsWith('net')) == true AND $(TargetFramework.Contains('-maccatalyst')) != true">
  <Compile Remove="**\**\*.MacCatalyst.cs" />
  <None Include="**\**\*.MacCatalyst.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<!-- Windows -->
<ItemGroup Condition="$(TargetFramework.StartsWith('net')) == true AND $(TargetFramework.Contains('-windows')) != true">
  <Compile Remove="**\*.Windows.cs" />
  <None Include="**\*.Windows.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<!-- .NET -->
<ItemGroup Condition="!($(TargetFramework.StartsWith('net')) == true AND $(TargetFramework.EndsWith('.0')) == true AND $(TargetFramework.Contains('-')) != true)">
  <!-- e.g net6.0 or net7.0 -->
  <Compile Remove="**\*.net.cs" />
  <None Include="**\*.net.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

With these <ItemGroup> elements we are telling the build system to only compile certain files when a specific platform is selected and otherwise simply ignore them based on their filename. For example, we only want the Android-specific C# files with the Android.cs suffix to be compiled when the target platform is net6.0-android or net7.0-android (or higher). In all other cases, the files are removed from compilation.

Note: Often, you will come across similar setups where the .NET version is hard-coded in the conditions of the <ItemGroup> elements, like in the official documentation. That's fine if you don't plan to upgrade to newer .NET versions, but I just switched from net6.0 to net7.0and this way, I had less to adjust in my project file.

Essentially, instead of using conditional compilation with preprocessor directives, we are now using filename-based conditional compilation.

A common interface

Having the filename-based conditional compilation in place, we can now create a new folder in our project and add platform-specific implementations to call some platform-specific APIs. Let's call the folder Services\Device. In this folder, we can then add an interface that I call IDeviceService and which declares a single method to set the screen brightness:

namespace MauiSamples.Services.Device;

public interface IDeviceService
{
    void SetScreenBrightness(float brightness);
}

This can be used for Dependency Injection and Unit Tests, which we will have a look at a little further down, but let's first create the platform-specific implementations.

Since we are dealing with a platform-agnostic scenario, meaning that our business logic does not know anything about the platform it is being executed on, we need to provide implementations for all the possible platforms that are part of our single project, even the ones that are unused. We will do this in a sub-folder called Platform and with the following names:

Note that we have C# files for each of our five target platforms (including plain .NET) and also a DeviceService.shared.cs file.

A shared implementation

First, we implement our shared class. We are going to use partial classes for this setup and DeviceService.shared.cs will serve as the shared part of our implementation, because we may have common methods and properties that may be shared among the different platform implementations.

Note: Technically, it would also be possible to do this without the shared part and without partial classes.

namespace MauiSamples.Services.Device.Platform;

public partial class DeviceService : IDeviceService
{
    private static DeviceService _instance;
    public static DeviceService Instance => _instance ??= new DeviceService();

    private DeviceService() {}

    public partial void SetScreenBrightness(float brightness);
}

Note how this shared part does not provide a body for the SetScreenBrightness() method. The reason for this is that each platform should provide its own implementation. Therefore, the body will be defined in the platform-specific code files.

For simplicity and ease of access to other APIs that are not covered in this article, I have also created a singleton for our DeviceServices class.

Note: Singletons are commonly considered to be an anti-pattern, because they may violate the Single Responsibility Principle and are often misused for so-called God-objects (global classes that contain a lot of shared logic and information). However, you will come across singletons in cross-platform and API development quite often. When used appropriately, they deserve some love, too.

The platform-specific implementations

Now that we have the interface and the shared code, we can finally create the platform-specific implementations. To keep things short, I will only focus on Android and iOS here, using the screen brightness example.

Important: Just like in the built-in Multi-Targeting approach from Part 1, it is important that the namespace and class name are exactly the same for each implementation.

.NET, Windows and MacCatalyst

Our plain .NET, Windows and MacCatalyst implementations will only be empty stubs:

namespace MauiSamples.Services.Device.Platform;

partial class DeviceService
{
    public partial void SetScreenBrightness(float brightness)
    {
        //ignore
    }
}

Only mobile platforms like Android and iOS support setting the screen brightness directly (as far as I know).

Android

using AndroidPlatform = Microsoft.Maui.ApplicationModel.Platform;

namespace MauiSamples.Services.Device.Platform;

partial class DeviceService
{
    public partial void SetScreenBrightness(float brightness)
    {
        if (AndroidPlatform.CurrentActivity?.Window?.Attributes == null)
        {
            return;
        }

        var attributes = AndroidPlatform.CurrentActivity.Window.Attributes;
        attributes.ScreenBrightness = brightness;
        AndroidPlatform.CurrentActivity.Window.Attributes = attributes;
    }
}

iOS

using UIKit;

namespace MauiSamples.Services.Device.Platform;

partial class DeviceService
{
    public partial void SetScreenBrightness(float brightness)
    {
        UIScreen.MainScreen.Brightness = brightness;
    }
}

And just like that, we have our platform-specific API calls hidden behind a common interface, accessible either through our singleton or via the interface through Depedency Injection. We can now use the singleton instance of our DeviceService class and call the SetScreenBrightness() method from anywhere in our business logic without knowing the current target platform. We can even apply DIP and inject the DeviceService as a dependency using the IDeviceService interface.

The really cool thing is that we can use platform-specific namespaces inside these implementations without any build errors on the other target platforms, because we use filename-based conditional compilation under the hood.

Putting it all to use

To keep things short, I am using MVVM Code Generation for the ViewModel and I will only show a single Unit Test for demonstration purposes.

James Montemagno has a great video about the MVVM Source Generators. I will also dig deeper into Code Generation for MVVM in a separate blog post.

The View and its ViewModel

Let's start with the ViewModel. I will call this class MainViewModel, because it will be the ViewModel for my MainPage and it only contains a constructor, two methods to set the screen brightness and also a private field for our IDeviceService interface from above. The dependency on the specific DeviceService implementation can be injected via the constructor that way.

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using MauiSamples.Services.Device;

namespace MauiSamples.ViewModels;

[ObservableObject]
public partial class MainViewModel
{
    private readonly IDeviceService _deviceService;

    public MainViewModel(IDeviceService deviceService)
    {
        _deviceService = deviceService;
    }

    [RelayCommand]
    public void SetHighBrightness()
    {
        _deviceService.SetScreenBrightness(1.0f);
    }

    [RelayCommand]
    public void SetLowBrightness()
    {
        _deviceService.SetScreenBrightness(0.1f);
    }
}

That's it already for the ViewModel. It can now be used as the BindingContext for the MainPage.xaml.cs:

public MainPage()
{
    InitializeComponent();
    BindingContext = new MainViewModel(DeviceService.Instance);
}

Note how the singleton is used to inject the dependency with the platform-specific implementation (decided at compile-time, remember?) into the ViewModel, which does not know anything at all about the different platforms.

In the MainPage.xaml we can now add two buttons and bind to the commands (which are auto-generated for us):

<HorizontalStackLayout
  Spacing="30"
  HorizontalOptions="Center">
  <Button
    Text="Dim Display"
    HorizontalOptions="Start"
    WidthRequest="100"
    Command="{Binding SetLowBrightnessCommand}"/>
  <Button
    Text="Undim Display"
    HorizontalOptions="End"
    WidthRequest="100"
    Command="{Binding SetHighBrightnessCommand}"/>
</HorizontalStackLayout>

Awesome, now we can dim and undim the display of our mobile device. 🍾

Note: Like with many other platform-specific APIs, this only works on real devices, emulators/simulators do not support dimming. If you would like to see the code in action, check out the GitHub repository for this post and run the app on a real Android or iOS device.

Writing Unit Tests

Perfect, we can not only dim our display now, we can also write Unit Tests for our ViewModel in our test project, because we have an interface that we can use to mock the dependency (I'm using the Moq library here, but any other mocking framework will work just as well):

using MauiSamples.Services.Device;
using MauiSamples.ViewModels;
using Moq;

namespace MauiSamples.Tests.ViewModels;

[TestFixture]
public class MainViewModelTests
{
    [Test]
    public void SetHighBrightness_SetScreenBrightnessCalled()
    {
        //arrange
        var deviceServiceMock = new Mock<IDeviceService>();
        var vm = new MainViewModel(deviceServiceMock.Object);

        //act
        vm.SetHighBrightness();

        //assert
        deviceServiceMock.Verify(service => service.SetScreenBrightness(It.IsAny<float>()), Times.Once);
    }
}

Wonderful. My developer heart is happy and full of joy. 💖

Conclusions and next steps

As I have demonstrated, Multi-Targeting is a marvelous way to support platform-specific APIs from within a single MAUI app project. The need for platform-specific projects we know from Xamarin.Forms is gone, drastically reducing development and maintenance effort while still allowing to implement platform-specific functionality.

With filename-based Multi-Targeting, we can group platform implementations together, use a common interface and share some parts of the code to reduce code duplication. A .NET MAUI project doesn't require a variety of different platform and test projects to be maintained separately.

Even custom components and MAUI class libraries can make use of the Multi-Targeting approaches that I have presented in this mini-series, as you will see in future blog posts.

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts.

I am a huge fan of the Dependency Inversion Principle (DIP). I apply it via Dependency Injection (DI) and Inversion of Control (IoC) a lot in my projects, because I like developing loosely coupled, well structured software components that are easy to maintain and extend.

However, when it comes to mobile application development and especially to UI related topics that do not involve any business logic, applying the DIP for platform-specific APIs can be quite cumbersome and seems like overkill, because it often involves Interfaces and IoC containers (or the Dependency Service in Xamarin.Forms).

In this blog post, I am going to explore an alternative approach to using platform-specific code that comes already built-in with .NET MAUI: Multi-Targeting. It is a clean way to implement and call platform-specific APIs, e.g. to dim the display, set the volume for audio playback or display a notification to the user without requiring interfaces and IoC containers.

In the .NET realm, the term has been around for a while already - .NET MAUI just makes heavy use of it with the single project approach. In Xamarin.Forms, you would need to create an interface, then create the different implementations in the platform projects and either register the implementation with the Dependency Service or with any other IoC container. That's not necessary anymore in .NET MAUI. Interfaces and Dependency Injection may still be required for complex, business-logic related scenarios, but this requirement has become optional for simple platform-specific APIs.

Hello from [Platform]!

In this first part, we will simply display a message to the user from within an event handler for a simple Button press event:

<Button Text="Say Hello" Pressed="Button_OnPressed" />

When the Button is pressed, a "Hello from [Platform]!" message is shown and depending on the platform, it will either be "Hello from Android!", "Hello from iOS!", "Hello from Windows!" or "Hello from MacCatalyst!".

Let's start with the simplest (and older) form of condition-based access to platform-specific code.

Conditional Compilation

One approach to build and ship platform-specific implementations is to use preprocessor directives (like #define, #if, #elif, etc.) and only compile certain bits of code when a specific target platform is selected. This is called conditional compilation and like the name says, specific parts of the code only get compiled when certain conditions are met.

For example, if we wanted to display an alert message with a different text on each platform, we could simply write the following code somewhere in our UI code, e.g. in an event handler that gets triggered when a Button was pressed:

    private async void Button_OnPressed(object sender, EventArgs e)
    {
#if ANDROID
        await DisplayAlert("Hello", "Hello from Android!", "OK");
#elif IOS
        await DisplayAlert("Hello", "Hello from iOS!", "OK");
#elif WINDOWS
        await DisplayAlert("Hello", "Hello from Windows!", "OK");
#else
        await DisplayAlert("Hello", "Hello from another platform (MacCatalyst, Tizen, ...)", "OK");
#endif
    }

Tapping the Button now triggers the display of an alert that looks like this on Android and very similar on the other platforms, just with different text:

This works and certainly is a valid approach for simple scenarios, but the code doesn't look great. As a general rule, preprocessor directives should be handled with care and should be avoided whenever possible as they lead to code that is illegible and difficult to maintain. They also bear the danger that some conditions are set incorrectly and then debugging becomes difficult quickly.

Imagine having to write a platform helper class that provides access to various different platform-specific APIs. Muddling them all together quickly becomes messy. Wouldn't it be better to separate the different implementations per platform instead? I think so, too.

Let's look at one of the alternatives.

A simple, but better approach

Essentially, the built-in Multi-Targeting in .NET MAUI allows developers to implement and call platform-specific code from a shared context while only building and shipping the relevant parts of the code for the target platform.

The single project created via the default template comes with a Platforms folder and sub-folders for each separate platform, e.g. Android, iOS and so on. This structure provides a basic setup; the contents of the individual platform folders are only built and shipped for the targeted platform.

This allows us to create platform-specific assets and even redefine the same class inside the same namespace per platform without any build conflicts, all while keeping the irrelevant parts from the different platforms out of the resulting platform-specific app.

Now, instead of using conditional compilation, we can create a separate file in each of the platform-specific folders that the single project comes with by default and provide an implementation there. This will certainly work and probably is the best for simple scenarios like the one shown above with the DisplayAlert() call.

Let's create a Messages.cs for each platform with the following content:

Android

namespace MauiSamples;

public static class Messages
{
    public static async Task SayHello(this Page page)
    {
        await page.DisplayAlert("Hello", "Hello from Android!", "OK");
    }
}

iOS

namespace MauiSamples;

public static class Messages
{
    public static async Task SayHello(this Page page)
    {
        await page.DisplayAlert("Hello", "Hello from iOS!", "OK");
    }
}

MacCatalyst

namespace MauiSamples;

public static class Messages
{
    public static async Task SayHello(this Page page)
    {
        await page.DisplayAlert("Hello", "Hello from MacCatalyst!", "OK");
    }
}

Windows

namespace MauiSamples;

public static class Messages
{
    public static async Task SayHello(this Page page)
    {
        await page.DisplayAlert("Hello", "Hello from Windows!", "OK");
    }
}

After adding all the Message.cs files, our project structure looks as follows (note that each platform has its own Messages implementation now):

Important: Please note that the namespace and the class name must be identical in each of the Messages.cs files in order for this approach to work. This is a general rule for multi-targeted APIs.

We can now update the event handler of the Button as follows:

    private async void Button_OnPressed(object sender, EventArgs e)
    {
        await this.SayHello();
    }

As we can see, the preprocessor directives are gone and we can call the SayHello() method as an extension method on our MainPage in a single line without having to worry about invoking platform-specific code anymore, because the build system takes care of that for us. It is much cleaner, more legible and easily maintained and extended.

It still works (showing Windows this time):

Conclusions and next steps

The built-in Multi-Targeting approach of .NET MAUI is quite powerful, it works beautifully and usually suffices for simple uses cases like the one presented in this article. I have only shown how to handle the platform differences, no actual platform-specific APIs have been invoked so far. I will get into actual platform-specific APIs in some of my upcoming blog posts (e.g. for setting the screen brightness on each platform).

In Part 2, I will explore more advanced setups that involve unit tests and dependency injection, which require a different approach to Multi-Targeting. I will show how to setup your project using filename-based Multi-Targeting and partial classes for platform-specific implementations. So, stay tuned!

If you enjoyed this blog post, then follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post so you don't miss out on any future posts.

A custom company or app logo that shows up while an app is starting is a nice eye catcher and helps with strengthening the recognition of a brand. In this blog post I want to show you how you can easily modify the splash screen which comes already prepared with new MAUI app projects with your own logo and background.

Considerations

In the past, apps would show complex graphics or fancy animations on the splash screen. With the advent of newer mobile operating system versions, especially since Android 12.0, mobile app developers have less options for the customization of the splash screen of an app, at least for simple scenarios.

For the purpose of a unified look and feel, the splash screen should be simple and feature only a custom logo and a simple background. Modern apps have relatively low start up latencies, so that the splash screen will not be visible for a long time anyway. Therefore, I will only focus on adding a custom logo and background color, advanced scenarios including animations and splash screen activities won't be covered.

However, as an extra goody, I will show you how to change the theme of the splash screen based on the system theme on Android.

Note: Starting with Android 12.0, the splash screen icon will be displayed inside a circular frame and everything outside that frame will be hidden by a mask. For more on this, please refer to the official documentation.

The default splash screen

This is what the default splash screen of the MAUI app template project looks like:

The logo and background color are defined in the .csproj file of your MAUI app project. You can edit the file by right-clicking on the project and selecting "Edit Project File". Then scroll down to the <PropertyGroup> that contains the following:

<!-- Splash Screen -->
<MauiSplashScreen Include="Resources\Splash\splash.svg" Color="#512BD4" BaseSize="128,128" />

Add your own logo

In order to add your own logo, the only thing you need to do is replace the splash.svg with your own logo. As an example, we will just use the dotnet-bot.svg which comes with the template, but we give it a different name, e.g. mysplashscreen.svg:

<!-- Splash Screen -->
 <MauiSplashScreen Include="Resources\Splash\mysplashscreen.svg" Color="#512BD4" BaseSize="128,128" />

Important: The logo should be square and with a transparent background for best results.

Note: At the time of writing, there is an issue with the one of the build actions of MAUI, which requires giving the splash screen image a completely new name each time it is changed. This will be fixed in a future release.

Change the background color

Now, we just need to change the background color of the splash screen to make it look great:

<!-- Splash Screen -->
 <MauiSplashScreen Include="Resources\Splash\mysplash.svg" Color="#000000" BaseSize="128,128" />

Result

Pretty cool, we now have a custom splash screen that works on Android and iOS:

iOS

Android

Change appearance based on Android system theme

On Android, there is a little trick on how to go even a step further and change the background color (and status bar theme) for the splash screen depending on the selected system theme. For this, we can take advantage of the night mode feature to show the black background only for dark mode and a white background for white mode, which is a neat little extra.

Light Mode

In your MAUI project, navigate to the Platforms/Android/Resources/ folder and, if not present yet, add a values subfolder. In this folder, create two files (or edit the existing ones):

• colors.xml
• styles.xml

Attention: The styles.xml actually probably already exists and is simply hidden from the project. If so, right-click on the values folder and select Add -> Existing Item and then select the styles.xml file in that location.

Then, in your colors.xml define some colors, e.g.:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <color name="colorPrimary">#c2c2c2</color>
  <color name="colorPrimaryDark">#ffffff</color>
  <color name="colorAccent">#3c3c3c</color>
</resources>

Next, create your own Theme in the styles.xml, inherit from Maui.SplashTheme and set your color for the android:windowSplashScreenBackground item:

<?xml version="1.0" encoding="utf-8" ?>
<resources>
  <style name="MyTheme" parent="Maui.SplashTheme">
    <item name="android:windowSplashScreenBackground">@color/colorPrimaryDark</item>
    <item name="android:windowLightStatusBar">true</item>
  </style>
</resources>

This will set up your splash screen color when the user is using the Light theme of Android.

Dark Mode

For Dark theme, you need to do essentially the same as for the Light theme, with a small difference.

In your MAUI project, add the following subfolder: Platforms/Android/Resources/values-night (note the -night suffix). In this folder, again create the two files:

• colors.xml
• styles.xml

In your colors.xml define some colors, e.g.:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <color name="colorPrimary">#c2c2c2</color>
  <color name="colorPrimaryDark">#000000</color>
  <color name="colorAccent">#c2c2c2</color>
</resources>

Again, create your own Theme in the styles.xml, inherit from Maui.SplashTheme and set your color for the android:windowSplashScreenBackground item:

<?xml version="1.0" encoding="utf-8" ?>
<resources>
  <style name="MyTheme" parent="Maui.SplashTheme">
    <item name="android:windowSplashScreenBackground">@color/colorPrimaryDark</item>
    <item name="android:windowLightStatusBar">false</item>
  </style>
</resources>

This will set up your splash screen color when the user is using the Dark theme of Android.

When you're done, your folder structure should look something like this:

Final Step

Finally, we still need to apply our custom theme to our MainActivity like this:

[Activity(Theme = "@style/MyTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity { }

Android: Light Mode

Note: The background color of the image can only be set once in the <MauiSplashScreen> build action and therefore is not adaptive, unfortunately. Notice the round image mask on Android as described in the beginning, as well.

Android: Dark Mode

Conclusions

Setting up a simple splash screen is very easy with .NET MAUI, because the <MauiSplashScreen> build action pretty much does all the work for you as it automatically generates everything for you. Unlike Xamarin.Forms, there is no need to create your own storyboard for iOS, for example, anymore.

If you enjoyed this blog post, you may want to follow me on LinkedIn, subscribe to this blog and star the GitHub repository for this post.

I absolutely love dark app themes. As a person working a lot in front of computer screens and using mobile devices a lot, I have come to appreciate the ease on the eyes that Dark (or Night) Modes of software and mobile apps provide. In this blog post, I would like to show a simple way to implement this wonderful feature in order to provide a flawless user experience to your app's users without having to manipulate a ResourceDictionary at run-time.

As the convention goes these days, users should have the option to choose whether to use a Dark or Light Theme or to simply follow the system setting. .NET MAUI conveniently supports "Light" and "Dark" App Themes right out of the box. The sample Shell app even comes pre-configured with some styles that use the built-in markup extension AppThemeBinding. Let's explore how to take advantage of this. The code for this sample implementation can be found in my GitHub repository.

The UserAppTheme property and Styles

The Application class (App.xaml.cs) comes with a property of the enum type AppTheme called UserAppTheme which can be set to change the current theme:

// dark theme
UserAppTheme = AppTheme.Dark;

// light theme
UserAppTheme = AppTheme.Light;

// follow system default
UserAppTheme = AppTheme.Unspecified;

Coupled with the AppThemeBinding markup extension inside some Style elements in a ResourceDictionary (e.g. defined in the Styles.xaml file) this would already to suffice to set the theme once and be done:

<Style TargetType="ContentPage" ApplyToDerivedTypes="True">
    <Setter Property="BackgroundColor" Value="{AppThemeBinding Light={StaticResource White}, Dark={StaticResource Black}}" />
</Style>

Our app would now just be either shown with a black or white page background depending on the hard-coded value for the UserAppTheme property. This is already pretty neat, but we want to let the user decide. So let's do that.

Our own Theme class

In order to provide a meaningful user experience, we are going to implement our own Theme class which holds the AppTheme as well as a DisplayName.

The advantages of this class will become apparent further down. Hint: The DisplayName could be used in advanced scenarios to show a translated string depending on the selected language, but we won't cover localization of string resources in this article.

public sealed class Theme
{
    public static Theme Dark = new(AppTheme.Dark, "Night Mode");
    public static Theme Light = new(AppTheme.Light, "Day Mode");
    public static Theme System = new(AppTheme.Unspecified, "Follow System");

    public static List<Theme> AvailableThemes { get; } = new()
    {
        Dark,
        Light,
        System
    };

    public AppTheme AppTheme { get; }
    public string DisplayName { get; }

    private Theme(AppTheme theme, string displayName)
    {
        AppTheme = theme;
        DisplayName = displayName;
    }
}

Since the theme can usually be selected in a Settings section of an app, we will also implement a small SettingsService class.

The SettingsService

In this example, we simply create a small class that implements the INotifyPropertyChanged interface and use it as a singleton for convenience. I am skipping advanced topics like Dependency Injection and MVVM Code Generation.

public class SettingsService : INotifyPropertyChanged
{
    private static SettingsService _instance;
    public static SettingsService Instance => _instance ??= new SettingsService();

    private SettingsService()
    {
        // set the default (in advanced scenarios, this could be read from the preferences)
        Theme = Theme.System;
    }

    private Theme _theme;
    public Theme Theme
    {
        get => _theme;
        set
        {
           if(_theme == value) return;
            _theme = value;
           OnPropertyChanged();
        }
    }

    //...
}