Introducing the .NET MAUI Community Toolkit

It is very common for developers to replicate elements used in one project in another one, especially when working on several .NET MAUI projects. This is true with value converters, custom views, and behaviors. In addition, sometimes developers need to build their own views that are common in modern mobile app design, but that the .NET MAUI code base does not include. To simplify reusing elements across projects, Microsoft offers a new library called the .NET MAUI Community Toolkit. This chapter introduces the library and will explain some conventions that I will be using across the book. If you have worked with Xamarin.Forms in the past and you have used the Xamarin.Forms Community Toolkit, you will find a lot of similarities and the same approach.

What to expect from this book

By reading this book, you will be able to use all the new elements offered by the .NET MAUI Community Toolkit and this will improve your productivity. However, this assumes you already have quite substantial knowledge of .NET MAUI as a development platform and of Microsoft Visual Studio 2022 as the development environment you use to build apps with MAUI. The main reason for this is to keep the length of this ebook brief enough to fit the Succinctly series and to provide you with productivity tools in a faster way, so it’s not possible to explain how .NET MAUI works. If you are a beginner, I recommend you read my free ebook .NET MAUI Succinctly (Coming Soon) first, since it will give you all the necessary knowledge you need. In addition, and for exactly the same reasons, it will not be possible to describe the architecture and the implementation of elements unless strictly necessary. If you need to understand more about architecture and implementation, you can always look at the official Microsoft documentation and investigate the source code yourself. You will discover that the backing code is not complex at all and that it is very well commented.

 Note: At the time of this writing, the latest stable version of the .NET MAUI Community Toolkit is 3.1.0. Keep in mind that this library continuously evolves, which means that new elements might be added over time after the release of this book. This is another reason to bookmark the documentation.

.NET MAUI Community Toolkit: solving common problems

The .NET MAUI Community Toolkit is an open-source collection of reusable elements for cross-platform development with .NET MAUI that works with all the supported OSs. It includes views, value converters, behaviors, animations, color themes, and helper classes that you can reuse across projects and that solve common problems without having to manually share your code or reinvent the wheel every time. Technically speaking, it is a .NET MAUI library that you can quickly add to your projects via NuGet and for which a GitHub repository is available. This repository is very important, not only because of the availability of the library’s source code, but also for the availability of sample code and the product road map.

Using the .NET MAUI Community Toolkit

The .NET MAUI Community Toolkit is available to the general public as a NuGet package. At the time of writing, the latest version available is 3.1.0 and it can be added to your MAUI solution in the usual way via the NuGet Package Manager. Figure 1 shows how the library appears in the NuGet Package Manager user interface of Visual Studio 2022.

Figure 1: Installing the .NET MAUI Community Toolkit

There is also another NuGet package called CommunityToolkit.Maui.Markup, which is only necessary if you want to work with C# markup extensions. This is discussed in Chapter 7. Once you have installed the library, you will be able to use all the objects discussed in this book. The last step is enabling the Community Toolkit in your projects. This is accomplished by changing the invocation of the MauiApp.CreateBuilder method in the MauiProgram.cs file as follows.

       var builder = MauiApp.CreateBuilder()

#if DEBUG

                                                        .UseMauiCommunityToolkit()

#else

                                                        .UseMauiCommunityToolkit(options =>

       {

              options.SetShouldSuppressExceptionsInConverters(false);                   options.SetShouldSuppressExceptionsInBehaviors(false);             options.SetShouldSuppressExceptionsInAnimations(false);

       })

#endif

                                                        .UseMauiCommunityToolkitMarkup()                                  .UseMauiApp<App>();

The UseMauiCommunityToolkit extension method enables all the objects in the library, and it disables exceptions for converters, behaviors, and animations when not in debugging mode. UseMauiCommunityToolkitMarkup enables C# markup extensions to define the user interface in code. However, it is not necessary to create a new project now. In the next section, I will explain how to use the official sample app.

