Add Fallback Commands

Override FallbackCommands() in your CommandProvider:

public partial class MyCommandsProvider : CommandProvider
{
    private readonly ICommandItem[] _commands;
    private readonly FallbackCommandItem[] _fallbacks;

    public MyCommandsProvider()
    {
        DisplayName = "Web Search";
        Icon = new IconInfo("\uE721"); // Search icon

        var searchPage = new WebSearchPage();
        _commands = [new CommandItem(searchPage) { Title = DisplayName }];
        _fallbacks = [new FallbackCommandItem(searchPage) { Title = "Search the web" }];
    }

    public override ICommandItem[] TopLevelCommands() => _commands;
    public override IFallbackCommandItem[] FallbackCommands() => _fallbacks;
}

Dynamic Fallback with DynamicListPage

For fallbacks that filter results based on the query, use DynamicListPage:

internal sealed partial class WebSearchPage : DynamicListPage
{
    private string _query = string.Empty;

    public WebSearchPage()
    {
        Icon = new IconInfo("\uE721");
        Title = "Web Search";
        Name = "Search";
        PlaceholderText = "Type to search...";
    }

    public override void UpdateSearchText(string oldSearch, string newSearch)
    {
        _query = newSearch;
        RaiseItemsChanged();
    }

    public override IListItem[] GetItems()
    {
        if (string.IsNullOrWhiteSpace(_query))
            return [];

        return [
            new ListItem(new OpenUrlCommand($"https://www.google.com/search?q={Uri.EscapeDataString(_query)}"))
            {
                Title = $"Search Google for \"{_query}\"",
                Icon = new IconInfo("\uE721"),
            },
            new ListItem(new OpenUrlCommand($"https://www.bing.com/search?q={Uri.EscapeDataString(_query)}"))
            {
                Title = $"Search Bing for \"{_query}\"",
                Icon = new IconInfo("\uE721"),
            },
        ];
    }
}

Responsive Fallback with Cancellation

For expensive operations (API calls, file searches), use cancellation to stay responsive:

internal sealed partial class SmartSearchPage : DynamicListPage
{
    private CancellationTokenSource? _cts;
    private IListItem[] _results = [];

    public override void UpdateSearchText(string oldSearch, string newSearch)
    {
        // Cancel any in-flight search
        _cts?.Cancel();
        _cts = new CancellationTokenSource();
        var token = _cts.Token;

        _ = Task.Run(async () =>
        {
            // Debounce: wait for user to stop typing
            await Task.Delay(300, token);
            if (token.IsCancellationRequested) return;

            // Perform search
            _results = await SearchAsync(newSearch, token);
            RaiseItemsChanged();
        }, token);
    }

    public override IListItem[] GetItems() => _results;

    private async Task<IListItem[]> SearchAsync(string query, CancellationToken token)
    {
        // Your search logic here
        // Check token.IsCancellationRequested periodically
        return [];
    }
}

Real-World Examples (from built-in extensions)

Key Points

• FallbackCommands() returns IFallbackCommandItem[] (not ICommandItem[])
• Use FallbackCommandItem wrapper (not CommandItem)
• Wrap a DynamicListPage for query-reactive results
• Cancel previous searches when new input arrives
• Keep fallback responses fast — users expect instant results
• Use PlaceholderText on your page to guide users

Documentation

• Extension samples
• Extensibility overview