microsoft/add-dock-band

Add Dock Band Support

The Command Palette Dock is a persistent toolbar at the edge of the user's screen. Your extension can provide dock bands — strips of items that appear in the Dock — giving users quick access to commands without opening the full Command Palette.

When to Use This Skill

• Adding a quick-access button to the persistent toolbar
• Creating a multi-button toolbar strip
• Displaying live-updating information (clock, CPU usage, etc.)
• Providing frequently-used commands without opening the full palette

Prerequisites

• Command Palette Extension SDK version 0.9 or later (Microsoft.CommandPalette.Extensions ≥ 0.9.260303001)

Quick Start: Single Button Dock Band

Override GetDockBands() in your CommandProvider:

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

    public MyCommandsProvider()
    {
        DisplayName = "My Extension";
        Id = "com.mycompany.myextension"; // Unique ID required for dock

        var mainPage = new MyPage();
        _dockBand = new CommandItem(mainPage) { Title = DisplayName };
        _commands = [new CommandItem(mainPage) { Title = DisplayName }];
    }

    public override ICommandItem[] TopLevelCommands() => _commands;

    public override ICommandItem[]? GetDockBands() => [_dockBand];
}

Multi-Button Dock Band

Use WrappedDockItem to create a band with multiple buttons:

public override ICommandItem[]? GetDockBands()
{
    var button1 = new ListItem(new OpenUrlCommand("https://github.com"))
    {
        Title = "GitHub",
        Icon = new IconInfo("\uE774"),
    };
    var button2 = new ListItem(new OpenUrlCommand("https://learn.microsoft.com"))
    {
        Title = "Learn",
        Icon = new IconInfo("\uE82D"),
    };

    var band = new WrappedDockItem(
        [button1, button2],
        "com.mycompany.myextension.quicklinks", // Unique band ID
        "Quick Links");

    return [band];
}

Live-Updating Dock Band

Create a dock band that updates its content periodically (like a clock):

internal sealed partial class LiveStatusBand : ListItem
{
    private readonly System.Timers.Timer _timer;

    public LiveStatusBand()
        : base(new NoOpCommand() { Result = CommandResult.KeepOpen() })
    {
        Title = DateTime.Now.ToString("HH:mm");
        Icon = new IconInfo("\uE823"); // Clock icon

        _timer = new System.Timers.Timer(60_000); // Update every minute
        _timer.Elapsed += (s, e) =>
        {
            Title = DateTime.Now.ToString("HH:mm");
            Subtitle = DateTime.Now.ToString("dddd, MMMM d");
        };
        _timer.Start();
    }
}

// In CommandProvider:
public override ICommandItem[]? GetDockBands()
{
    var band = new WrappedDockItem(
        [new LiveStatusBand()],
        "com.mycompany.myextension.status",
        "Live Status");
    return [band];
}

How Dock Bands Render

| Command Type on ICommandItem | Dock Behavior | |------------------------------|---------------| | IInvokableCommand | Single button that executes the command | | IListPage | Each list item renders as a separate button in one band | | IContentPage | Single expandable button with a flyout |

Support Pinning Nested Commands

By default, only top-level commands and dock bands can be pinned. To allow pinning nested commands:

public override ICommandItem? GetCommandItem(string id)
{
    // Look up commands by their Id
    foreach (var item in GetAllCommands())
    {
        if (item?.Command is ICommand cmd && cmd.Id == id)
            return item;
    }
    return null;
}

Important Notes

• All dock band ICommandItem objects must have a Command with a non-empty Id — items without an ID are ignored
• Set Id on your CommandProvider (e.g., Id = "com.mycompany.myextension")
• Use WrappedDockItem for multi-button bands backed by a ListPage
• Keep dock band updates lightweight — they run frequently

Documentation

• Adding Dock support