嵌套控件子视图添加Effects触发NullReferenceException问题

异常现象 #

• 单视图中执行Effects.Add(Effect)添加自定义Effect无异常
• 嵌套控件的子视图中执行相同操作时触发NullReferenceException

嵌套布局示例：

<!-- 嵌套控件结构 -->
<ContentPage.Content>
    <local:SampleView>
        <local:SampleView.Content>
            <local:SampleView2>
                <local:ContextNullException />
            </local:SampleView2>
        </local:SampleView.Content>
    </local:SampleView>
</ContentPage.Content>

异常堆栈跟踪：

[mono-rt] [ERROR] FATAL UNHANDLED EXCEPTION: System.NullReferenceException: Object reference not set to an instance of an object.
[mono-rt]    at Microsoft.Maui.Controls.Element.get_EffectsFactory() in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\Element\Element.Impl.cs:line 14
[mono-rt]    at Microsoft.Maui.Controls.Element.Microsoft.Maui.Controls.IEffectControlProvider.RegisterEffect(Effect effect) in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\Element\Element.Impl.cs:line 88
[mono-rt]    at Microsoft.Maui.Controls.Element.AttachEffect(Effect effect) in D:\a\_work\1\s\src\Controls\src\Core\Element.cs:line 547
[mono-rt]    at Microsoft.Maui.Controls.Element.set_EffectControlProvider(IEffectControlProvider value) in D:\a\_work\1\s\src\Controls\src\Core\Element.cs:line 250
[mono-rt]    at Microsoft.Maui.Controls.Element.OnHandlerChangedCore() in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\Element\Element.Impl.cs:line 35
[mono-rt]    at Microsoft.Maui.Controls.VisualElement.OnHandlerChangedCore() in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\VisualElement\VisualElement.Impl.cs:line 40
[mono-rt]    at Microsoft.Maui.Controls.View.OnHandlerChangedCore() in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\View\View.Impl.cs:line 16
[mono-rt]    at Microsoft.Maui.Controls.Element.SetHandler(IElementHandler newHandler) in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\Element\Element.Impl.cs:line 71
[mono-rt]    at Microsoft.Maui.Controls.Element.set_Handler(IElementHandler value) in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\Element\Element.Impl.cs:line 19
[mono-rt]    at Microsoft.Maui.Controls.VisualElement.set_Handler(IViewHandler value) in D:\a\_work\1\s\src\Controls\src\Core\HandlerImpl\VisualElement\VisualElement.Impl.cs:line 35
[mono-rt]    at Microsoft.Maui.Controls.Compatibility.RendererToHandlerShim.SetupRenderer(IVisualElementRenderer visualElementRenderer) in D:\a\_work\1\s\src\Compatibility\Core\src\RendererToHandlerShim.cs:line 100
[mono-rt]    at Microsoft.Maui.Controls.Compatibility.RendererToHandlerShim..ctor(IVisualElementRenderer visualElementRenderer) in D:\a\_work\1\s\src\Compatibility\Core\src\RendererToHandlerShim.cs:line 91
[mono-rt]    at Microsoft.Maui.Controls.Compatibility.Platform.Android.Platform.<>c.<.cctor>b__66_0(BindableObject bindable, Object oldvalue, Object newvalue) in D:\a\_work\1\s\src\Compatibility\Core\src\Android\AppCompat\Platform.cs:line 44
[mono-rt]    at Microsoft.Maui.Controls.BindableObject.SetValueActual(BindableProperty property, BindablePropertyContext context, Object value, Boolean currentlyApplying, SetValueFlags attributes, Boolean silent) in D:\a\_work\1\s\src\Controls\src\Core\BindableObject.cs:line 535
[mono-rt]    at Microsoft.Maui.Controls.BindableObject.SetValueCore(BindableProperty property, Object value, SetValueFlags attributes, SetValuePrivateFlags privateAttributes) in D:\a\_work\1\s\src\Controls\src\Core\BindableObject.cs:line 469
[mono-rt]    at Microsoft.Maui.Controls.BindableObject.SetValue(BindableProperty property, Object value, Boolean fromStyle, Boolean checkAccess) in D:\a\_work\1\s\src\Controls\src\Core\BindableObject.cs:line 391
[mono-rt]    at Microsoft.Maui.Controls.BindableObject.SetValue(BindableProperty property, Object value) in D:\a\_work\1\s\src\Controls\src\Core\BindableObject.cs:line 365
[mono-rt]    at Microsoft.Maui.Controls.Compatibility.Platform.Android.Platform.SetRenderer(VisualElement bindable, IVisualElementRenderer value) in D:\a\_work\1\s\src\Compatibility\Core\src\Android\AppCompat\Platform.cs:line 408
[mono-rt]    at Microsoft.Maui.Controls.Compatibility.Platform.Android.VisualElementPackager.AddChild(VisualElement view, IVisualElementRenderer oldRenderer, RendererPool pool, Boolean sameChildren) in D:\a\_work\1\s\src\Compatibility\Core\src\Android\VisualElementPackager.cs:line 153
[mono-rt]    at Microsoft.Maui.Controls.Compatibility.Platform.Android.VisualElementPackager.SetElement(VisualElement oldElement, VisualElement newElement) in D:\a\_work\1\s\src\Compatibility\Core\src\Android\VisualElementPackager.cs:line 347
[mono-rt]    at Microsoft.Maui.Controls.Compatibility.Platform.Android.VisualElementPackager.Load() in D:\a\_work\1\s\src\Compatibility\Core\src\Android\VisualEleme