Setting up the development environment

It is possible to combine efficiency, productivity, and learning by using the official sample app created by Microsoft to demonstrate how the .NET MAUI Community Toolkit works. The main reason is that it is very well organized, so all the discussions and examples in the book will be based on the official sample. In addition, it is always updated as new releases are available, so you can more easily stay up to date. Having said that, first open the GitHub repository for the project. Click the Code button as shown in Figure 2.

Figure 2: The Official Repository for the .NET MAUI Community Toolkit

At this point, you can decide how to get the source code between cloning the repository in Visual Studio or downloading the full ZIP archive. The repository contains the full source code of the library, plus the source code for a complete sample application. If you want to explore the source code for the .NET MAUI Community Toolkit, you can open the Community.Maui.sln solution file in Visual Studio. It is located in the src subfolder. For the purposes of this book, the solution you need to open is called CommunityToolkit.Maui.Sample.sln, which is in the samples folder of the repository. Figure 3 shows how the solution appears in Solution Explorer.

Figure 3: The Official Sample Project in Visual Studio 2022

The project of interest across the book is the shared project called CommunityToolkit.Maui.Sample that you can see in Figure 3. This contains the sample pages, viewmodels, assets, and resources required to build the sample app, which provides access to examples of all the objects exposed by the Toolkit.

Tip: The reason I told you to download the source code for the full repository instead of only for the sample app is that the .NET MAUI Community Toolkit in the sample project is not downloaded from NuGet. Rather, it is referenced via the Visual Studio projects in the repository. If you only downloaded the sample app source code, you would have to manually install the NuGet package and make some changes, wasting your time.

Choose a platform project as the startup project, select an appropriate device (either physical or emulated), and then press F5 to start the sample application. In this book, I will use the Android platform project and an Android emulator, but everything will work similarly on a different device. When the app is running, you will see a welcome page and the list of examples in the flyout menu. When you click an item, you access a sublist of buttons, and each button opens examples about a specific feature. If you look at Figure 4, starting from left to right, you can see a sample representation of this flow based on the Behaviors feature, but it will work the same for all the features.

Figure 4: The Official Sample App Running

In addition to discovering and running examples, it is a good idea to define some conventions that will be used across the book to simplify your reading.

Conventions used in this book

From the next chapter, you will start looking at all the available elements in the .NET MAUI Community Toolkit, so it is useful to provide you with some standards that are shared across the book but will not be repeated every time. Because each element is presented with an example in the official sample app, I will always point you to the page in the app and also tell you where to find the XAML page files in the project. XAML page files are located in the Pages folder of the project. Each page populates its own data context with a dedicated viewmodel class. Viewmodel.cs files are located within specific subfolders of the ViewModels folder of the project. They are declared and assigned directly in the XAML of the page, and they are identified via either the vm: or the viewmodel: XML namespaces. Viewmodel and page names are based on the name of the object currently discussed. For example, for the ImageResourceConverter class, the sample page is called ImageResourceConverterPage.xaml and the viewmodel is called ImageResourceConverterViewModel.cs. Pages that use views, converters, behaviors, or any other feature provided by the .NET MAUI Community Toolkit will always include the following namespace declaration.

xmlns:mct="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

In this way, a view like the UniformItemsLayout will be accessed as follows.

<mct:UniformItemsLayout />

Now that you know to what the mct identifier refers, it will not be repeated in the next chapters, nor will the other standards, for the sake of simplicity.

Chapter summary

The .NET MAUI Community Toolkit is an open-source project backed by Microsoft that provides common, reusable elements for .NET MAUI. In this chapter, you received an introduction to the library, you saw how to get the sample source code that will be used in the book, and you saw how to set up the development environment. Then, you learned about conventions used in the book that will make your reading better and clearer. It is now time to start working with all the goodies that the .NET MAUI Community Toolkit has to offer, and certainly the more natural way to do so is looking at new views.