将Xamarin迁移至MAUI：自定义控件HandlerNotFoundException问题解决

我有一个名为CustomView的自定义控件，包含若干可绑定属性，代码如下：

namespace App.Maui.Controls
{
   public class CustomView : Layout<Layout>
}

在XAML中引用该控件的代码如下：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:controls="using:App.Maui.Controls">
  <controls:CustomView IsOpen="{Binding ViewModel.IsOpen}">

将Xamarin应用迁移至MAUI后，代码编译正常，但显示控件时出现如下错误：

Microsoft.Maui.Platform.HandlerNotFoundException: 'Handler not found for view App.Maui.Controls.CustomControl.'

该错误看似明确，但我未找到解决方案——查阅大量指南均未提及Handler，且基础控件似乎无需平台特定实现。请问如何为此类基础控件定义Handler？

在MAUI中，自定义控件即便继承自Layout<T>这类基础布局控件，也需要明确注册对应的Handler，以下是两种实用的解决方法：

方法1：复用内置布局的Handler #

直接在MauiProgram.cs中为CustomView注册复用MAUI内置的LayoutHandler即可，因为你的控件本质属于布局类，无需额外编写平台特定代码：

builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler(typeof(CustomView), typeof(Microsoft.Maui.Handlers.LayoutHandler));
});

方法2：创建自定义Handler（用于后续扩展平台功能） #

如果之后需要为控件添加平台专属逻辑，可以自定义Handler，步骤如下：

1. 在共享项目中定义Handler #

using Microsoft.Maui.Handlers;

namespace App.Maui.Controls
{
    public class CustomViewHandler : LayoutHandler
    {
        protected override LayoutView CreatePlatformView()
        {
            // 若需自定义平台视图创建逻辑，在此修改，默认复用基类实现即可
            return base.CreatePlatformView();
        }

        // 如需处理自定义属性变化，重写Map方法
        public static void MapIsOpen(CustomViewHandler handler, CustomView view)
        {
            if (handler.PlatformView is LayoutView platformView)
            {
                // 根据view.IsOpen的值执行对应平台逻辑
            }
        }
    }
}

2. 在MauiProgram中注册自定义Handler #

builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler(typeof(CustomView), typeof(CustomViewHandler));
});

额外提示 #

• 错误信息中提到的是CustomControl，但你的控件类名是CustomView，请检查是否存在命名拼写不一致的情况，这也可能导致该错误。
• MAUI的控件模型和Xamarin.Forms不同，所有可视化控件都必须有对应的Handler关联，哪怕是继承自基础控件的自定义类也不例外。

内容的提问来源于stack exchange，提问作者Aventil