问题根源分析 #

1. Effect添加时机过早：触发异常的视图在构造函数中直接添加Effect，此时控件尚未完成初始化，EffectsFactory等核心对象未被创建，嵌套布局场景下父控件的Children操作会进一步打乱生命周期流程，导致空引用。
2. 自定义布局属性实现不规范：SampleView的Content属性直接操作Children集合，未使用MAUI的BindableProperty机制，框架无法正确处理子控件的生命周期事件。

解决方案 #

1. 延迟Effect添加到控件生命周期的合适阶段 #

将Effect的添加从构造函数移到OnHandlerChanged方法，确保控件初始化完成后再操作Effects：

public class NullReferenceException : Microsoft.Maui.Controls.Compatibility.Layout<View>
{
    public NullReferenceException()
    {
        // 移除构造函数中的Effect添加代码
    }

    protected override void OnHandlerChanged()
    {
        base.OnHandlerChanged();
        // 确保Handler已初始化且未添加过该Effect
        if (Handler != null && !Effects.Any(e => e is TapGestureEffect))
        {
            var tapGestureEffect = new TapGestureEffect();
            Effects.Add(tapGestureEffect);
        }
    }

    protected override void LayoutChildren(double x, double y, double width, double height)
    {
    }
}

2. 优化自定义布局的Content属性实现 #

使用BindableProperty替代普通属性，让MAUI框架正确处理控件生命周期：

public class SampleView : Microsoft.Maui.Controls.Compatibility.Layout<View>
{
    public static readonly BindableProperty ContentProperty =
        BindableProperty.Create(nameof(Content), typeof(View), typeof(SampleView), propertyChanged: OnContentChanged);

    public View Content
    {
        get => (View)GetValue(ContentProperty);
        set => SetValue(ContentProperty, value);
    }

    private static void OnContentChanged(BindableObject bindable, object oldValue, object newValue)
    {
        var view = (SampleView)bindable;
        if (oldValue is View oldContent)
        {
            view.Children.Remove(oldContent);
        }
        if (newValue is View newContent)
        {
            view.Children.Insert(0, newContent);
        }
    }

    protected override void LayoutChildren(double x, double y, double width, double height)
    {
    }
}

3. 完善Effect注册代码 #

确保CreateMauiApp中正确注册Effect并初始化MAUI应用：

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .ConfigureEffects(effects =>
        {
            effects.Add<TapGestureEffect, TouchPlatformEffect>();
        })
        .UseMauiApp<App>();
    return builder.Build();
}

验证步骤 #

1. 替换上述代码后重新编译Android项目
2. 检查嵌套控件场景下是否不再触发NullReferenceException
3. 确认自定义Effect功能正常生效

内容的提问来源于stack exchange，提问作者k.kk