[Android] Fix for App Hang When PopModalAsync Is Called Immediately After PushModalAsync with Task.Yield()

[BagavathiPerumal]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Root Cause:

The issue was caused by a timing inconsistency in Android’s modal navigation behavior. When invoking PushModalAsync() with animated: false, Android displays the modal fragment but returns control before the modal is fully initialized and ready for interaction. Subsequently, if Task.Yield() is followed by PopModalAsync(), the pop operation attempts to interact with a modal that has not yet completed its loading process, resulting in the application hanging.

This problem does not occur with animated modals, as the animation duration provides sufficient time for the modal to complete its loading sequence before any subsequent operations are executed.

Fix Description:

The fix involves ensuring that non-animated modals are fully loaded before allowing any subsequent operations. A new event, PresentationCompleted, has been introduced to signal when Android confirms that the modal is completely initialized and ready for use. With this improvement, when PushModalAsync() is called with animated: false, the method waits for the PresentationCompletedevent before returning control. This ensures that the modal is ready for any follow-up operations, such as Task.Yield() or PopModalAsync(). The Animated modals continue to function as before to maintain optimal performance.

Issues Fixed

Fixes #32310

Tested the behaviour in the following platforms

• Android
• Windows
• iOS
• Mac

Output Screenshot

Before Issue Fix	After Issue Fix
32310-BeforeFix.mov	32310-AfterFix.mov

[sheiksyedm]

/azp run MAUI-UITests-public

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Copilot]

Pull Request Overview

This PR fixes an Android-specific app hang that occurred when PopModalAsync is called immediately after PushModalAsync with animated: false, separated only by await Task.Yield(). The root cause was that non-animated modals returned control before the modal fragment completed initialization, causing subsequent pop operations to fail.

Key changes:

• Introduced a PresentationCompleted event in ModalFragment that fires in OnStart() when the dialog window is fully laid out
• For non-animated modals, PushModalAsync now waits for PresentationCompleted before returning, ensuring the modal is fully initialized
• Animated modals continue to use the existing AnimationEnded event pattern for optimal performance

Reviewed Changes

Copilot reviewed 3 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Controls/src/Core/Platform/ModalNavigationManager/ModalNavigationManager.Android.cs	Refactored PresentModal to separate animated and non-animated paths, adding PresentationCompleted event handling for non-animated modals to prevent race conditions
src/Controls/tests/TestCases.HostApp/Issues/Issue32310.cs	Added test page that reproduces the hang scenario with non-animated modal push/pop separated by Task.Yield()
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue32310.cs	Added UI test that validates the modal navigation completes without hanging
src/Controls/tests/TestCases.Android.Tests/snapshots/android/ModalNavigationShouldNotHang.png	Added Android screenshot baseline for visual regression testing
src/Controls/tests/TestCases.iOS.Tests/snapshots/ios/ModalNavigationShouldNotHang.png	Added iOS screenshot baseline for cross-platform test consistency

[PureWeen]

Let me know what you think of these suggestions for additions to ModalNavigationManager.android.cs

			public override void OnDestroy()
			{
				base.OnDestroy();
				FireAnimationEnded();
				
				// SAFETY: If destroyed before OnStart completed, fire PresentationCompleted to prevent deadlock
				if (!_presentationCompleted)
				{
					_presentationCompleted = true;
					PresentationCompleted?.Invoke(this, EventArgs.Empty);
				}
			}

and then inside OnStart

public override void OnStart()
			{
				base.OnStart();

				var dialog = Dialog;

				if (dialog is null || dialog.Window is null || View is null)
				{
					// SAFETY: Fire event even on early return to prevent deadlock
					_presentationCompleted = true;
					PresentationCompleted?.Invoke(this, EventArgs.Empty);
					return;
				}

				int width = ViewGroup.LayoutParams.MatchParent;
				int height = ViewGroup.LayoutParams.MatchParent;
				dialog.Window.SetLayout(width, height);

				// Signal that the modal is fully presented and ready
				_presentationCompleted = true;
				PresentationCompleted?.Invoke(this, EventArgs.Empty);
			}

[BagavathiPerumal]

Let me know what you think of these suggestions for additions to ModalNavigationManager.android.cs

			public override void OnDestroy()
			{
				base.OnDestroy();
				FireAnimationEnded();
				
				// SAFETY: If destroyed before OnStart completed, fire PresentationCompleted to prevent deadlock
				if (!_presentationCompleted)
				{
					_presentationCompleted = true;
					PresentationCompleted?.Invoke(this, EventArgs.Empty);
				}
			}

and then inside OnStart

public override void OnStart()
			{
				base.OnStart();

				var dialog = Dialog;

				if (dialog is null || dialog.Window is null || View is null)
				{
					// SAFETY: Fire event even on early return to prevent deadlock
					_presentationCompleted = true;
					PresentationCompleted?.Invoke(this, EventArgs.Empty);
					return;
				}

				int width = ViewGroup.LayoutParams.MatchParent;
				int height = ViewGroup.LayoutParams.MatchParent;
				dialog.Window.SetLayout(width, height);

				// Signal that the modal is fully presented and ready
				_presentationCompleted = true;
				PresentationCompleted?.Invoke(this, EventArgs.Empty);
			}

@PureWeen, Thanks for the suggestion. I have implemented the suggested code changes with a FirePresentationCompleted() helper method (matching the existing FireAnimationEnded() pattern) to ensure the event fires exactly once and prevent deadlocks on early returns or premature destruction.

[sheiksyedm]

/azp run MAUI-UITests-public

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[pictos]

I've added some comments from points that I saw from my implementation

[pictos]

I would say we don't need this here. I added those null check here to make the nullable analyser happy. If this results in true, something is very wrong.

[BagavathiPerumal]

@pictos, I have added FirePresentationCompleted() in the null check condition to prevent potential deadlocks as per @PureWeen's suggestion. Please find the below comment for your reference.

Comment link: #32479 (review)

[pictos]

@BagavathiPerumal I read it, but not sure if we just want to complete the Task or set an exception to the user, since the navigation will be in a invalid state.

cc: @PureWeen

[pictos]

This could be only a TaskCompletionSource, since the value isn't needed

[BagavathiPerumal]

I have modified the code based on your suggestion. Changed to TaskCompletionSource without generic type parameter in the non-animated modal presentation path as the completion value isn't needed.

[pictos]

I'm sorry I thought I had deleted this comment. We need to have the generic because the project targets net-standard2.0 and on that target there's no TaskCompletionSource without generic.

[BagavathiPerumal]

@pictos, Thanks for clarifying. I have maintained the TaskCompletionSource<bool> with the generic type parameter since this project targets .NET Standard 2.0.

[pictos]

I'm not sure if it's a good idea to complete the TCS, I would say the best here is to Cancel it

[BagavathiPerumal]

@pictos, I have added FirePresentationCompleted() in OnDestroy() to handle cases where the fragment is destroyed before OnStart() completes, preventing deadlocks based on @PureWeen ’s earlier suggestion, which I mentioned in my previous comment.

changes applied