App actions

Article
11/29/2023

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IAppActions interface, which lets you create and respond to app shortcuts. App shortcuts are helpful to users because they allow you, as the app developer, to present them with extra ways of starting your app. For example, if you were developing an email and calendar app, you could present two different app actions, one to open the app directly to the current day of the calendar, and another to open to the email inbox folder.

The default implementation of the IAppActions interface is available through the AppActions.Current property. Both the IAppActions interface and AppActions class are contained in the Microsoft.Maui.ApplicationModel namespace.

Get started

To access the AppActions functionality, the following platform specific setup is required.

In the Platforms/Android/MainActivity.cs file, add the OnResume and OnNewIntent overrides to the MainActivity class, and the following IntentFilter attribute:

[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
[IntentFilter(new[] { Platform.Intent.ActionAppAction },
              Categories = new[] { global::Android.Content.Intent.CategoryDefault })]
public class MainActivity : MauiAppCompatActivity {

    protected override void OnResume()
    {
        base.OnResume();

        Platform.OnResume(this);
    }

    protected override void OnNewIntent(Android.Content.Intent intent)
    {
        base.OnNewIntent(intent);

        Platform.OnNewIntent(intent);
    }

}

Create actions

App actions can be created at any time, but are often created when an app starts. To configure app actions, invoke the ConfigureEssentials(MauiAppBuilder, Action<IEssentialsBuilder>) method on the MauiAppBuilder object in the MauiProgram.cs file. There are two methods you must call on the IEssentialsBuilder object to enable an app action:

AddAppAction

This method creates an action. It takes an id string to uniquely identify the action, and a title string that's displayed to the user. You can optionally provide a subtitle and an icon.
OnAppAction

The delegate passed to this method is called when the user invokes an app action, provided the app action instance. Check the Id property of the action to determine which app action was started by the user.

The following code demonstrates how to configure the app actions at app startup:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        })
        .ConfigureEssentials(essentials =>
        {
            essentials
                .AddAppAction("app_info", "App Info", icon: "app_info_action_icon")
                .AddAppAction("battery_info", "Battery Info")
                .OnAppAction(App.HandleAppActions);
        });

    return builder.Build();
}

Responding to actions

After app actions have been configured, the OnAppAction method is called for all app actions invoked by the user. Use the Id property to differentiate them. The following code demonstrates handling an app action:

public static void HandleAppActions(AppAction appAction)
{
    App.Current.Dispatcher.Dispatch(async () =>
    {
        var page = appAction.Id switch
        {
            "battery_info" => new SensorsPage(),
            "app_info" => new AppModelPage(),
            _ => default(Page)
        };

        if (page != null)
        {
            await Application.Current.MainPage.Navigation.PopToRootAsync();
            await Application.Current.MainPage.Navigation.PushAsync(page);
        }
    });
}

Check if app actions are supported

When you create an app action, either at app startup or while the app is being used, check to see if app actions are supported by reading the AppActions.Current.IsSupported property.

Create an app action outside of the startup bootstrap

To create app actions, call the SetAsync method:

if (AppActions.Current.IsSupported)
{
    await AppActions.Current.SetAsync(new[] { new AppAction("app_info", "App Info", icon: "app_info_action_icon"),
                                              new AppAction("battery_info", "Battery Info") });
}

More information about app actions

If app actions aren't supported on the specific version of the operating system, a FeatureNotSupportedException will be thrown.

Use the AppAction(String, String, String, String) constructor to set the following aspects of an app action:

Id: A unique identifier used to respond to the action tap.
Title: the visible title to display.
Subtitle: If supported a subtitle to display under the title.
Icon: Must match icons in the corresponding resources directory on each platform.

App actions on home screen.

Get actions

You can get the current list of app actions by calling AppActions.Current.GetAsync.

Share via