{"id":48886,"date":"2021-08-31T11:00:05","date_gmt":"2021-08-31T18:00:05","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/xamarin\/?p=48886"},"modified":"2021-08-31T09:58:47","modified_gmt":"2021-08-31T16:58:47","slug":"introducing-net-maui-compatibility-for-the-xamarin-community-toolkit","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/xamarin\/introducing-net-maui-compatibility-for-the-xamarin-community-toolkit\/","title":{"rendered":"Introducing .NET MAUI Compatibility for the Xamarin Community Toolkit"},"content":{"rendered":"<blockquote>\n<p><strong>Note:<\/strong> This is a follow to last month&#8217;s announcement: <a href=\"https:\/\/devblogs.microsoft.com\/xamarin\/the-future-of-xamarin-community-toolkit\/?WT.mc_id=mobile-39515-bramin\">The Future of Xamarin Community Toolkit<\/a><\/p>\n<\/blockquote>\n<p>The Xamarin Community Toolkit team is excited to announce two new .NET MAUI-compatible versions of the toolkit:<\/p>\n<ul>\n<li><a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit.MauiCompat\/\"><code>Xamarin.CommunityToolkit.MauiCompat<\/code><\/a><\/li>\n<li><a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit.Markup.MauiCompat\/\"><code>Xamarin.CommunityToolkit.Markup.MauiCompat<\/code><\/a><\/li>\n<\/ul>\n<p>These <code>MauiCompat<\/code> libraries align to latest release of <code>Xamarin.CommunityToolkit<\/code>; the main difference being that these are for your <a href=\"https:\/\/docs.microsoft.com\/dotnet\/maui\/what-is-maui?WT.mc_id=mobile-39515-bramin\"><code>.NET MAUI<\/code><\/a> apps, whereas <code>Xamarin.CommunityToolkit<\/code> is for your <a href=\"https:\/\/dotnet.microsoft.com\/apps\/xamarin\/xamarin-forms?WT.mc_id=mobile-39515-bramin\"><code>Xamrain.Forms<\/code><\/a> apps.<\/p>\n<p>Today&#8217;s <code>MauiCompat<\/code> release includes support for iOS and Android. Future <code>MauiCompat<\/code> releases will include support for iOS, Android, macOS and UWP.<\/p>\n<table>\n<thead>\n<tr>\n<th>\n      <\/th>\n<th>\n        <strong>Xamarin.Community.Toolkit<\/strong>\n      <\/th>\n<th>\n        <strong>Xamarin.CommunityToolkit.MauiCompat<\/strong>\n      <\/th>\n<th>\n        <strong>Xamarin.Community.Toolkit.Markup<\/strong>\n      <\/th>\n<th>\n        <strong>Xamarin.CommunityToolkit.Markup.MauiCompat<\/strong>\n      <\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>\n        <strong>Dependency<\/strong>\n      <\/td>\n<td>\n        Xamarin.Forms\n      <\/td>\n<td>\n        .NET MAUI\n      <\/td>\n<td>\n        Xamarin.Forms\n      <\/td>\n<td>\n        .NET MAUI\n      <\/td>\n<\/tr>\n<tr>\n<td>\n        <strong>Native Implementation<\/strong>\n      <\/td>\n<td>\n        <a href=\"https:\/\/docs.microsoft.com\/xamarin\/xamarin-forms\/app-fundamentals\/custom-renderer\/?WT.mc_id=mobile-39515-bramin\">Custom Renderer<\/a>\n      <\/td>\n<td>\n        <a href=\"https:\/\/docs.microsoft.com\/xamarin\/xamarin-forms\/app-fundamentals\/custom-renderer\/?WT.mc_id=mobile-39515-bramin\">Custom Renderer<\/a>\n      <\/td>\n<td>\n        <a href=\"https:\/\/docs.microsoft.com\/xamarin\/xamarin-forms\/app-fundamentals\/custom-renderer\/?WT.mc_id=mobile-39515-bramin\">Custom Renderer<\/a>\n      <\/td>\n<td>\n        <a href=\"https:\/\/docs.microsoft.com\/xamarin\/xamarin-forms\/app-fundamentals\/custom-renderer\/?WT.mc_id=mobile-39515-bramin\">Custom Renderer<\/a>\n      <\/td>\n<\/tr>\n<tr>\n<td>\n        <strong>Target<\/strong>\n      <\/td>\n<td>\n        .NET Standard 1.0 <em>(Same as Xamarin.Forms)<\/em>\n      <\/td>\n<td>\n        .NET 6.0 <em>(Same as .NET MAUI)<\/em>\n      <\/td>\n<td>\n        .NET Standard 1.0 <em>(Same as Xamarin.Forms)<\/em>\n      <\/td>\n<td>\n        .NET 6.0 <em>(Same as .NET MAUI)<\/em>\n      <\/td>\n<\/tr>\n<tr>\n<td>\n        <strong>Platforms<\/strong>\n      <\/td>\n<td>\n        iOS, Android, GTK#, Tizen, UWP, WPF <em>(Same as Xamarin.Forms)<\/em>\n      <\/td>\n<td>\n        iOS, Android, Windows (in progress), macOS (in progress) <em>(Same as .NET MAUI)<\/em>\n      <\/td>\n<td>\n        iOS, Android, GTK#, Tizen, UWP, WPF <em>(Same as Xamarin.Forms)<\/em>\n      <\/td>\n<td>\n        iOS, Android, Windows (in progress), macOS (in progress) <em>(Same as .NET MAUI)<\/em>\n      <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Which Apps Should Use <code>MauiCompat<\/code>?<\/h2>\n<h3>\u2705 Existing Xamarin.Forms apps migrating to .NET MAUI<\/h3>\n<p>The <code>MauiCompat<\/code> libraries are created as a helpful step in your migration from Xamarin.Forms to .NET MAUI. These libraries ensure that you can access all of the features of <code>Xamarin.CommunityToolkit<\/code> in your .NET MAUI apps without breaking changes, helping to make your migration to .NET MAUI easier.<\/p>\n<p>We recommend eventually replacing <code>Xamarin.CommunityToolkit.MauiCompat<\/code> with the <a href=\"https:\/\/www.nuget.org\/packages\/CommunityToolkit.Maui\">new .NET MAUI Toolkit<\/a>, <code>CommunityToolkit.Maui<\/code>, to take advange of new features and optimizations (see comarison chart below).<\/p>\n<h3>\u274c Brand new .NET MAUI apps<\/h3>\n<p>For new (aka greenfield) .NET MAUI apps, use the new <a href=\"https:\/\/www.nuget.org\/packages\/CommunityToolkit.Maui\/\">.NET MAUI Community Toolkit<\/a>, which is fully optimized for .NET MAUI, instead of <code>Xamarin.CommunityToolkit.MauiCompat<\/code>.<\/p>\n<h3><a href=\"https:\/\/www.nuget.org\/packages\/CommunityToolkit.Maui\/\"><code>Xamarin.CommunityToolkit.MauiCompat<\/code><\/a> vs <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit\/\"><code>CommunityToolkit.Maui<\/code><\/a><\/h3>\n<table>\n<thead>\n<tr>\n<th>\n      <\/th>\n<th>\n        <a href=\"https:\/\/www.nuget.org\/packages\/CommunityToolkit.Maui\/\"><strong>Xamarin.CommunityToolkit.MauiCompat<\/strong><\/a>\n      <\/th>\n<th>\n        <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit\/\"><strong>CommunityToolkit.Maui<\/strong><\/a>\n      <\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>\n        <strong>Future Updates<\/strong>\n      <\/td>\n<td>\n        Only Bug Fixes\n      <\/td>\n<td>\n        New Features + Bug Fixes\n      <\/td>\n<\/tr>\n<tr>\n<td>\n        <strong>Native Implementation<\/strong>\n      <\/td>\n<td>\n        <a href=\"https:\/\/docs.microsoft.com\/xamarin\/xamarin-forms\/app-fundamentals\/custom-renderer\/?WT.mc_id=mobile-39515-bramin\">Custom Renderer<\/a>\n      <\/td>\n<td>\n        <a href=\"https:\/\/docs.microsoft.com\/dotnet\/maui\/user-interface\/handlers\/customize?WT.mc_id=mobile-39515-bramin\">Handlers<\/a>\n      <\/td>\n<\/tr>\n<tr>\n<td>\n        Uses <code>Microsoft.Maui.Controls.Compatibility<\/code>?\n      <\/td>\n<td>\n        Yes\n      <\/td>\n<td>\n        No\n      <\/td>\n<\/tr>\n<tr>\n<td>\n        <strong>Road Map<\/strong>\n      <\/td>\n<td>\n        Will be deprecated <a href=\"https:\/\/github.com\/xamarin\/Xamarin.Forms\/wiki\/Feature-Roadmap\">alongside Xamarin.Forms November 2022<\/a>\n      <\/td>\n<td>\n        Periodic Updates + Maintenance Releases Alongside .NET MAUI (I.e. No planned deprecation schedule)\n      <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Getting Started With MauiCompat<\/h2>\n<p>Both <code>MauiCompat<\/code> libraries are available as a NuGet package that can be added to any .NET 6 project targeting <code>net6.0-ios<\/code> and <code>net6.0-android<\/code>:<\/p>\n<table>\n<thead>\n<tr>\n<th><\/th>\n<th><strong>Xamarin.CommunityToolkit.MauiCompat<\/strong><\/th>\n<th><strong>Xamarin.CommunityToolkit.Markup.MauiCompat<\/strong><\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>NuGet Package<\/td>\n<td>https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit.MauiCompat\/<\/td>\n<td>https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit.Markup.MauiCompat\/<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<ol>\n<li>\n<p>Open existing project in Visual Studio<\/p>\n<\/li>\n<li>\n<p>In the <a href=\"https:\/\/docs.microsoft.com\/nuget\/consume-packages\/install-use-packages-powershell#opening-the-console-and-console-controls?WT.mc_id=mobile-39515-bramin\">Visual Studio Package Manager Console<\/a>, enter the following command:<\/p>\n<pre><code class=\"language-bash\">Install-Package Xamarin.CommunityToolkit.MauiCompat<\/code><\/pre>\n<p>or<\/p>\n<pre><code class=\"language-bash\">Install-Package Xamarin.CommunityToolkit.Markup.MauiCompat<\/code><\/pre>\n<\/li>\n<li>\n<p>To add the namespace to the toolkit:<\/p>\n<ul>\n<li>\n<p>In your C# page, add:<\/p>\n<pre><code class=\"language-csharp\">using Xamarin.CommunityToolkit;<\/code><\/pre>\n<p>or<\/p>\n<pre><code class=\"language-csharp\">using Xamarin.CommunityToolkit.Markup;<\/code><\/pre>\n<\/li>\n<li>\n<p>In your XAML page, add the namespace attribute:<\/p>\n<pre><code class=\"language-xaml\">xmlns:xct=\"http:\/\/xamarin.com\/schemas\/2020\/toolkit\"<\/code><\/pre>\n<\/li>\n<\/ul>\n<\/li>\n<li>\n<p>Register the renderer(s) you want to use in the <code>Startup.cs<\/code> file. You can either only register the renderer(s) you actually need, or register all the renderers that are inside of the Xamarin Community Toolkit. Have a look at the code snippet below how to do both.<\/p>\n<\/li>\n<\/ol>\n<pre><code class=\"language-csharp\">public void Configure(IAppHostBuilder appBuilder)\n{\n    appBuilder\n        .UseMauiApp&lt;App&gt;()\n        .ConfigureMauiHandlers(handlers =&gt;\n        {\n            \/\/ Register ALL handlers in the Xamarin Community Toolkit assembly\n            handlers.AddCompatibilityRenderers(typeof(Xamarin.CommunityToolkit.UI.Views.MediaElementRenderer).Assembly)\n\n            \/\/ Register just one handler for the control you need\n            handlers.AddCompatibilityRenderer(typeof(Xamarin.CommunityToolkit.UI.Views.MediaElement), typeof(Xamarin.CommunityToolkit.UI.Views.MediaElementRenderer));\n        });\n}<\/code><\/pre>\n<ol start=\"5\">\n<li>\n    Check out the rest of the documentation to learn more about implementing specific features: <a href=\"https:\/\/docs.microsoft.com\/xamarin\/community-toolkit\/?WT.mc_id=mobile-39515-bramin\">https:\/\/docs.microsoft.com\/xamarin\/community-toolkit\/<\/a>\n  <\/li>\n<\/ol>\n<h2>Good to Know<\/h2>\n<p>We have released this package under the alpha tag. Because this <code>MauiCompat<\/code> package is being built alongside the preview of .NET MAUI, there are still some things that need to be etched out on both sides. We&#8217;re releasing this now so that we can get your feedback early on and make sure the <code>MauiCompat<\/code> Toolkit is ready to use by the time .NET MAUI is released.<\/p>\n<h3>Non-Renderer Controls<\/h3>\n<p>There are some controls that don&#8217;t require a (separate) renderer, i.e. <code>Shield<\/code>. Those controls are not supported at the moment. We have a good idea how to add support for this, it just hasn&#8217;t been realized yet. If you do try to use a &#8220;non-renderer&#8221; control, you will see an error messages which states that a handler hasn&#8217;t been found for type X.<\/p>\n<p>However, this error will also come up when you didn&#8217;t register the renderer for the control you&#8217;re trying to use (see above), so make sure you have that in place.<\/p>\n<h3><code>Markup<\/code> Should Just Work<\/h3>\n<p>The <code>Markup<\/code> package should just work as it doesn&#8217;t rely on renderers. We did make it compatible with all the current .NET MAUI changes and namespaces so you can continue enjoying the markup extensions as before.<\/p>\n<h3>Other Known Issues &amp; Reporting Issues<\/h3>\n<p>In .NET MAUI there has been a change in the <code>Color<\/code> object. Therefore there might be some issues in that area, although that might not be apparent to you on the outside. Whenever you run into a <code>NullReferenceException<\/code> you might want to try setting all the color properties of a control to an explicit value and see if that resolves the issue. If not, please let us know what you&#8217;re seeing so we can have a look.<\/p>\n<p>If you find any issues, please report them on the regular <a href=\"https:\/\/github.com\/xamarin\/XamarinCommunityToolkit\"><code>Xamarin.CommunityToolkit repository<\/code><\/a>, but make sure that you mention that this is about the <code>MauiCompat<\/code> package just so we know where to look for issues.<\/p>\n<h2>Release Schedule<\/h2>\n<p>Going forward, we will release a <code>MauiCompat<\/code> NuGet package alongside each new release of <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit\"><code>Xamarin.CommunityToolkit<\/code><\/a> and <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit.Markup\"><code>Xamarin.CommunityToolkit.Markup<\/code><\/a>.<\/p>\n<p>For example, the latest release of <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit\">Xamarin.CommunityToolkit<\/a> is <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit\/1.3.0-pre2\">v1.3.0-pre2<\/a>, and thus today&#8217;s release of <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit.MauiCompat\">Xamarin.CommunityToolkit.MauiCompat<\/a> is also <a href=\"https:\/\/www.nuget.org\/packages\/Xamarin.CommunityToolkit.MauiCompat\/1.3.0-alpha2\">v1.3.0-alpha2<\/a>. The only minor difference here is the <code>pre<\/code> and <code>alpha<\/code> tag for now. This should be more in line in future releases.<\/p>\n<p>To keep the <code>MauiCompat<\/code> releases packages aligned with <code>Xamarin.CommunityToolkit<\/code>, we follow these steps:<\/p>\n<ol>\n<li>Branch from the latest <a href=\"https:\/\/github.com\/xamarin\/XamarinCommunityToolkit\/releases\/tag\/1.3.0-pre2\">Xamarin.CommunityToolkit Release<\/a> (aka its <a href=\"https:\/\/git-scm.com\/book\/en\/v2\/Git-Basics-Tagging\">Git Tag<\/a>) \n<ul>\n<li>This ensures the logic in the <code>MauiCompat<\/code> libraries exactly matches the logic in the <code>Xamarin.CommunityToolkit<\/code> release<\/li>\n<\/ul>\n<\/li>\n<li>Replace the Xamarin.Forms dependency with the .NET MAUI dependency \n<ul>\n<li><code>&lt;PackageReference Include=\"Xamarin.Forms\" \/&gt;<\/code> -> <code>&lt;UseMaui&gt;true&lt;\/UseMaui&gt;<\/code><\/li>\n<\/ul>\n<\/li>\n<li>Update to <a href=\"https:\/\/dotnet.microsoft.com\/download\/dotnet\/6.0?WT.mc_id=mobile-39515-bramin\">.NET 6<\/a> \n<ul>\n<li><code>&lt;TargetFramework&gt;netstandard2.1&lt;\/TargetFramework&gt;<\/code> -> <code>&lt;TargetFrameworks&gt;net6.0-ios;net6.0-android&lt;\/TargetFramework&gt;<\/code><\/li>\n<\/ul>\n<\/li>\n<li>Update the namespaces \n<ul>\n<li><code>using Xamarin.Forms<\/code> -> <code>using Microsoft.Maui<\/code><\/li>\n<\/ul>\n<\/li>\n<\/ol>\n<blockquote>\n<p>(There are also some references to <code>Xamarin.Forms.*<\/code> in specific files that we indiviually update to <code>Mirosoft.Maui.*<\/code>)<\/p>\n<\/blockquote>\n<p>We&#8217;ve documented the steps we follow to convert <code>Xamarin.CommunityToolkit<\/code> to <code>Xamarin.CommunityToolkit.MauiCompat<\/code>, and you can find them here: https:\/\/github.com\/xamarin\/XamarinCommunityToolkit\/blob\/main\/MauiCompatSteps.md<\/p>\n<h2>Summary<\/h2>\n<p>When migrating your existing Xamarin.Forms app to .NET MAUI, levarage these <code>MauiCompat<\/code> libraries. They contain the same logic as their <code>Xamarin.CommunityToolkit<\/code> counterpart, targeting .NET MAUI instead of Xamarin.Forms.<\/p>\n<p>Eventually, you will want to migrate to the <a href=\"https:\/\/www.nuget.org\/packages\/CommunityToolkit.Maui\/\">.NET MAUI Toolkit<\/a> to take advantage of new features and optimizations, as we will sunset the <code>MauiCompat<\/code> libraries alongside <a href=\"https:\/\/github.com\/xamarin\/Xamarin.Forms\/wiki\/Feature-Roadmap\">Xamarin.Forms in November 2022<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Announcing the first preview release of Xamarin.CommunityToolkit.MauiCompat<\/p>\n","protected":false},"author":568,"featured_media":48887,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[9211,313,5216,303,1,367,7745],"tags":[589,9207,9210,8704,9209,5481,27,9208],"class_list":["post-48886","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-net-maui","category-android","category-announcements","category-ios","category-xamarin","category-xamarin-forms","category-xaml","tag-community","tag-communitytoolkit","tag-compatibility","tag-maui","tag-mauicompat","tag-toolkit","tag-xamarin","tag-xamarincommunitytoolkit"],"acf":[],"blog_post_summary":"<p>Announcing the first preview release of Xamarin.CommunityToolkit.MauiCompat<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/48886","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\/568"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/comments?post=48886"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/48886\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media\/48887"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media?parent=48886"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/categories?post=48886"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/tags?post=48886"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}