{"id":49199,"date":"2022-05-17T10:40:35","date_gmt":"2022-05-17T17:40:35","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/xamarin\/?p=49199"},"modified":"2022-05-18T23:48:19","modified_gmt":"2022-05-19T06:48:19","slug":"migrating-mrgestures-to-dotnet-maui","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/xamarin\/migrating-mrgestures-to-dotnet-maui\/","title":{"rendered":"Migrating MR.Gestures from Xamarin.Forms to .NET MAUI"},"content":{"rendered":"
\n

Note: This is a Guest Blog Post by Michael Rumpler<\/a>. Michael has been a freelance C# developer since 2003, switching from web to mobile in 2014 upon the introduction of Xamarin.Forms.<\/p>\n<\/blockquote>\n

Let’s first provide a brief introduction to the MR.Gestures Library<\/a> to explain why it exists and the problem it solves.<\/p>\n

When Xamarin.Forms was released in 2014 it only provided TapGestureRecognizer<\/code> which had to be added to a GestureRecognizers<\/code> collection. This implementation was always a bit of a code-smell for me. It copied the iOS + Android APIs, but iOS and Android (at the time) only used that architecture because Objective-C and Java didn’t support events. However, In .NET and C# we always used event<\/code> and ICommand<\/code> for these scenarios.<\/p>\n

I created the MR.Gestures<\/a> library to close this gap. It provides event<\/code>s and ICommand<\/code>s for gestures on each and every control (all View<\/code>s, Layout<\/code>s and ContentPage<\/code>s) which you can leverage to respond to any touch (and mouse) events.<\/p>\n

Before MR.Gestures, we would write this in XAML to handle a tapped event on a Label<\/code>:<\/p>\n

<Label Text=\"{Binding Text}\">\n    <Label.GestureRecognizers>\n        <TapGestureRecognizer Tapped=\"Label_Tapped\" \/>\n    <\/Label.GestureRecognizers>\n<\/Label><\/code><\/pre>\n
But with MR.Gestures, our XAML now looks like this:<\/p>\n
<mr:Label Text=\"{Binding Text}\" Tapped=\"Label_Tapped\" \/><\/code><\/pre>\n
And, more importantly, there are 17 other touch (and mouse) events which MR.Gestures supports. Each event’s respective EventArgs<\/code> also provide more information than Microsoft’s GestureRecognizers<\/code>.<\/p>\n
Now that the .NET MAUI engineering team has published their release candidate, the time has come to migrate MR.Gestures from Xamarin.Forms to .NET MAUI.<\/p>\n
Starting the Migration<\/h2>\n
We started by creating a new project in Visual Studio using the .NET MAUI Class Library<\/strong> template. The template creates one single project (csproj<\/code>) using multi-targeting to target all platforms.<\/p>\n
This template also includes a Platforms<\/strong> folder with subfolders for every platform, Android<\/code>, iOS<\/code>, MacCatalyst<\/code> and Windows<\/code>. But it does NOT<\/strong> configure the contents of any folder named Android<\/code>, iOS<\/code>, MacCatalyst<\/code> or Windows<\/code> to be compiled only on their respective platform. For this we need to copy a few lines from the official .NET MAUI Multi-Targeting documentation<\/a> to our csproj<\/code> file.<\/p>\n
I simplified them a bit so that this is enough:<\/p>\n
<ItemGroup Condition=\"!$(TargetFramework.StartsWith('net6.0-android'))\">\n    <Compile Remove=\"**\/*.Android.cs\" \/>\n    <Compile Remove=\"**\/Android\/**\/*.cs\" \/>\n<\/ItemGroup>\n\n<ItemGroup Condition=\"!$(TargetFramework.StartsWith('net6.0-ios')) AND !$(TargetFramework.StartsWith('net6.0-maccatalyst'))\">\n    <Compile Remove=\"**\/*.iOS.cs\" \/>\n    <Compile Remove=\"**\/iOS\/**\/*.cs\" \/>\n<\/ItemGroup>\n\n<ItemGroup Condition=\"!$(TargetFramework.Contains('-windows'))\">\n    <Compile Remove=\"**\/*.Windows.cs\" \/>\n    <Compile Remove=\"**\/Windows\/**\/*.cs\" \/>\n<\/ItemGroup>\n\n<ItemGroup>\n    <None Include=\"**\/*\" Exclude=\"$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder);$(Compile)\" \/>\n<\/ItemGroup>\n<\/code><\/pre>\n
The first ItemGroup<\/code> makes sure that any files which end in .Android.cs<\/code> or are in an Android<\/code> folder are only compiled if the current TargetFramework<\/code> is net6.0-android<\/code>.<\/p>\n
The second and third do that for iOS, MacCatalyst and Windows respectively.<\/p>\n
And the last one is a fix for VS so that the solution explorer still shows all the files which are only compiled on some platforms.<\/p>\n
With this configuration completed, let’s start coding!<\/p>\n
Migrating The Controls<\/h2>\n
Migrating my Xamarin.Forms controls to .NET MAUI was easy. I just changed the base class of my types from Xamarin.Forms.*<\/code> to Microsoft.Maui.Controls.*<\/code>, eg Microsoft.Maui.Controls.Label<\/code>. All of the properties and events in those classes stayed the same.<\/p>\n
As you can imagine, this is a lot of code. In Xamarin.Forms, MR.Gestures had 34 classes, each with 18 events, commands and command parameters.<\/p>\n
This is a lot of repetitive code which I don’t want to write by hand. So I use a T4 template<\/a> to generate it. When I first created MR.Gestures in 2014, my template had 110 lines and generated 19,000 lines of code. Over time, with additional events, additional controls, and now with .NET MAUI support, I also added a few controls. Now my T4 template has 188 lines and generates 30,000 lines of C#.<\/p>\n
Migrating To Handlers<\/h2>\n
In Xamarin.Forms, each of my cross-platform controls has a Custom Renderer<\/a> which implements the platform-specific touch handling logic. In the renderers I override OnElementChanged<\/code>, OnElementPropertyChanged<\/code>, Dispose<\/code> and on Android also DispatchTouchEvent<\/code> and DispatchGenericMotionEvent<\/code>.<\/p>\n
In .NET MAUI, Custom Renderers are replaced by Handlers<\/a>. A Handler still has the same purpose as a Custom Renderer – it synchronizes changes between the cross-platform control and the platform-specific implementation – but the Handler does not inherit from the platform view; the methods from the Custom Renderer which I overrode no longer exist. I needed to find the right place where to call into my methods for the native gesture handling.<\/p>\n
The best information I got about how handlers work was in this repo by Javier Su\u00e1rez<\/a>. I also recommend looking at the .NET MAUI source code<\/a> and the .NET MAUI Community Toolkit source code<\/a> for additional examples of Handlers and their implementation.<\/p>\n
I used the same folder structure as .NET MAUI. It has a folder for each control and within that a handler file for every platform.<\/p>\n
\"Handler<\/p>\n
Keep in mind that this is a single-project with multi-targeting. To share code between the cross-platform code and the platform-specific code, each of these files is implementing a partial class<\/code>. The compiled result is a combination of LabelHandler.cs<\/code> and the respective platform file, e.g. LabelHandler.Android.cs<\/code>. Therefore each platform-specific file can inherit from different platform-specific base classes.<\/p>\n
Every handler has a property PlatformView<\/code>, but the type of that property differs per platform.<\/p>\n\n\n\n\n\n\n\n\n
\n        File\n      <\/th>\n\n        Platform\n      <\/th>\n\n        PlatformView\n      <\/th>\n<\/tr>\n<\/thead>\n
\n        LabelHandler.cs\n      <\/td>\n\n        All\n      <\/td>\n\n      <\/td>\n<\/tr>\n
\n        LabelHandler.Android.cs\n      <\/td>\n\n        Android\n      <\/td>\n\n        AndroidX.AppCompat.Widget.AppCompatTextView<\/code>\n      <\/td>\n<\/tr>\n
\n        LabelHandler.iOS.cs\n      <\/td>\n\n        iOS & MacCatalyst\n      <\/td>\n\n        Microsoft.Maui.Platform.MauiLabel<\/code> which is a UILabel<\/code>\n      <\/td>\n<\/tr>\n
\n        LabelHandler.Windows.cs\n      <\/td>\n\n        Windows\n      <\/td>\n\n        Microsoft.UI.Xaml.Controls.TextBlock<\/code>\n      <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
The most important properties in a Handler are PlatformView<\/code>, which is the platform-specific implementation of the view on its respective platform, and VirtualView<\/code>, which is the cross-platform control that we use to compose a .NET MAUI control. In this example, we are using a Label<\/code>.<\/p>\n
In my Handlers, I inherit from the respective .NET MAUI Handler, e.g. LabelHandler<\/code>, which provides the following methods which I can override:<\/p>\n\n\n\n\n\n\n\n
\n        Handler Method\n      <\/th>\n\n        Purpose\n      <\/th>\n<\/tr>\n<\/thead>\n
\n        CreatePlatformView<\/code>\n      <\/td>\n\n        Create the platform-specific view\n      <\/td>\n<\/tr>\n
\n        ConnectHandler<\/code>\n      <\/td>\n\n        Initialize the platform-specific view\n      <\/td>\n<\/tr>\n
\n        DisconnectHandler<\/code>\n      <\/td>\n\n        Clean up + Dispose\n      <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n
Note<\/strong>: As of writing this blog post, a bug exists, “DisconnectHandler is never called”<\/a>, that is scheduled to be fixed in a service release to .NET v6.0.3.<\/p>\n<\/blockquote>\n
As I wrote above, a Renderer IS A platform-specific view which allows me to easily override, for example, the Android-specific methods DispatchTouchEvent<\/code> and DispatchGenericMotionEvent<\/code>.<\/p>\n
Now I need to create a sub-class of the View<\/code> used by the Android handler, override the noted methods, and return a new instance of that class from CreatePlatformView<\/code>. It’s a bit more complicated, but still no big deal.<\/p>\n
Mapper<\/h3>\n
When properties change in the cross-platform control, .NET MAUI uses a PropertyMapper<\/code> to notify the handler. A PropertyMapper<\/code> is basically a Dictionary<\/code> which maps the property name to a method that is invoked each time the property changes. Each respective method is called when that particular property changes.<\/p>\n
LabelHandler.cs<\/h4>\n
public partial class LabelHandler : ILabelHandler\n{\n    public static IPropertyMapper<ILabel, ILabelHandler> Mapper = new PropertyMapper<ILabel, ILabelHandler>(ViewHandler.ViewMapper)\n    {\n        [nameof(ILabel.Text)] = MapText,\n        \/\/ ...\n    };\n\n    public LabelHandler() : base(Mapper) { }\n\n    public LabelHandler(IPropertyMapper? mapper = null) : base(mapper ?? Mapper) { }\n}<\/code><\/pre>\n
LabelHandler<\/code> defines a static Mapper<\/code> which basically states that each time the Text<\/code> property changes, the method MapText<\/code> is invoked.<\/p>\n
Note that the PropertyMapper<\/code> constructor also receives a ViewHandler.ViewMapper<\/code>. This allows PropertyMapper<\/code>s to be chained together. Chaining together PropertyMappers<\/code> means that it will not only react when a property defined in Label<\/code> changes, but also for any property which is defined in its parent’s Mapper<\/code>, e.g. Visibility<\/code>.<\/p>\n
The MapText<\/code> method is defined in the respective platform-specific part of the handler. It has parameters of the generic types used by the Mapper<\/code>:<\/p>\n
LabelHandler.Android.cs<\/h4>\n
public partial class LabelHandler\n{\n    public static void MapText(ILabelHandler handler, ILabel label)\n    {\n        \/\/ handler.PlatformView is a AppCompatTextView\n        handler.PlatformView?.UpdateTextPlainText(label);\n    }\n    \/\/ ...\n}<\/code><\/pre>\n
LabelHandler.iOS.cs<\/h4>\n
public partial class LabelHandler\n{\n    public static void MapText(ILabelHandler handler, ILabel label)\n    {\n        \/\/ handler.PlatformView is a UILabel\n        handler.PlatformView?.UpdateTextPlainText(label);\n    }\n    \/\/ ...\n}<\/code><\/pre>\n
LabelHandler.Windows.cs<\/h4>\n
public partial class LabelHandler\n{\n    public static void MapText(ILabelHandler handler, ILabel label)\n    {\n        \/\/ handler.PlatformView is a TextBlock\n        handler.PlatformView?.UpdateText(label);\n    }\n    \/\/ ...\n}<\/code><\/pre>\n
Now we can translate the methods we used in Xamarin.Forms Custom Renderers to the methods we’ll use in .NET MAUI Handlers to wire-up our custom code<\/p>\n\n\n\n\n\n\n\n\n
\n        Xamarin.Forms Custom Renderer\n      <\/th>\n\n        .NET MAUI Handler\n      <\/th>\n<\/tr>\n<\/thead>\n
\n        OnElementChanged<\/code>\n      <\/td>\n\n        ConnectHandler<\/code>\n      <\/td>\n<\/tr>\n
\n        OnElementPropertyChanged<\/code>\n      <\/td>\n\n        Mapper<\/code>\n      <\/td>\n<\/tr>\n
\n        Dispose<\/code>\n      <\/td>\n\n        DisconnectHandler<\/code>\n      <\/td>\n<\/tr>\n
\n        Dispatch*TouchEvent<\/code>\n      <\/td>\n\n        CreatePlatformView<\/code> and own sub-class\n      <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
From each of these methods, I call into my native platform code to handle the gestures. That code did not use Xamarin.Forms at all and therefore it did not change.<\/p>\n
Registering the Handler<\/h2>\n
Xamarin.Forms used the ExportRendererAttribute<\/code> to link the cross-platform controls to their Renderers. This had a performance problem: each time the app launched, Xamarin.Forms needed to scan every dll<\/code> for said attribute. This was very slow and it got even slower for every reference which you added even if the dependency had nothing to do with Xamarin.Forms at all.<\/p>\n
In other words, every NuGet Package added to your Xamarin.Forms app, regardless of whether it implemented Custom Renderers or not, would slow down your app’s startup time.<\/p>\n
In .NET MAUI, we register handlers in the startup code of our app in MauiProgram.CreateMauiApp()<\/code>, specifically in the ConfigureMauiHandlers<\/code> extension method:<\/p>\n
public static MauiApp CreateMauiApp()\n{\n    var builder = MauiApp.CreateBuilder();\n    builder\n        .UseMauiApp<App>()\n        .ConfigureMauiHandlers(handlers =>\n        {\n            handlers.AddHandler<MR.Gestures.Label, LabelHandler>();\n        });\n\n    return builder.Build();\n}<\/code><\/pre>\n
In MR.Gestures, I wrote an extension method to register all the MR.Gestures handlers at once, so all you need to do is this:<\/p>\n
var builder = MauiApp.CreateBuilder();\nbuilder\n    .UseMauiApp<App>()\n    .ConfigureMRGestures(licenseKey);\n\nreturn builder.Build();<\/code><\/pre>\n
\n
Note:<\/strong> The licenseKey<\/code> is ignored for now. It will be used when MAUI gets to GA.<\/p>\n<\/blockquote>\n
Supporting Additional Platforms<\/h2>\n
.NET MAUI adds two new platforms: MacCatalyst and WinUI3.<\/p>\n
In theory, MacCatalyst should run the same iOS code. So in theory it should “just work”. But unfortunately I couldn’t test this yet<\/a>.<\/p>\n
For WinUI3 I took my UWP code and almost exclusively just changed the namespaces from Windows.UI<\/code> to Microsoft.UI<\/code>.<\/p>\n
There was just one pitfall because I used Windows.UI.Xaml.Window.Current.CoreWindow<\/code> on UWP which returns a Windows.UI.Core.CoreWindow<\/code>. In WinUI3 Microsoft.UI.Xaml.Window.Current.CoreWindow<\/code> still exists, but it has the UWP type Windows.UI.Core.CoreWindow<\/code>. I had to replace CoreWindow<\/code> with something else to find the root window of my view.<\/p>\n
Conclusion<\/h2>\n
Altogether I was very pleased with the migration procedure. I just had to learn how Handlers work in-detail and how to wire-up all my code. In total, it took me two weeks from starting to look into how the .NET MAUI source-code works until I published the first prerelease of MR.Gestures for .NET MAUI.<\/p>\n","protected":false},"excerpt":{"rendered":"
In this guest blog post, Michael Rumpler shares how he ported his popular Xamarin.Forms library, MR.Gestures, to support .NET MAUI<\/p>\n","protected":false},"author":91724,"featured_media":39167,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[9211,1],"tags":[8867,589,9216,9217],"class_list":["post-49199","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-net-maui","category-xamarin","tag-net-maui","tag-community","tag-library","tag-migration"],"acf":[],"blog_post_summary":"
In this guest blog post, Michael Rumpler shares how he ported his popular Xamarin.Forms library, MR.Gestures, to support .NET MAUI<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/49199","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/users\/91724"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/comments?post=49199"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/49199\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media\/39167"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media?parent=49199"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/categories?post=49199"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/tags?post=49199"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}