[iOS] Fix modal page crash during app snapshot creation

[Copilot]

• Analyze the crash issue and understand the stack trace
• Review the suggested fix from the issue comment
• Implement null check in ControlsModalWrapper.ViewDidLayoutSubviews()
• Verify the fix matches the pattern used elsewhere in the same file (Dispose method)
• Test build to ensure no compilation errors
• Format code and verify changes
• Review existing tests and verify fix doesn't break them
• Add explanatory comment for the defensive check

Summary

This PR fixes a crash that occurs when iOS creates app snapshots while modal pages are displayed (e.g., when users switch between apps). The crash happens because ViewDidLayoutSubviews() was calling PlatformArrange() without checking if the handler's VirtualView is still valid.

Technical Details

Error Stack Trace:

System.InvalidOperationException: Unable to convert Microsoft.Maui.Handlers.PageHandler to UIKit.UIView
  at UIView ElementHandlerExtensions.ToPlatform(IElementHandler elementHandler)()
  at void ViewHandlerExtensions.PlatformArrangeHandler(IViewHandler viewHandler, Rect rect)()
  at void ViewHandler<IContentView, ContentView>.PlatformArrange(Rect rect)()
  at void ControlsModalWrapper.ViewDidLayoutSubviews()()

Root Cause: During iOS snapshot creation (when app goes to background), the ViewDidLayoutSubviews() method is called, which tries to call PlatformArrange() on a handler whose VirtualView has already been disposed or is null.

Solution Implemented

Added a defensive null check in ControlsModalWrapper.ViewDidLayoutSubviews() with explanatory comments to ensure _modal?.VirtualView is Page before calling PlatformArrange(). This matches the defensive pattern already used in:

• The Dispose() method (line 162)
• The DidDismiss() method (line 66)

Changes Made

• File: src/Controls/src/Core/Platform/iOS/ControlsModalWrapper.cs
• Lines changed: 139-144 (added explanatory comment and null check guard)

This is a minimal, surgical change that adds defensive programming without altering any existing behavior when VirtualView is valid.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[iOS] Modal-Page crashes</issue_title>
<issue_description>### Description

We're seeing a lot of crashes in Sentry with this stack trace.

System.InvalidOperationException: Unable to convert Microsoft.Maui.Handlers.PageHandler to UIKit.UIView
  at UIView ElementHandlerExtensions.ToPlatform(IElementHandler elementHandler)()
  at void ViewHandlerExtensions.PlatformArrangeHandler(IViewHandler viewHandler, Rect rect)()
  at void ViewHandler<IContentView, ContentView>.PlatformArrange(Rect rect)()
  at void ControlsModalWrapper.ViewDidLayoutSubviews()()
  at void __Registrar_Callbacks__.callback_69_Microsoft_Maui_Controls_Platform_ControlsModalWrapper_ViewDidLayoutSubviews(IntPtr pobj, IntPtr sel, IntPtr* exception_gchandle)()

Unfortunately, we can't reproduce the issue ourselves, so we can't provide a way to reproduce it.
However, the stack trace strongly suggests that it's related to pop-ups (displayed using INavigation.PushModalAsync).
Users report that it occurs when they switch back and forth between our app and OneDrive.

My hope is that the Maui team can make some adjustments to the code in the relevant parts of the stack, adding null checks to prevent crashes, even though we can't currently reproduce the issue. It's likely that the VirtualView of the PageHandler is simply null.

Steps to Reproduce

Unfortunately, we can't reproduce the issue

Link to public reproduction project repository

No response

Version with bug

9.0.110 SR11

Is this a regression from previous behavior?

No, this is something new

Last version that worked well

Unknown/Other

Affected platforms

iOS

Affected platform versions

No response

Did you find any workaround?

No response

Relevant log output

```</issue_description>

<agent_instructions>Can you see if the suggestion in https://github.com/dotnet/maui/issues/31829#issuecomment-3355211864 could make sense in this context? If so, apply it.</agent_instructions>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@jfversluis</author><body>
Without any reproduction or at the very least relevant code it will be near impossible to say something useful about this. Please remember that we know nothing about your project and do not have any code or even know what it does functionally. Try to investigate a bit more and provide any details you might uncover, else it is very unlikely for this to be solved.</body></comment_new>
</comments>

Fixes #31829

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[jfversluis]

/azp run

[Copilot]

Pull Request Overview

Fixes a crash that occurs during iOS app snapshot creation when modal pages are displayed. The crash happens when ViewDidLayoutSubviews() attempts to call PlatformArrange() on a handler whose VirtualView has been disposed or is null.

• Added defensive null check in ControlsModalWrapper.ViewDidLayoutSubviews() method
• Follows existing defensive programming pattern used elsewhere in the same file
• Prevents InvalidOperationException during app state transitions

[jfversluis]

Not sure it will help, but also it doesn't hurt?

[azure-pipelines]

Azure Pipelines successfully started running 3 pipeline(s).

[jfversluis]

Failing tests are unrelated

[jsuarezruiz]

@copilot Review

[PureWeen]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 3 pipeline(s).

[azure-pipelines]

Azure Pipelines successfully started running 3 pipeline(s).

[baaaaif]

I'm quite unhappy that, after an initial prospect of a quick fix, this is now being postponed for no apparent reason and not merged. ...while our customer escalates the situation and we stand powerless

[baaaaif]

@jfversluis Could you please merge this? Or is there some kind of professional support I can use to get this addressed? Then I can forward it internally to someone who has access to our Microsoft support contract.

[jfversluis]

@baaaaif have you tested this? Does it resolve your issue?

[jfversluis]

/rebase

[baaaaif]

Unfortunately, we were never able to reproduce it ourselves. It's purely a customer issue.

But as you said yourself, it doesn't hurt.

And the fix takes over the check that's already implemented in Dispose and DidDismiss and is simply missing here.

[jfversluis]

/azp run MAUI-public

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[baaaaif]

Thanks alot!
The Netherlands has not only the best music producers and festivals, but also simply fantastic developers 🙌
I really appreciate that.