Understanding Launch Modes

Oct 13, 2025 by wbrum.org 15 views

Introduction

As a developer working on a Maui Android app, you may encounter issues with the launch mode of your activities. In this article, we will discuss how to get Maui SingleTop and SingleTask working as documented. We will cover the basics of launch modes, how to configure them in Maui, and provide examples to help you understand the concepts.

Understanding Launch Modes

Launch modes determine how an activity is launched and managed by the system. There are four main launch modes:

Standard: This is the default launch mode. When an activity is launched in standard mode, a new instance of the activity is created each time it is launched.
SingleTop: When an activity is launched in single top mode, the system checks if there is an existing instance of the activity at the top of the back stack. If there is, the system brings that instance to the front. If not, a new instance is created.
SingleTask: When an activity is launched in single task mode, the system creates a new task and launches the activity in that task. If there is already an instance of the activity in the task, the system brings that instance to the front.
SingleInstance: When an activity is launched in single instance mode, the system creates a new task and launches the activity in that task. If there is already an instance of the activity in the task, the system brings that instance to the front. However, the system does not allow any other activities to be launched in the task.

Configuring Launch Modes in Maui

To configure launch modes in Maui, you need to use the LaunchMode attribute on the Activity class. Here are some examples:

SingleTop

[Activity(LaunchMode = LaunchMode.SingleTop)]
public class MyActivity : AppCompatActivity
{
    // ...
}

SingleTask

[Activity(LaunchMode = LaunchMode.SingleTask)]
public class MyActivity : AppCompatActivity
{
    // ...
}

SingleInstance

[Activity(LaunchMode = LaunchMode.SingleInstance)]
public class MyActivity : AppCompatActivity
{
    // ...
}

Resuming the App via the ... Menu

You mentioned that you are experiencing issues with resuming the app via the ... menu. This is likely due to the fact that your activity is created as SingleTask, but the system is not bringing the existing instance to the front.

To fix this issue, you need to add the following code to your activity's OnNewIntent method:

protected override void OnNewIntent(Intent intent)
{
    base.OnNewIntent(intent);
    // Handle the new intent here
}

This method is called when the system brings an existing instance of the activity to the front. You can use this method to handle the new intent and update your activity's state accordingly.

Example Use Case

Here is an example use case that demonstrates how to use SingleTop and SingleTask launch modes:

Suppose you have an app that receives files shared from WhatsApp or Telegram. You want to create an activity that displays the received files. You can configure the activity to use SingleTop launch mode, so that the system brings the existing instance to the front when the user resumes the app.

[Activity(LaunchMode = LaunchMode.SingleTop)]
public class FileDisplayActivity : AppCompatActivity
{
    // ...
}

When the user shares a file from WhatsApp or Telegram, the system launches the FileDisplayActivity in SingleTop mode. If there is already an instance of the activity in the back stack, the system brings that instance to the front. If not, a new instance is created.

Conclusion

In this article, we discussed how to get Maui SingleTop and SingleTask working as documented. We covered the basics of launch modes, how to configure them in Maui, and provided examples to help you understand the concepts. We also discussed how to handle resuming the app via the ... menu and provided an example use case that demonstrates how to use SingleTop and SingleTask launch modes.

By following the tips and examples provided in this article, you should be able to get your Maui Android app working as documented and provide a better user experience for your users.

Troubleshooting Tips

Here are some troubleshooting tips that may help you resolve issues with SingleTop and SingleTask launch modes:

Make sure that you have configured the launch mode correctly in your activity's Activity attribute.
Check that you have implemented the OnNewIntent method correctly to handle the new intent when the system brings an existing instance to the front.
Verify that you have not overridden the OnCreate method, which can cause issues with SingleTop and SingleTask launch modes.
Use the debugger to step through the code and see if the system is bringing the existing instance to the front as expected.

Q: What is the difference between SingleTop and SingleTask launch modes?

A: SingleTop and SingleTask launch modes are both used to manage the back stack of activities in an Android app. However, they behave differently when it comes to launching new instances of an activity.

SingleTop: When an activity is launched in SingleTop mode, the system checks if there is an existing instance of the activity at the top of the back stack. If there is, the system brings that instance to the front. If not, a new instance is created.
SingleTask: When an activity is launched in SingleTask mode, the system creates a new task and launches the activity in that task. If there is already an instance of the activity in the task, the system brings that instance to the front.

Q: How do I configure SingleTop and SingleTask launch modes in Maui?

A: To configure SingleTop and SingleTask launch modes in Maui, you need to use the LaunchMode attribute on the Activity class. Here are some examples:

SingleTop

[Activity(LaunchMode = LaunchMode.SingleTop)]
public class MyActivity : AppCompatActivity
{
    // ...
}

SingleTask

[Activity(LaunchMode = LaunchMode.SingleTask)]
public class MyActivity : AppCompatActivity
{
    // ...
}

Q: What happens when I launch an activity in SingleTop mode and there is no existing instance at the top of the back stack?

A: When you launch an activity in SingleTop mode and there is no existing instance at the top of the back stack, the system creates a new instance of the activity.

Q: What happens when I launch an activity in SingleTask mode and there is already an instance of the activity in the task?

A: When you launch an activity in SingleTask mode and there is already an instance of the activity in the task, the system brings that instance to the front.

Q: How do I handle the new intent when the system brings an existing instance to the front?

A: To handle the new intent when the system brings an existing instance to the front, you need to implement the OnNewIntent method in your activity. Here is an example:

protected override void OnNewIntent(Intent intent)
{
    base.OnNewIntent(intent);
    // Handle the new intent here
}

Q: What are some common issues that I may encounter when using SingleTop and SingleTask launch modes?

A: Some common issues that you may encounter when using SingleTop and SingleTask launch modes include:

Activity not being brought to the front: Make sure that you have configured the launch mode correctly and that the system is bringing the existing instance to the front as expected.
New instance being created instead of existing instance: Make sure that you have implemented the OnNewIntent method correctly to handle the new intent when the system brings an existing instance to the front.
Activity not being launched in the correct task: Make sure that you have configured the launch mode correctly and that the system is launching the activity in the correct task.

Q: How do I troubleshoot issues with SingleTop and SingleTask launch modes?

A: To troubleshoot issues with SingleTop and SingleTask launch modes, you can use the following steps:

Check the launch mode configuration: Make sure that you have configured the launch mode correctly in your activity's Activity attribute.
Implement the OnNewIntent method: Make sure that you have implemented the OnNewIntent method correctly to handle the new intent when the system brings an existing instance to the front.
Use the debugger: Use the debugger to step through the code and see if the system is bringing the existing instance to the front as expected.
Verify the activity's state: Verify that the activity's state is being updated correctly when the system brings an existing instance to the front.

By following these troubleshooting steps, you should be able to resolve issues with SingleTop and SingleTask launch modes and get your Maui Android app working as documented.