PowerToys/src/modules/cmdpal/doc/initial-sdk-spec/initial-sdk-spec.md

author, created on, last updated, issue id

author	created on	last updated	issue id
Mike Griese	2024-07-19	2025-03-10	n/a

Run v2 Extensions SDK

aka "DevPal", "PT Run v2", "DevSearch", "Windows Command Palette", this thing has many names. I'll use "DevPal" throughout the doc

[NOTE!] Are you here to just see what the SDK looks like? Skip to the Commands SDK details section.

Abstract

"DevPal" is "PowerToys Run v2" - the graduated form of PowerToys Run, ready for ingestion as a Windows inbox app. DevPal enables the user to launch more than just apps and search for files - it's a highly customizable surface that allows users to "Start anything".

Most importantly, DevPal is highly extensible. By exposing a simple-to-use SDK, DevPal enables 3p developers to quickly create plugins and extend it functionality.

• Run v2 Extensions SDK
  • Abstract
  • Background
    • Inspiration
    • User Stories
    • Elevator Pitch
  • Business Justification
  • Scenario Details
    • Extension basics
    • Installed extension discovery
      • Unpackaged extensions
    • Extension lifecycle
      • Startup
      • Caching
        • Loading commands from stub items
        • Microwaved commands
      • Disposing
  • Installing extensions
    • From the Store
    • From winget
  • Publishing extensions
  • Built-in commands
  • SDK overview
  • Commands SDK details
    • Commands
      • Results
    • Pages
      • List Pages
        • Updating the list
        • Empty content
        • Filtering the list
      • Content Pages
        • Markdown Content
        • Form Content
    • Other types
      • ContextItems
      • Icons - IconInfo and IconData
      • OptionalColor
      • Details
      • INotifyPropChanged
      • ICommandProvider
      • Fallback commands
        • GetCommand
        • Settings
  • Helper SDK Classes
    • Default implementations
    • Using the Clipboard
    • Settings helpers
  • Advanced scenarios
    • Status messages
    • Rendering of ICommandItems in Lists and Menus
  • Class diagram
  • Future considerations
    • Arbitrary parameters and arguments
    • URI activation
    • Custom "empty list" messages
  • Footnotes
    • Generating the .idl
    • Adding APIs

Background

Note

This is the spec specifically for the devpal SDK. For a more general overview of devpal, see the this functional spec (internal only).

Inspiration

The largest inspiration for this extension SDK is the Dev Home Extension model. They are the ones who pioneered the plumbing for registering COM classes in the extension manifest, then using CoCreateInstance to create objects in the host and use them as WinRT objects.

User Stories

(typically there'd be a long list of user stories here, but that felt better suited for a more general DevPal dev spec, rather than the SDK doc)

Elevator Pitch

"Start anything here".

What if the Start Menu was more than just a launcher for apps? What if it could be the start for all sorts of different workflows? One that apps could plug into directly, and provide dedicated experiences for their users.

Business Justification

It will delight developers all power users.

Scenario Details

Note

This document is largely concerned with the details for how 3p apps could plug into DevPal. However, much of the built-in devpal functionality will be built using the same interfaces. This will make sure that everything that we build keeps 3p use cases in mind. Built-in experiences, however, can be loaded in-proc, so they can skip pretty much all of this doc up till "SDK overview".

Extension basics

In the simplest case, extensions for Dev Pal can register themselves using their .appxmanifest. As an example:

<Extensions>
    <com:Extension Category="windows.comServer">
        <com:ComServer>
            <com:ExeServer Executable="ExtensionName.exe" Arguments="-RegisterProcessAsComServer" DisplayName="Sample Extension">
                <com:Class Id="<Extension CLSID Here>" DisplayName="Sample Extension" />
            </com:ExeServer>
        </com:ComServer>
    </com:Extension>
    <uap3:Extension Category="windows.appExtension">
        <uap3:AppExtension Name="com.microsoft.commandpalette"
                           Id="YourApplicationUniqueId"
                           PublicFolder="Public"
                           DisplayName="Sample Extension"
                           Description="Sample Extension for Run">
            <uap3:Properties>
                <CmdPalProvider>
                    <Activation>
                        <CreateInstance ClassId="<Extension CLSID Here>" />
                    </Activation>
                    <SupportedInterfaces>
                        <Commands />
                    </SupportedInterfaces>
                </CmdPalProvider>
            </uap3:Properties>
        </uap3:AppExtension>
    </uap3:Extension>
</Extensions>

Notable elements:

• The application must specify a Extensions.comExtension.ComServer to host their COM class. This allows for the OS to register that GUID as a COM class we can instantiate.
  • Make sure that this CLSID is unique, and matches the one in your application
• The application must specify a Extensions.uap3Extension.AppExtension with the Name set to com.microsoft.commandpalette. This is the unique identifier which DevPal can use to find it's extensions.
• In the Properties of your AppExtension, you must specify a CmdPalProvider element. This is where you specify the CLSID of the COM class that DevPal will instantiate to interact with your extension. Also, you specify which interfaces you support.

Currently, only Commands is supported. If we need to add more in the future, we can add them to the SupportedInterfaces element.

This is all exactly the same as the Dev Home Extension model, with a different Name in the AppExtension element, and different SupportedInterfaces.

Installed extension discovery

Fortunately for DevPal, it is quite trivial to enumerate installed packages that have registered themselves as a AppExtension extensions. This is done by querying the AppExtensionCatalog for all extensions with the Name set to com.microsoft.commandpalette.

Unpackaged extensions

Sparse packages are always a simple solution for adding package identity to otherwise unpackaged applications. However, there may be apps out there that (for whatever reason) still don't have a package identity. We need a way to allow these apps to register themselves as extensions.

We can't just ask the COM catalog for all CLSIDs that implement a particular COM interface, unfortunately. This means we'll need another well-known location in the registry for unpackaged apps to write their extension CLSID's into.

We'll create a registry key at HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\DevPal\Extensions [TODO!api-review]: not this path. I think that's owned by the OS with a subkey for each extension. The subkey should be the Name of the extension, and the default value should be the CLSID of the COM class that implements the extension. On startup, DevPal will enumerate these keys in addition to the packaged ones. Apps should not write into both locations, unless they have two separate extension classes to load.

On uninstall, apps should remove themselves from that registry key.

Extension lifecycle

Startup

When an extension is installed, DevPal will find it in the AppExtensionCatalog, and parse the AppExtension.Properties. It will then instantiate the COM class specified in the CreateInstance element. It is ultimately up to the extension app how it wants to serve that COM class. In the simplest case (above), COM will create the ExtensionName.exe process to serve the COM object.

A more elaborate use case would have an existing process that the COM object is created in. This is useful for extensions that need to deeply tie into a running application. One could imagine a Windows Terminal extension that produces a list of all the open windows, tabs and panes. This extension would be best served by the Terminal process itself, as it has all the context it needs to produce that list.

When DevPal launches, it will enumerate all the extensions it knows about, and create the IExtension object for each one. DevPal will then get the ICommandProvider for apps that register as Commands providers in SupportedInterfaces. Extension apps should have that COM object served quickly, for performance. That is the first object that DevPal needs, to load the top-level list of commands.

These commands will be loaded asynchronously, and the UI will be updated as they are loaded on a cold launch. Subsequent launches will have devpal already running in the background.

Each individual page will be loaded as the user navigates to it. This allows for apps to lazily load their "UI content" as needed.

Caching

A key goal of DevPal is to have it start as fast as possible, and have the footprint while it's running be minimal. If DevPal needed to instantiate every extension just to get the top-level list of commands, the impact on startup would grow as the user installed more extensions. Additionally, each extension installed would result in another process starting and running for the lifetime of DevPal.

To avoid this, DevPal can "cache" the toplevel commands for an extension. This will allow DevPal to display these commands to the user on startup, without needing to keep the extension process running.

Command Providers which can have their commands cached are called "frozen", and have Frozen=true set in ICommandProvider. This is the default for apps using the helpers library. For the large majority of extensions, the list of commands won't change over time. These extensions can be cached to save resources.

Command providers can opt out of this behavior by setting Frozen=false in their extension. We'll call these extensions "fresh, never frozen".

As some examples:

• The "Hacker News" extension, only has a single top-level command. Once we load that once, we don't need to CreateProcess just to find that command title. This is a frozen extension.
• Similarly for something like the GitHub extension - it's got multiple top-level commands (My issues, Issue search, Repo search, etc), but these top-level commands never change. This is a frozen extension.
• The "Quick Links" extension has a dynamic list of top-level commands. This is a fresh extension.¹
• The "Media Controls" extension only has a single top-level command, but it needs to be running to be able to update it's title and icon. So we can't just cache the state of it. This is a fresh extension.
• Similarly, any top-level IFallbackHandler need to be running to get real-time updates to their name. Any extension with a top-level IFallbackHandler will be treated as fresh extension.

How do we actually cache this frozen list?

Our goal is to make initial startup to be fast, even faster than hitting the package catalog. To support this, DevPal will cache information about the top-level commands it gets from extensions. With that cached information, DevPal can create "stub" entries of those commands in the palette, without launching the extension first.

The structure of the data DevPal caches will look something like the following:

{
    "extensions": [
        {
            "pfn": "TemplateExtension_0.0.1.0_x64__8wekyb3d8bbwe",
            "clsid": "{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}",

            "displayName": "TemplateDisplayName",
            "frozen": true,
            "commands":
            [
                {
                    "id": "TemplateExtension.MyFirstCommand",
                    "icon": "",
                    "title": "",
                    "subtitle": "",
                    "name": "",
                    "moreCommands": [ /* Additional commands... */]
                }
            ]
        }
    ]

}

In this data you can see:

• We cache some basic info about each extension we've seen. This includes
  • the Package Family Name (a unique identifier per-app package),
  • the COM CLSID for that extension,
  • the display name for that extension,
  • and if that extension is frozen or not.
• We also cache the list of top-level commands for that extension. We'll store the basic amount of info we need to recreate that command in the top-level list.

On a cold launch, DevPal will do the following:

1. SLOW: First we start up WASDK and XAML. Unavoidable cost.
2. FAST: We load builtin extensions. These are just extensions in DLLs, so there's nothing to it.
3. FAST: We load our cache of extensions from disk, and note which are frozen vs fresh
   • We needs this to know which extensions have classes we need to instantiate (fresh), vs ones we can lazy-start (frozen)
   • We'll create stub extension objects here, with the CLSID and commandline stored.
     • note: we don't need the executable/commandline. Just the clsid. We still want to leave it to COM to deal with actually starting the COM server. That's not our job, and we don't need the package catalog loaded to get that - only the clsid.
4. FAST: With our extension & command cache, get the list of commands, and add those items as "stub" list items
   • These items don't have an actual live extension object backing them. They're just the data we cached from the extension.
   • Stubs refer to the stub extension object we created in 3
   • When the user clicks on a stub item, we'll do what's outlined in Loading commands from stub items below.
5. SLOW: We open the package catalog for more commands
   • Extensions that we've seen before in our cache:
     • If it's fresh, we'll start it, and fill in commands from TopLevelCommands into the palette
     • If it's frozen, we'll leave it be. We've already got stubs for it.
   • Extensions we've never seen before:
     • Start it up.
     • Check if it's fresh or frozen.
     • Call TopLevelCommands, and put all of them in the list
     • Create a extension cache entry for that app.
     • If the provider is frozen: we can actually release the ICommandProvider instance at this point.
   • And of course, if we don't find all the packages we had cached, then delete entries for the missing ones. Those apps were uninstalled.
6. We start a package catalog change watcher to be notified by the OS for changes to the list of installed extensions

After 1, we can display the UI. It won't have any commands though, so maybe we should wait. After 2, we'd have some commands, but nothing from extensions After 4, the palette is ready to be used, with all the frozen extension commands. This is probably good enough for most use cases.

Most of the time, when the user "launches" devPal, we won't run through this whole process. The slowest part of startup is standing up WASDK and WinUI. After the first launch, we will keep our window will be hidden, running silently in the background. When the user presses the global hotkey, or otherwise launches the app, we'll just activate our existing process. This is a "warm launch".

On a warm launch, we already have all the stubs in memory. We're listening for package installs/uninstalls already. So we're basically just in the post-step 5 state already.

Loading commands from stub items

^"reheating"

When the user activates a top-level "stub" list item (referring to a frozen command), we need to quickly load that app and get the command for it.

1. If this stub has already been reheated, just return out the ICommand we instantiated last time, and skip this whole process.
2. Get the extension stub out of that item
   • If that fails: display an error message.
3. Check if the extension is already in the warm extension cache. If it is, we recently reheated a command from this provider. We can skip step 4 and go straight to step 5
4. Use the CLSID from the cache to CoCreateInstance this extension, and get its ICommandProvider.
   • If that fails: display an error message.
5. Try to load the command from the provider. This is done in two steps:
   1. If the cached command had an id, try to look up the command with ICommandProvider.GetCommand(id), passing the id. If that returns an item, we can move on to the next stem
   2. Otherwise (the command wasn't assigned an ID, or GetCommand returned null): all TopLevelItems on that CommandProvider.
      • Search through all the returned commands with the same id or icon/title/subtitle/name, and return that one.
6. If we found the command from the provider, navigate to it or invoke it.

Microwaved commands

DevPal will want to keep the last N extensions that were activated "warm", so that they are ready to be re-activated again. Once a command provider is reheated, we'll keep it around in a warm extension cache. Stubs that have been activated by reheating them can then skip a CommandProvider lookup (GetCommand or TopLevelItems).

We'll give the user options to control how many of the most recent commands we keep warm at a given time. We'll probably also want to offer an option like "always warm up {this command} / {all commands}", if the user doesn't care about the memory usage as much.

[WARNING!]

If your command provider returns a IFallbackCommandItems from FallbackCommands, and that provider is marked frozen, DevPal will always treat your provider as "fresh". Otherwise, devpal wouldn't be able to call into the extension to have the IFallbackHandler respond to the search query.

The alternative would be to have DevPal just ignore the fallback handler from that provider. Silently doing nothing seemed less user friendly than silently doing What's Expected.

Disposing

As implied by the above section, all the extensions for DevPal won't be loaded and running all at once. We'll only keep the "fresh never frozen" extensions running, as well as the last N most recently used commands. Once we've exceeded that limit of recent commands, we'll release our reference to the COM object for that extension, and re-mark commands from it as "stubs". Upon the release of that reference, the extension is free to clean itself up. For extensions that use the helpers library, they can override CommandProvider.Dispose to do cleanup in there.

Installing extensions

From the Store

These are fairly straightforward. The user goes to the Store, finds an extension app, and installs it. When they do that, the PackageCatalog will send us an event which we can use to update our list of extensions.

At the time of writing, there's not an easy way to query the store for a list of apps who's manifest specifies that they are an extension. We could launch something like:

ms-windows-store://assoc/?Tags=AppExtension-com.microsoft.commandpalette

to open the store to a list of extensions. However, we can't list those ourselves directly. Our friends in DevHome suggested it could be possible to stand up a azure service which could query the store for us, and return a list of extensions. This is not something that they currently have planned, nor would it be cheap from an engineering standpoint.

From winget

Winget on the other hand, does allow packages to specify arbitrary tags, and let apps query them easily. We can use that as a system to load a list of packages available via winget directly in DevPal. We'll specify a well-known tag that developers can use in their winget package manifest to specify that their package is an extension. We will then query winget for all packages with that tag, to expose a list of possible extensions.

Publishing extensions

As a part of DevPal, we'll ship a "Sample Project" template. We will use this to be able to quickly generate a project that can be used to create a new extension. This will include the sln, csproj, and appxmanifest files that are needed to create a new extension, as well as plumbing to get it all ready. All the developer will need to do is open up the project to the MyCommandProvider class and start implementing their commands.

As a part of this project template, we'll include a winget GitHub Actions workflow that will allow the developer to push their extension to winget with the needed tags to be discoverable by DevPal. That way, developers won't need to worry about the details of packaging, they can just push to main and let the pipeline take care of the rest.

Built-in commands

Certain commands are "built-in" to DevPal. These are commands that ship directly in the DevPal package. These don't need to be loaded as out-of-proc COM extensions like the third-party ones. However, they will still conform to the same interface as third-party commands. This allows us to have a consistent experience for the user. It also cements the ability for 3p extensions to do anything that a 1p built-in can do.

SDK overview

The SDK for DevPal is split into two namespaces:

• Microsoft.CommandPalette.Extensions - This namespace contains the interfaces that developers will implement to create extensions for DevPal.
• Microsoft.CommandPalette.Extensions.Toolkit - This namespace contains helper classes that developers can use to make creating extensions easier.

The first is highly abstract, and gives developers total control over the implementation of their extension. The second contains a variety of default implementations and helper classes that developers can use to make authoring extensions simpler.

Commands SDK details

Below details the SDK that developers can use to create extensions for the DevPal. These interfaces are exposed through the Microsoft.CommandPalette.Extensions namespace. We'll expose an SDK with helper classes and default implementations in the Microsoft.CommandPalette.Extensions namespace.

[NOTE!]

In the following SDK details, csharp & c# code fences to show snippets of what the Microsoft.CommandPalette.Extensions interface will look like. This is roughly midl v3 in this spec, with one modification. I'm using the made up async keyword to indicate that a method is async. In the real .idl, these methods will be replaced with IAsyncAction for async void and IAsyncOperation<T> for async T.

cs code fences will be used for samples of what an extension implementations may look like.

Commands

Commands are the primary unit of functionality in the DevPal SDK. They represent "a thing that a user can do". These can be something simple like open a URL in a web browser. Or they can be more complex, with nested commands, custom arguments, and more.

interface ICommand requires INotifyPropChanged{
    String Name{ get; };
    String Id{ get; };
    IIconInfo Icon{ get; };
}

enum CommandResultKind {
    Dismiss,    // Reset the palette to the main page and dismiss
    GoHome,     // Go back to the main page, but keep it open
    GoBack,     // Go back one level
    Hide,       // Keep this page open, but hide the palette.
    KeepOpen,   // Do nothing.
    GoToPage,   // Go to another page. GoToPageArgs will tell you where.
    ShowToast,  // Display a transient message to the user
    Confirm,    // Display a confirmation dialog
};

enum NavigationMode {
    Push,   // Push the target page onto the navigation stack
    GoBack, // Go back one page before navigating to the target page
    GoHome, // Go back to the home page before navigating to the target page
};

[uuid("f9d6423b-bd5e-44bb-a204-2f5c77a72396")]
interface ICommandResultArgs{};
interface ICommandResult {
    CommandResultKind Kind { get; };
    ICommandResultArgs Args { get; };
}
interface IGoToPageArgs requires ICommandResultArgs{
    String PageId { get; };
    NavigationMode NavigationMode { get; };
}
interface IToastArgs requires ICommandResultArgs{
    String Message { get; };
    ICommandResult Result { get; };
}
interface IConfirmationArgs requires ICommandResultArgs{
    String Title { get; };
    String Description { get; };
    ICommand PrimaryCommand { get; };
    Boolean IsPrimaryCommandCritical { get; };
}

// This is a "leaf" of the UI. This is something that can be "done" by the user.
// * A ListPage
// * the MoreCommands flyout of for a ListItem or a MarkdownPage
interface IInvokableCommand requires ICommand {
    ICommandResult Invoke(Object sender);
}

If a developer wants to add a simple command to DevPal, they can create a class that implements ICommand, and implement the Invoke method. This method will be called when the user selects the command in DevPal.

As a simple example² :

class HackerNewsPage : Microsoft.CommandPalette.Extensions.Toolkit.InvokableCommand {
    public class HackerNewsPage()
    {
        Name = "Hacker News";
        Icon = "https://news.ycombinator.com/favicon.ico";
    }

    public ICommandResult Invoke() {
        Process.Start(new ProcessStartInfo("https://news.ycombinator.com/") { UseShellExecute = true });
        return CommandResult.Hide();
    }
}

This will create a single command in DevPal that, when selected, will open Hacker News in the user's default web browser.

Commands can also be Pages, which represent additional "nested" pages within DevPal. When the user selects an command that implements IPage, DevPal will navigate to a page for that command, rather than calling Invoke on it. Skip ahead to Pages for more information on the different types of pages.

The Id property is optional. This can be set but the extension author to support more efficient command lookup in ICommandProvider.GetCommand(), below.

When Invoke is called, the host app will pass in a sender object that represents the context of where that command was invoked from. This can be different types depending on where the command is being used:

• TopLevelCommands (and fallbacks)
  • Sender is the ICommandItem for the top-level command that was invoked
• IListPage.GetItems
  • Sender is the IListItem for the list item selected for that command
• ICommandItem.MoreCommands (context menus)
  • Sender is the IListItem which the command was attached to for a list page, or
  • the ICommandItem of the top-level command (if this is a context item on a top level command)
• IContentPage.Commands
  • Sender is the IContentPage itself

The helpers library also exposes a Invoke() method on InvokableCommand which takes no parameters, as a convenience for developers who don't need the sender object.

Using the sender parameter can be useful for big lists of items where the actionable information for each item is practically the same. Consider a big list of links. An extension developer can implement this as a single IInvokableCommand that opens a URL based on the sender object passed in. Then each list item would store the URL to open and the title of the link. This creates less overhead for the extension and host to communicate.

Results

Commands can return a CommandResult to indicate what DevPal should do after the command is executed. This allows for commands to control the flow of the DevPal. For example, an action that opens a URL might return Kind = CommandResult.Dismiss to close DevPal after the URL is opened.

Use cases for each CommandResultKind:

• Dismiss - Close DevPal after the action is executed. All current state is dismissed as well. On the next launch, DevPal will start from the main page with a blank query.
  • Ex: An action that opens an application. The Puser doesn't need DevPal open after the application is opened, nor do they need the query they used to find the action.
• GoHome - Navigate back to the main page of DevPal, but keep it open. This clears out the current stack of pages, but keeps DevPal open.
  • Note: if the action navigates to another application, DevPal's default behavior is to hide itself when it loses focus. That will behave the same as Dismiss in that case.
  • Ex: The "Add Quick Link" command is a form. After submitting the form, the user should be taken back to the main page, with the query cleared, leaving the window open.
• GoBack - Navigate to the previous page, and keep it open. Useful for submitting a form, then going back to the parent page of the form
• KeepOpen - Do nothing. This leaves the palette in its current state, with the current page stack and query.
  • Note: if the action navigates to another application, DevPal's default behavior is to hide itself when it loses focus. When the user next activates DevPal, it will be in the same state as when it was hidden.
  • Ex: An action that opens a URL in a new tab, like the Hacker News sample. The user might want to open multiple URLs in a row, so DevPal should stay in its current state.
• GoToPage - Navigate to a different page in DevPal. The GoToPageArgs will specify which page to navigate to.
  • Push: The new page gets added to the current navigation stack. Going back from the requested page will take you to the current page.
  • GoBack: Go back one level, then navigate to the page. Going back from the requested page will take you to the page before the current page.
  • GoHome: Clear the back stack, then navigate to the page. Going back from the requested page will take you to the home page (the L0).
• ShowToast - Display a transient desktop-level message to the user. This is especially useful for displaying confirmation that an action took place, when the palette will be closed. Consider the CopyTextCommand in the helpers - this command will show a toast with the text "Copied to clipboard", then dismiss the palette.
  • Once the message is displayed, the palette will then react to the Result. In the helpers library, the ToastArgs's default Result value is Dismiss.
  • Only one toast can be displayed at a time. If a new toast is requested before the previous one is dismissed, the new toast will replace the old one. This includes if the Result of one IToastArgs is another IToastArgs.
• Confirm: Display a confirmation dialog to the user. This is useful for actions that are destructive or irreversible. The ConfirmationArgs will specify the title, and description for the dialog. The primary button of the dialog will activate the Command. If IsPrimaryCommandCritical is true, the primary button will be red, indicating that it is a destructive action.

Pages

Pages represent individual views in the application. They are the primary unit of navigation and interaction. Developers can author Commands as a page to provide an additional page of functionality within the application. They are not wholly responsible for their own rendering. Rather, they provide bits of information that the host application will then use to render the page.

interface IPage requires ICommand {
    String Title { get; };
    Boolean IsLoading { get; };

    OptionalColor AccentColor { get; };
}

When a user selects an action that implements IPage, DevPal will navigate to that page, pushing it onto the UI stack.

Pages can be one of several types, each detailed below:

• List
• Content

If a page returns a null or empty Title, DevPal will display the Name of the ICommand instead.

Pages have a Loading property which they can use to indicate to DevPal that the content is still loading. When Loading is true, DevPal will show an indeterminate loading bar to the user. When Loading is false, DevPal will hide the progress bar. This allows extensions which are displaying asynchronous content to indicate that something is happening in the background.

Pages are ICommands, which means they also are observable via the INotifyPropChanged interface. This allows the page to set Loading as needed and change the value once the results are loaded.

Pages may also specify an AccentColor. DevPal will use this color to stylize elements of the page with that color.

List Pages

Lists are the most common type of page. They represent a collection of items which the user can quickly filter and search through.

Lists can be either "static" or "dynamic":

• A static list leaves devpal in charge of filtering the list of items, based on the query the user typed.
  • These are implementations of the default IListPage.
  • In this case, DevPal will use a fuzzy string match over the Name of the action, the Subtitle, and any Text on the Tags.
• A dynamic list leaves the extension in charge of filtering the list of items.
  • These are implementations of the IDynamicListPage interface.
  • In this case, the host app will call the setter for SearchText on the IDynamicListPage when the user changes the query. The extension may then raise an ItemsChanged event afterwards, to let the host know it needs to fetch items again. Additionally, the host app won't do any filtering of the results - it's the extension's responsibility to filter them.
    • Ex: The GitHub extension may want to allow the user to type is:issue is:open, then return a list of open issues, without string matching on the text.

[uuid("c78b9851-e76b-43ee-8f76-da5ba14e69a4")]
interface IContextItem {}

interface ICommandItem requires INotifyPropChanged {
    ICommand Command{ get; };
    IContextItem[] MoreCommands{ get; };
    IIconInfo Icon{ get; };
    String Title{ get; };
    String Subtitle{ get; };
}

interface ICommandContextItem requires ICommandItem, IContextItem {
    Boolean IsCritical { get; }; // READ: "make this red"
    KeyChord RequestedShortcut { get; };
}

[uuid("924a87fc-32fe-4471-9156-84b3b30275a6")]
interface ISeparatorContextItem requires IContextItem {}

interface IListItem requires ICommandItem {
    ITag[] Tags{ get; };
    IDetails Details{ get; };
    String Section { get; };
    String TextToSuggest { get; };
}

interface IGridProperties  {
    Windows.Foundation.Size TileSize { get; };
}

interface IListPage requires IPage, INotifyItemsChanged {
    // DevPal will be responsible for filtering the list of items, unless the
    // class implements IDynamicListPage
    String SearchText { get; };
    String PlaceholderText { get; };
    Boolean ShowDetails{ get; };
    IFilters Filters { get; };
    IGridProperties GridProperties { get; };
    Boolean HasMoreItems { get; };
    ICommandItem EmptyContent { get; };

    IListItem[] GetItems();
    void LoadMore();
}

interface IDynamicListPage requires IListPage {
    String SearchText { set; };
}

Lists are comprised of a collection of IListItems.

NOTE: The above diagram is from before Nov 2024. It doesn't properly include the relationship between ICommandItems and list items. A more up-to-date explainer of the elements of the UI can be found in "Rendering of ICommandItems in Lists and Menus"

Each ListItem has one default Command. This is the command that will be run when the user selects the item. If the IListItem has a non-null Icon, that icon will be displayed in the list. If the Icon is null, DevPal will display the Icon of the list item's Command instead.

ListItems may also have a list of MoreCommands. These are additional commands that the user can take on the item. These will be displayed to the user in the "More commands" flyout when the user has that item selected. As the user moves focus through the list to select different items, we will update the UI to show the commands for the currently selected item.

The elements of a ListPage (IListItems) and the context menu (ICommandContextItem) both share the same base type. Basically, they're both a list of things which have:

• A ICommand to invoke or navigate to.
• a Title which might replace their Command's Name,
• an Icon which might replace their Command's Icon,
• A Subtitle, which is visible on the list, and a tooltip for a context menu
• They might also have MoreCommands:
  • For a IListItem, this is the context menu.
  • For a ContextItem in the context menu, this creates a sub-context menu.

For more details on the structure of the MoreCommands property, see the ContextItems section below.

As an example, here's how the Media Controls extension adds play/pause, next & previous track context commands to the list of items:

internal sealed class MediaListItem : ListItem
{
    // Theis is an example of a ListItem that displays the currently track
    // This TogglePlayMediaCommand is the default action when the user selects the item.
    public MediaListItem() : base(new TogglePlayMediaCommand())
    {
        // These two commands make up the "More commands" flyout for the item.
        this.MoreCommands = [
            new CommandContextItem(new PrevNextTrackCommand(true)),
            new CommandContextItem(new PrevNextTrackCommand(false))
        ];

        GlobalSystemMediaTransportControlsSessionManager.RequestAsync().AsTask().ContinueWith(async (task) => {
            var manager = task.Result;
            var mediaSession = manager.GetCurrentSession();
            var properties = await this.mediaSession.TryGetMediaPropertiesAsync().AsTask();
            this.Title = properties.Title;
            // update other things too
        });

    }
}
internal sealed class TogglePlayMediaCommand : InvokableCommand
{
    public TogglePlayMediaCommand()
    {
        Name = "Play";
        Icon = new("\ue768"); //play
    }

    public ICommandResult Invoke()
    {
        _ = mediaSession.TryTogglePlayPauseAsync();
        return new ICommandResult(CommandResultKind.KeepOpen);
    }
}
// And a similar InvokableCommand for the PrevNextTrackCommand

List items may also have an optional Section provided as a string. When displaying items to the user, the Command Palette will group items with the same Section string together in the order that the Sections are first seen in the results. Many extensions will not use sections at all. If developers want to have lots of grouped results, they're free to have as many sections as they like.

• For example: An "Agenda" extension may want to have one section for each day, with each section's items containing the events for the day.
• Or a Pokedex extension may want to group results by region.

Lists may either be a list of items like a traditional ListView, or they can be a grid of items. Each of these items can be grouped into sections, which will be displayed to the user in the order they are returned by the extension. Many extensions will only have a single section, but if developers want to have lots of grouped results, they're free to have as many sections as they like.

When the GridProperties property is set to null, DevPal will display the items as a simple list, grouping them by section. When the GridProperties property is set to a non-null value, DevPal will display the items as a grid, with each item in the grid being a TileSize square. Grids are useful for showing items that are more visual in nature, like images or icons.

Each item in the list may also include an optional Details property. This allows the extension to provide additional information about the item, like a description, a preview of a file, or a link to more information. For more information on the structure of the Details property, see the Details section below.

If a list page returns a value from PlaceholderText, that text will be shown as the placeholder for the filter on the page.

If a list page returns a value from SearchText, that text will be used to initialize the search box on the page.

If the page returns ShowDetails = true, the DevPal automatically expand out the Details for list items with Details set to a non-null value. If ShowDetails = false, the DevPal will not expand out the details for list items by default, but will add a "Show details" action to the item's list of actions (if it sets Details).

• For example: in the Windows Search box, when you search for an app, you get a "details" that is pre-expanded.
• Similarly for file searches - you get a preview of the file, and metadata on those details for the file path, last modified time, etc.
• But something like the "GitHub" extension may not want to always fetch issue bodies to show their details by default. So it would set ShowDetails = false. If the user activates the automatic "Show details" action, then the github action can then fetch the body and show it.

Each item in the list may also provide TextToSuggest. This serves a similar purpose to result.QueryTextDisplay in the original PowerToys Run API. When provided, DevPal will use that text to provide a suggested search query to the user. The user can accept that suggestion with a single keypress, and DevPal will then set the SearchText on the page to that TextToSuggest. This is especially useful for dynamic lists, to easily populate the entire SearchText as the user navigates the list.

Consider the Windows Registry command. When the page is initially loaded, it displays only the top-level registry keys (HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, etc). If the user types HKC, the command will filter the results down to just HKEY_CURRENT_USER, HKEY_CLASSES_ROOT and HKEY_CURRENT_CONFIG. However, if the user at this point taps the right-arrow key, DevPall will use the TextToSuggest from the HKEY_CURRENT_USER ListItem to fill the SearchText with "HKEY_CURRENT_USER\". The extension will then be notified of this change to the search text, and can now return results nested under HKEY_CURRENT_USER\.

An example list page for the Hacker News extension:

class NewsPost {
    string Title;
    string Url;
    string CommentsUrl;
    string Poster;
    int Points;
}
class LinkCommand(NewsPost post) : Microsoft.CommandPalette.Extensions.Toolkit.InvokableCommand {
    public string Name => "Open link";
    public CommandResult Invoke() {
        Process.Start(new ProcessStartInfo(post.Url) { UseShellExecute = true });
        return CommandResult.KeepOpen;
    }
}
class CommentCommand(NewsPost post) : Microsoft.CommandPalette.Extensions.Toolkit.InvokableCommand {
    public string Name => "Open comments";
    public CommandResult Invoke() {
        Process.Start(new ProcessStartInfo(post.CommentsUrl) { UseShellExecute = true });
        return CommandResult.KeepOpen;
    }
}
class NewsListItem(NewsPost post) : Microsoft.CommandPalette.Extensions.Toolkit.ListItem {
    public string Title => post.Title;
    public string Subtitle => post.Poster;
    public IContextItem[] Commands => [
        new CommandContextItem(new LinkCommand(post)),
        new CommandContextItem(new CommentCommand(post))
    ];
    public ITag[] Tags => [ new Tag(){ Text=post.Points } ];
}
class HackerNewsPage: Microsoft.CommandPalette.Extensions.Toolkit.ListPage {
    public bool Loading => true;
    IListItem[] GetItems() {
        List<NewsItem> items = /* do some RSS feed stuff */;
        this.IsLoading = false;
        return items
                .Select((post) => new NewsListItem(post))
                .ToArray();
    }
}

Updating the list

Extension developers are able to update the list of items in real-time, by raising an PropChanged event for the Items property of the IListPage. This will cause DevPal to re-request the list of items via GetItems.

Consider for example a process list which updates in real-time. As the extension determines that the list should change, it can raise the Items property changed event.

Important

For extension developers: Best practice would be to cache your IListItems between calls. Minimizing the time it takes to respond to GetItems will make the UI feel more responsive.

Warning

We chose this API surface for a few reasons:

• IObservableCollection, which has quite a good mechanism for specifying exactly which parts of the collection changed, isn't exposed through WinRT
• IObservableVector doesn't work well across process boundaries
• In general, all the collection WinRT objects are Considered Harmful in cross-proc scenarios

But we want both static and dynamic lists to be able to update the results in real-time. Example: A process list that updates in real-time. We want to be able to add and remove items from the list as they start and stop.

Additionally, HasMoreItems / LoadMoreItems is almost exactly ISupportIncrementalLoading, but without 1: the async aspect, 2: forcing us to pull in XAML as a dependency

Here's a breakdown of how a dynamic list responds to the CmdPal. In this example, we'll use a hypothetical GitHub issue search extension, which allows the user to type a query and get a list of issues back.

1. CmdPal loads the ListPage from the extension.
2. It is a IDynamicListPage, so the command palette knows not to do any host-side filtering.
3. CmdPal reads the SearchText from the ListPage
   • it returns is:issue is:open as initial text
4. CmdPal reads the HasMoreItems from the ListPage
   • it returns true
5. CmdPal calls GetItems()
   • the extension returns the first 25 items that match the query.
6. User scrolls the page to the bottom
   • CmdPal calls GetMore on the ListPage, to let it know it should start fetching more results
7. The extension raises a ItemsChanged(40), to indicate that it now has 40 items
   • CmdPal calls GetItems, which the command returns the whole list of items
     • CmdPal does an in-place update of the existing items - ignoring the unchanged ones, and appending the new ones to the end of the list
   • The extension probably also raises a PropChanged("HasMoreItems") here, (but we'll skip that for simplicity)
8. The user types foo.
   • CmdPal calls page.SearchText("is:issue is:open foo"), to let the extension know the query has changed
9. The extension does the background query to match
10. The extension raises an ItemsChanged(5), to indicate there are 5 results
11. CmdPal calls GetItems to fetch the items.

Empty content

Developers can specify an EmptyState to customize the way the list page looks when there are no search results. This will control what's displayed to the user when both:

• IsLoading = false
• GetItems() returns null or an empty list

This property is observable like anything else, which allows developers to change the empty state contextually. For example, consider a "search winget" extension:

• If the user hasn't typed anything yet -> Title="Start typing to search winget"
• If the user has typed and no results were found -> Title="No results found", Subtitle="Your search '...' returned no packages on winget"

Filtering the list

Lists are able to specify a set of filters that the user can use to filter or pivot the list of results. These are wholly controlled by the extension. To indicate that a list page supports filtering, it should set the Filters property on the list page to a non-null value.

[uuid("ef5db50c-d26b-4aee-9343-9f98739ab411")]
interface IFilterItem {}

[uuid("0a923c7f-5b7b-431d-9898-3c8c841d02ed")]
interface ISeparatorFilterItem requires IFilterItem {}

interface IFilter requires IFilterItem {
    String Id { get; };
    String Name { get; };
    IIconInfo Icon { get; };
}

interface IFilters {
    String CurrentFilterId { get; set; };
    IFilterItem[] Filters();
}

The extension specifies the text for these filters, and gives them each a unique ID. It is also able to specify what the "default" filter is, with whatever the initial value of CurrentFilterId is.

When DevPal calls GetItems, the extension can filter the list of items based on the selected filter. If the user changes the filter in the UI, DevPal will set CurrentFilterId to the ID of the selected filter, and call GetItems again.

For example:

• the GitHub extension might provide filters for "Issues", "Pull Requests", and "Repositories". When the user selects "Issues", the GitHub extension will only return issues in the list of items.
• The Spotify extension may want to provide filters for "Playlists", "Artists", "Albums", 'Podcasts'. When the user selects "Artists", the Spotify extension will only return artists in the list of items.

Content Pages

Content pages are used for extensions that want to display richer content than just a list of commands to the user. These pages are useful for displaying things like documents and forms. You can mix and match different types of content on a single page, and even nest content within other content.

[uuid("b64def0f-8911-4afa-8f8f-042bd778d088")]
interface IContent requires INotifyPropChanged {
}

interface IFormContent requires IContent {
    String TemplateJson { get; };
    String DataJson { get; };
    String StateJson { get; };
    ICommandResult SubmitForm(String inputs, String data);
}

interface IMarkdownContent requires IContent {
    String Body { get; };
}

interface ITreeContent requires IContent, INotifyItemsChanged {
    IContent RootContent { get; };
    IContent[] GetChildren();
}

interface IContentPage requires IPage, INotifyItemsChanged {
    IContent[] GetContent();
    IDetails Details { get; };
    IContextItem[] Commands { get; };
}

Content pages may also have a Details property, which will be displayed in the same way as the details for a list item. This is useful for showing additional information about the page, like a description, a preview of a file, or a link to more information.

Similar to the List page, the Commands property is a list of commands that the user can take on the page. These are the commands that will be shown in the "More actions" flyout. Unlike the List page, the Commands property is not associated with any specific item on the page, rather, these commands are global to the page itself.

Markdown Content

This is a block of content that displays text formatted with Markdown. This is useful for showing a lot of information in a small space. Markdown provides a rich set of simple formatting options.

An example markdown page for an issue on GitHub:

class GitHubIssue {
    string Title;
    string Url;
    string Body;
    string Author;
    string[] Tags;
    string[] AssignedTo;
}
class GithubIssuePage: Microsoft.CommandPalette.Extensions.Toolkit.ContentPage {
    private readonly MarkdownContent issueBody;
    public GithubIssuePage(GithubIssue issue)
    {
        Commands = [ new CommandContextItem(new Microsoft.CommandPalette.Extensions.Toolkit.OpenUrlCommand(issue.Url)) ];
        Details = new Details(){
            Title = "",
            Body = "",
            Metadata = [
                new Microsoft.CommandPalette.Extensions.Toolkit.DetailsTags(){
                    Key = "Author",
                    Tags = [new Tag(issue.Author)]
                },
                new Microsoft.CommandPalette.Extensions.Toolkit.DetailsTags(){
                    Key = "Assigned To",
                    Tags = issue.AssignedTo.Select((user) => new Tag(user)).ToArray()
                },
                new Microsoft.CommandPalette.Extensions.Toolkit.DetailsTags(){
                    Key = "Tags",
                    Tags = issue.Tags.Select((tag) => new Tag(tag)).ToArray()
                }
            ]
        };

        issueBody = new MarkdownContent(issue.Body);
    }

    public override IContent[] GetContent() => [issueBody];
}

Note

A real GitHub extension would likely load the issue body asynchronously. In that case, the page could start a background thread to fetch the content, then raise the ItemsChanged to signal the host to retrieve the new IContent.

Form Content

Forms allow the user to input data to the extension. This is useful for actions that might require additional information from the user. For example: imagine a "Send Teams message" action. This action might require the user to input the message they want to send, and give the user a dropdown to pick the chat to send the message to.

Form content is powered by Adaptive Cards. This allows extension developers a rich set of controls to use in their forms. Each page can have as many forms as it needs. These forms will be displayed to the user as separate "cards", in the order they are returned by the extension.

The TemplateJson, DataJson, and StateJson properties should be a JSON string that represents the Adaptive Card to be displayed to the user.

When the user submits the form, the SubmitForm method will be called with the JSON payload of the form. The extension is responsible for parsing this payload and acting on it.

Other types

The following are additional type definitions that are used throughout the SDK.

ContextItems

This represents a collection of items that might appear in the MoreCommands flyout. Mostly, these are just commands and separators.

If an ICommandContextItem has MoreCommands, then when it's invoked, we'll create a sub-menu with those items in it.

Icons - IconInfo and IconData

IconData is a wrapper type for passing information about an icon to DevPal. This allows extensions to specify apps in a variety of ways, including:

• A URL to an image on the web or filesystem
• A string for an emoji or Segoe Fluent icon
• A path to an exe, dll or lnk file, to extract the icon from
• A IRandomAccessStreamReference to raw image data. This would be for extensions that want to pass us raw image data, which isn't necessarily a file which DevPal can load itself.

When specifying icons, elements can specify both the light theme and dark theme versions of an icon with IconInfo.

struct IconData {
    IconData(String iconString);
    static IconData FromStream(Windows.Storage.Streams.IRandomAccessStreamReference stream);

    String Icon { get; };
    Windows.Storage.Streams.IRandomAccessStreamReference Data { get; };
}
struct IIconInfo {
    IIconInfo(String iconString);
    IIconInfo(IconData lightIcon, IconData darkIcon);

    IconData Light { get; };
    IconData Dark { get; };
}

Terminal already has a robust arbitrary string -> icon loader that we can easily reuse for this. DevPal will only fall back to the Data member if the Icon member is null or the empty string.

As a future consideration, we may also consider supporting a base64 encoded image in the Icon member. Base64 doesn't include :, . or \, the presence of any of which would indicate the string is probably a URI, not base64 data.

OptionalColor

We declare our own Color struct to avoid depending on Windows.UI.Color and to avoid passing around unclothed uint32s.

struct Color
{
    UInt8 R;
    UInt8 G;
    UInt8 B;
    UInt8 A;
};

struct OptionalColor
{
    Boolean HasValue;
    Microsoft.CommandPalette.Extensions.Color Color;
};

We also define OptionalColor as a helper struct here. Yes, this is also just an IReference<Color>. However, IReference has some weird ownership semantics that just make it a pain for something as simple as "maybe this color doesn't have a value set".

Details

This represents additional information that can be displayed about an action or item. These can be present on both List pages and Markdown pages. For a List page, each element may have its own details. For a Markdown page, the details are global to the page.

This gif includes a mockup of what the details might look like on a list of apps. The details have a title and a hero image, which the action has set to the app's icon.

(However, the buttons in the gif for "Open", "Uninstall", etc, are not part of the Details, they are part of the "more commands" dropdown. It's a mockup)

interface ITag {
    IIconInfo Icon { get; };
    String Text { get; };
    OptionalColor Foreground { get; };
    OptionalColor Background { get; };
    String ToolTip { get; };
};

[uuid("6a6dd345-37a3-4a1e-914d-4f658a4d583d")]
interface IDetailsData {}
interface IDetailsElement {
    String Key { get; };
    IDetailsData Data { get; };
}
interface IDetails {
    IIconInfo HeroImage { get; };
    String Title { get; };
    String Body { get; };
    IDetailsElement[] Metadata { get; };
}
interface IDetailsTags requires IDetailsData {
    ITag[] Tags { get; };
}
interface IDetailsLink requires IDetailsData {
    Windows.Foundation.Uri Link { get; };
    String Text { get; };
}
interface IDetailsCommand requires IDetailsData {
    ICommand Command { get; };
}
[uuid("58070392-02bb-4e89-9beb-47ceb8c3d741")]
interface IDetailsSeparator requires IDetailsData {}

INotifyPropChanged

You may have noticed the presence of the INotifyPropChanged interface on ICommand. Typically this would be a INotifyPropertyChanged event from XAML. However, we don't want to require that developers use XAML to create extensions. So we'll provide a simple PropertyChanged event that developers can use to notify DevPal that a property has changed.

interface INotifyPropChanged {
    event Windows.Foundation.TypedEventHandler<Object, PropChangedEventArgs> PropChanged;
}
runtimeclass PropChangedEventArgs {
    String PropName { get; };
}
interface INotifyItemsChanged {
    event Windows.Foundation.TypedEventHandler<Object, ItemsChangedEventArgs> ItemsChanged;
}
runtimeclass ItemsChangedEventArgs {
    Int32 TotalItems { get; };
}

It's basically exactly the event from XAML. I've named it PropChanged to avoid prevent confusion with the XAML version.

[TODO!api-review]: can we do some trickery in the idl to have this PropertyChanged be literally the same as the XAML one? So that if there's both in a dll, they get merge into one?

ICommandProvider

This is the interface that an extension must implement to provide commands to DevPal.

interface ICommandSettings {
    IContentPage SettingsPage { get; };
};

interface IFallbackHandler {
    void UpdateQuery(String query);
};

interface IFallbackCommandItem requires ICommandItem {
    IFallbackHandler FallbackHandler{ get; };
    String DisplayTitle { get; };
};

interface ICommandProvider requires Windows.Foundation.IClosable, INotifyItemsChanged
{
    String Id { get; };
    String DisplayName { get; };
    IIconInfo Icon { get; };
    ICommandSettings Settings { get; };
    Boolean Frozen { get; };

    ICommandItem[] TopLevelCommands();
    IFallbackCommandItem[] FallbackCommands();

    ICommand GetCommand(String id);

    void InitializeWithHost(IExtensionHost host);
};

TopLevelCommands is the method that DevPal will call to get the list of actions that should be shown when the user opens DevPal. These are the commands that will allow the user to interact with the rest of your extension. They can be simple actions, or they can be pages that the user can navigate to.

TopLevelCommands returns a list of ICommandItems. These are basically just a simpler form of IListItem, which can be displayed even as a stub (as described in Caching), before the extension process is loaded.

The INotifyItemsChanged interface can be used to let DevPal know at runtime that the list of top-level command items has changed. This can be used for something like an extension that might require the user to login before accessing certain pages within the extension. Command Providers which are Frozen=true can also use this event to change their list of cached commands, since the only time an extension can raise this event is when it's already running.

Id is only necessary to set if your extension implements multiple providers in the same package identity. This is an uncommon scenario which most developers shouldn't need to worry about. If you do set Id, it should be a stable string across package versions. DevPal will use this Id for tracking settings for each provider within a package. Changing this string will result in the user's settings for your extension being lost.

Fallback commands

Providers may also specify a set of FallbackCommands³ . These are special top-level items which allow extensions to have dynamic top-level items which respond to the text the user types on the main list page.

These are implemented with a special IFallbackHandler interface. This is an object that will be informed whenever the query changes in List page hosting it. This is commonly used for commands that want to allow the user to search for something that they've typed that doesn't match any of the commands in the list.

For example, if the user types "What's the weather?":

• the Copilot action might want to be able to update their own action's Name to be "Ask Copilot 'What's the weather'?".
• The Store application may want to show a "Search the Store for 'weather'" action.
• And of course, the SpongeBot extension will want to update its name to "wHaT's tHe wEaThEr?".

This also gives the action an opportunity to know what the query was before the the page is navigated to.

Fallback commands will be shown in the top-level search results, even if the query doesn't match their Title/Subtitle, unless their Title is empty, in which case they won't be shown. This allows for:

• Fallback items that have dynamic names in response to the search query, but not restricted to the query.
• Fallback items that are hidden until the user types something

As an example, here's how a developer might implement a fallback action that changes its name to be mOcKiNgCaSe.

public class SpongebotPage : Microsoft.CommandPalette.Extensions.Toolkit.MarkdownPage, IFallbackHandler
{
    // Name, Icon, IPropertyChanged: all those are defined in the MarkdownPage base class
    public SpongebotPage()
    {
        this.Name = "";
        this.Icon = new("https://imgflip.com/s/meme/Mocking-Spongebob.jpg");
    }
    public void IFallbackHandler.UpdateQuery(string query) {
        if (string.IsNullOrEmpty(query)) {
            this.Name = "";
        } else {
            this.Name = ConvertToAlternatingCase(query);
        }
        return Task.CompletedTask.AsAsyncCommand();
    }
    static string ConvertToAlternatingCase(string input) {
        StringBuilder sb = new StringBuilder();
        for (var i = 0; i < input.Length; i++)
        {
            sb.Append(i % 2 == 0 ? char.ToUpper(input[i]) : char.ToLower(input[i]));
        }
        return sb.ToString();
    }
    public override string Body() {
        var t = _GenerateMeme(this.Name); // call out to imgflip APIs to generate the meme
        t.ConfigureAwait(false);
        return t.Result;
    }
}
internal sealed class SpongebotCommandsProvider : CommandProvider
{
    public ICommandItem[] TopLevelCommands() => [];
    public IFallbackCommandItem[] FallbackCommands()
    {
        var spongebotPage = new SpongebotPage();
        var listItem = new FallbackCommandItem(spongebotPage);
        // ^ The FallbackCommandItem ctor will automatically set its FallbackHandler to the
        // Command passed in, if the command implements IFallbackHandler
        return [ listItem ];
    }
}

Microsoft.CommandPalette.Extensions.Toolkit.FallbackCommandItem in the SDK helpers will automatically set the FallbackHandler property on the IFallbackCommandItem to the Command it's initialized with, if that command implements IFallbackHandler. This allows the action to directly update itself in response to the query. You may also specify a different IFallbackHandler, if needed.

We'll include specific affordances within the DevPal settings to allow the user to configure which top-level fallbacks are enabled, and in what order. This will give the user greater control over the apps that can respond to queries that don't match any of the commands in the list.

If an extension's own list page wants to implement a similar fallback mechanism

• it's free to use IDynamicListPage to listen for changes to the query and have its own ListItem it updates manually.

Important

If your extension has top-level FallbackCommandItems, then DevPal will treat your ICommandProvider as fresh, never frozen, regardless of the value of Frozen you set.

The DisplayTitle property allows the user to see a descriptive name for the command, without the context of what's been typed. This property is what devpal will show to the user in the settings for your application.

For example: a "Search the Web" command would just set its DisplayTitle to
"Search the web", but the UpdateQuery method might change the title to "Search the web for {searchText}"

GetCommand

GetCommand is a method that DevPal can use to shortcut loading a command, for frozen command providers. If a top-level command is assigned an Id by the extension author, DevPal will use GetCommand as a first-resort to instantiate that command.

For command providers that have multiple top-level commands, this can be a helpful short-circuit. The extension won't need to construct instances of all the IListItems for all its top-level commands. Instead, the extension can just instantiate the requested one.

Settings

Extensions may also want to provide settings to the user. They can do this by implementing the ICommandSettings interface. This interface has a single property, SettingsPage, which is a FormPage. (We're adding the layer of abstraction here to allow for further additions to ICommandSettings in the future.)

In the DevPal settings page, we can then link to each extension's given settings page. As these pages are just FormPages, they can be as simple or as complex as the extension developer wants, and they're rendered and interacted with in the same way.

We're then additionally going to provide a collection of settings helpers for developers in the helper SDK. This should allow developers to quickly work to add settings, without mucking around in building the form JSON themselves.

Helper SDK Classes

As a part of the Microsoft.CommandPalette.Extensions namespace, we'll provide a set of default implementations and helper classes that developers can use to make authoring extensions easier.

Default implementations

We'll provide default implementations for the following interfaces:

• IInvokableCommand
• IListItem
• ICommandContextItem
• ICommandResult
• IGoToPageArgs
• IChangeQueryArgs
• ISeparatorContextItem
• ISeparatorFilterItem
• IFilter
• IListPage
• IMarkdownPage
• IFormPage
• IDetailsTags
• IDetailsLink
• IDetailsSeparator

This will allow developers to quickly create extensions without having to worry about implementing every part of the interface. You can see that reference implementation in extensionsdk\Microsoft.CommandPalette.Extensions.Toolkit.Lib\DefaultClasses.cs.

In addition to the default implementations we provide for the interfaces above, we should provide a set of helper classes that make it easier for developers to write extensions.

For example, we should have something like:

class OpenUrlCommand(string targetUrl, CommandResult result) : Microsoft.CommandPalette.Extensions.Toolkit.InvokableCommand {
    public OpenUrlCommand()
    {
        Name = "Open";
        Icon = new("\uE8A7"); // OpenInNewWindow
    }
    public CommandResult Invoke() {
        Process.Start(new ProcessStartInfo(targetUrl) { UseShellExecute = true });
        return result;
    }
}

Then, the entire Hacker News example from above becomes the following. Note that no longer do we need to add additional classes for the actions. We just use the helper:

class NewsListItem : Microsoft.CommandPalette.Extensions.Toolkit.ListItem {
    private NewsPost _post;
    public NewsListItem(NewsPost post)
    {
        _post = post;
        Title = post.Title;
        Subtitle = post.Url;
    }
    public IContextItem[] Commands => [
        new CommandContextItem(new OpenUrlCommand(post.Url, CommandResult.KeepOpen)),
        new CommandContextItem(new OpenUrlCommand(post.CommentsUrl, CommandResult.KeepOpen){
            Name = "Open comments",
            Icon = "\uE8F2" // ChatBubbles
        })
    ];
    public ITag[] Tags => [ new Tag(){ Text=post.Poster, new Tag(){ Text=post.Points } } ];
}
class HackerNewsPage: Microsoft.CommandPalette.Extensions.Toolkit.ListPage {
    public HackerNewsPage()
    {
        Loading = true;
    }
    IListItem[] GetItems(String query) {
        List<NewsItem> items = /* do some RSS feed stuff */;
        this.IsLoading = false;
        return items
                .Select((post) => new NewsListItem(post))
                .ToArray();
    }
}

Using the Clipboard

Typically, developers would be expected to use the Clipboard class from the Windows.ApplicationModel.DataTransfer namespace. However, this class comes with restrictions around the ability to call it from a background thread. Since extensions are always running in the background, this presents persistent difficulties.

We'll provide a helper class that allows developers to easily use the clipboard in their extensions.

Settings helpers

The DevPal helpers library also includes a set of helpers for building settings pages for you. This lets you define a Settings object as a collection of properties, controlled by how they're presented in the UI. The helpers library will then handle the process of turning those properties into a IForm for you.

As a complete example: Here's a sample of an app which defines a pair of settings (onOff and whatever) in their MyAppSettings class. MyAppSettings can be responsible for loading or saving the settings however the developer best sees fit. They then pass an instance of that object to the MySettingsPage class they define. In MySettingsPage.Forms, the developer doesn't need to do any work to build up the Adaptive Card JSON at all. Just call Settings.ToForms(). The generated form will call back to the extension's code in SettingsChanged when the user submits the IForm. At that point, the extension author is again free to do whatever they'd like - store the json wherever they want, use the updated values, whatever.

class MyAppSettings {
    private readonly Helpers.Settings _settings = new();
    public Helpers.Settings Settings => _settings;

    public MyAppSettings() {
        // Define the structure of your settings here.
        var onOffSetting = new Helpers.ToggleSetting("onOff", "Enable feature", "This feature will do something cool", true);
        var textSetting = new Helpers.TextSetting("whatever", "Text setting", "This is a text setting", "Default text");
        _settings.Add(onOffSetting);
        _settings.Add(onOffSetting);
    }
    public void LoadSavedData()
    {
        // Possibly, load the settings from a file or something
        var persistedData = /* load the settings from file */;
        _settings.LoadState(persistedData);
    }
    public void SaveSettings()
    {
        /* You can save the settings to the file here */
        var mySettingsFilePath = /* whatever */;
        string mySettingsJson = mySettings.Settings.GetState();
        // Or you could raise a event to indicate to the rest of your app that settings have changed.
    }
}

class MySettingsPage : Microsoft.CommandPalette.Extensions.Toolkit.FormPage
{
    private readonly MyAppSettings mySettings;
    public MySettingsPage(MyAppSettings s) {
        mySettings = s;
        mySettings.Settings.SettingsChanged += SettingsChanged;
    }
    public override IForm[] Forms() {
        // If you haven't already:
        mySettings.Settings.LoadSavedData();
        return mySettings.Settings.ToForms();
    }

    private void SettingsChanged(object sender, Settings args)
    {
        /* Do something with the new settings here */
        var onOff = _settings.GetSetting<bool>("onOff");
        ExtensionHost.LogMessage(new LogMessage() { Message = $"MySettingsPage: Changed the value of onOff to {onOff}" });

        // Possibly even:
        mySettings.SaveSettings();
    }
}

// elsewhere in your app:

MyAppSettings instance = /* Up to you how you want to pass this around.
                            Singleton, dependency injection, whatever. */
var onOff = instance.Settings.Get("onOff");

Advanced scenarios

Status messages

Extensions will want to be able to communicate feedback to the user, based on what's going on inside the extension.

Consider a winget extension that allows the user to search for and install packages. When the user starts an install, the extension should be able to show a progress bar for the install, and then show a success or error message to the user, depending on the result.

To do so, extensions can make use of the IExtensionHost interface. This is an object which extensions shouldn't implement themselves. Rather, this is implemented by the host app itself. On this class is the ShowStatus & HideStatus methods.

Calling ShowStatus will display a given message to the user in the status area of the UI. The extension can provide an info/success/warning/error state to colorize the message. The extension can also provide progress info in the message.

When the extension wants to hide the message, they can call HideStatus, passing the same message object to the method. The host app will keep a log of all status's written to it, so a user can alway view old messages once they've been hidden. The message also conforms to INotifyPropChanged, so extensions can modify an existing message if they'd like to. This is recommended, rather than writing lots of individual updates as separate messages.

enum MessageState
{
    Info = 0,
    Success,
    Warning,
    Error,
};

enum StatusContext
{
    Page,
    Extension
};

interface IProgressState requires INotifyPropChanged
{
    Boolean IsIndeterminate { get; };
    UInt32 ProgressPercent { get; };
};

interface IStatusMessage requires INotifyPropChanged
{
    MessageState State { get; };
    IProgressState Progress { get; };
    String Message { get; };
    // TODO! Icon maybe? Work with design on this
};

interface ILogMessage
{
    MessageState State { get; };
    String Message { get; };
};

interface IExtensionHost
{
    Windows.Foundation.IAsyncAction ShowStatus(IStatusMessage message, StatusContext context);
    Windows.Foundation.IAsyncAction HideStatus(IStatusMessage message);

    Windows.Foundation.IAsyncAction LogMessage(ILogMessage message);
};

There's also a LogMessage method provided by the IExtensionHost interface. This is useful for apps that want to write to the debug log of the host app itself. These are for messages that wouldn't otherwise be visible to the user, but may be helpful for debugging purposes.

IExtensionHost is implemented by the hosting app itself. It is passed to a command provider on startup, when the host app first connects to the extension. For apps which use the helpers library, this will be managed for them. Consumers of the helpers lib can simply call Helpers.ExtensionHost.Host to get the instance from the host app.

[TODO!]: I'm marking these methods async right now, to force extension authors to remember that these are x-proc calls, and should be treated asynchronously. Should the other properties be async too?

Rendering of ICommandItems in Lists and Menus

When displaying a list item:

• The icon is ICommandItem.Icon ?? ICommandItem.Command.Icon
• The title is ICommandItem.Title ?? ICommandItem.Command.Name
• The Subtitle is ICommandItem.Subtitle
• The text displayed for the default action (↲) is ICommandItem.Command.Name

When displaying a command context menu item:

• The icon is ICommandItem.Icon ?? ICommandItem.Command.Icon
• The text is ICommandItem.Title ?? ICommandItem.Command.Name
• The tooltip is ICommandItem.Subtitle

When displaying a IListItem's default Command as a context item, we'll make a new

ICommandContextItem(){
    Command = ICommandItem.Command,
    MoreCommands = null,
    Icon = Command.Icon, // use icon from command, not list item
    Title = Command.Name, // Use command's name, not list item
    Subtitle = IListItem.Title, // Use the title of the list item as the tooltip on the context menu
    IsCritical = false,
}

If a ICommandItem in a context menu has MoreCommands, then activating it will open a submenu with those items. If a ICommandItem in a context menu has MoreCommands AND a non-null Command, then activating it will open a submenu with the Command first (following the same rules above for building a context item from a default Command), followed by the items in MoreCommands.

When displaying a page:

• The title will be IPage.Title ?? ICommand.Name
• The icon will be ICommand.Icon

Class diagram

This is a diagram attempting to show the relationships between the various types we've defined for the SDK. Some elements are omitted for clarity. (Notably, IconData and IPropChanged, which are used in many places.)

The notes on the arrows help indicate the multiplicity of the relationship.

• "*" means 0 or more (for arrays)
• "?" means 0 or 1 (for optional/nullable properties)
• "1" means exactly 1 (for required properties)

classDiagram
    class ICommand {
        String Name
        String Id
        IIconInfo Icon
    }
    IPage --|> ICommand
    class IPage  {
        String Title
        Boolean IsLoading
    }

    IInvokableCommand --|> ICommand
    class IInvokableCommand  {
        ICommandResult Invoke(object context)
    }

    class IForm {
        String TemplateJson()
        String DataJson()
        String StateJson()
        ICommandResult SubmitForm(String payload)
    }
    IFormPage --|> IPage
    class IFormPage  {
        IForm[] Forms()
    }
    IForm "*" *-- IFormPage

    IMarkdownPage --|> IPage
    class IMarkdownPage  {
        String[] Bodies()
        IDetails Details()
        IContextItem[] Commands
    }
    %% IMarkdownPage *-- IDetails
    IContextItem "*" *-- IMarkdownPage
    IDetails "?" *-- IMarkdownPage
    %%%%%%%%%

    class IFilterItem

    ISeparatorFilterItem --|> IFilterItem
    class ISeparatorFilterItem

    IFilter --|> IFilterItem
    class IFilter  {
        String Id
        String Name
        IIconInfo Icon
    }

    class IFilters {
        String CurrentFilterId
        IFilterItem[] AvailableFilters()
    }
    IFilterItem "*" *-- IFilters

    class IFallbackHandler {
        void UpdateQuery(String query)
    }


    %% IListItem --|> INotifyPropChanged
    class IListItem  {
        IIconInfo Icon
        String Title
        String Subtitle
        ICommand Command
        IContextItem[] MoreCommands
        ITag[] Tags
        IDetails Details
        IFallbackHandler FallbackHandler
        String Section
        String TextToSuggest
    }
    IContextItem "*" *-- IListItem
    IDetails "?" *-- IListItem
    ICommand "?" *-- IListItem
    ITag "*" *-- IListItem
    IFallbackHandler "?" *-- IListItem

    class IGridProperties  {
        Windows.Foundation.Size TileSize
    }

    IListPage --|> IPage
    class IListPage  {
        String SearchText
        String PlaceholderText
        Boolean ShowDetails
        IFilters Filters
        IGridProperties GridProperties
        Boolean HasMore

        IListItem[] GetItems()
        void LoadMore()
    }
    IListItem "*" *-- IListPage
    IFilters "*" *-- IListPage
    IGridProperties "?" *-- IListPage

    IDynamicListPage --|> IListPage
    class IDynamicListPage  {
        +String SearchText set;
    }

    class IDetails {
        IIconInfo HeroImage
        String Title
        String Body
        IDetailsElement[] Metadata
    }

    class ITag {
        IIconInfo Icon
        String Text
        Color Color
        String ToolTip
        ICommand Command
    }
    ICommand "?" *-- ITag

    %%%%%%
    class IContextItem

    ISeparatorContextItem --|> IContextItem
    class ISeparatorContextItem
    ICommandContextItem --|> IContextItem
    class ICommandContextItem  {
        ICommand Command
        String Tooltip
        Boolean IsCritical
    }
    ICommand "?" *-- ICommandContextItem



    class ICommandProvider {
        String DisplayName
        IIconInfo Icon
        Boolean Frozen

        ICommandItem[] TopLevelCommands()
        IFallbackCommandItem[] FallbackCommands()
        IListItem GetCommand(String id)
    }
    ICommandItem "*" *-- ICommandProvider
    IFallbackCommandItem "*" *-- ICommandProvider

Future considerations

Arbitrary parameters and arguments

Something we'll want to consider soon is how to allow for arbitrary parameters to be passed to commands. This allows for commands to require additional info from the user before they are run. In its simplest form, this is a lightweight way to have an action accept form data inline with the query. But this also allows for highly complex action chaining.

I had originally started to spec this out as:

interface IInvokableCommandWithParameters requires ICommand {
    ActionParameters Parameters { get; };
    CommandResult InvokeWithArgs(ActionArguments args);
}

And ActionParameters would be a set of { type, name, required} structs, which would specify the parameters that the action needs. Simple types would be string, file, file[], enum (with possible values), etc.

But that may not be complex enough. We recently learned about Action Framework and some of their plans there - that may be a good fit for this. My raw notes follow - these are not part of the current SDK spec.

Note

A thought: what if a action returns a CommandResult.Entity, then that takes devpal back home, but leaves the entity in the query box. This would allow for a Quicksilver-like "thing, do" flow. That command would prepopulate the parameters. So we would then filter top-level commands based on things that can accept the entity in the search box.

For example: The user uses the "Search for file" list page. They find the file they're looking for. That file's ListItem has a context item "With {filename}..." that then returns a CommandResult.Entity with the file entity. The user is taken back to the main page, and a file picker badge (with that filename) is at the top of the search box. In that state, the only commands now shown are ones that can accept a File entity. This could be things like the "Remove background" action (from REDACTED), the "Open with" action, the "Send to Teams chat" (which would then ask for another entity). If they did the "Remove Background" one, that could then return another entity.

We'd need to solve for the REDACTED case specifically, cause I bet they want to stay in the REDACTED action page, rather than the main one.

We'd also probably want the REDACTED one to be able to accept arbitrary entities... like, they probably want a + button that lets you add... any kind of entity to their page, rather than explicitly ask for a list of args.

However, we do not have enough visibility on how action framework actually works, consumer-wise, to be able to specify more. As absolutely fun as chaining actions together sounds, I've decided to leave this out of the official v1 spec. We can ship a viable v0.1 of DevPal without it, and add it in post.

URI activation

We should also consider how to allow for URI activation. This would allow for extensions to be activated by a URI, rather than by the user typing a query. Consider another app that may want to boot into a particular action page in DevPal.

I'd imagine that we'd surface some URI scheme that would look like:

devpal://commands/{{extension_id}}/{{page_id}}?param=arg

that could be used to activate a particular page in an app. Apps would need to be able to specify their own extension ID (all my homies dislike working with PFNs). DevPal would also need to be able to control which schemes are active, and if they're active, which apps can call through to it (if that's knowable).

This remains under-specified for now. It's a cool feature for the future, but one that's not needed for v1.

Custom "empty list" messages

We should consider how to allow for extensions to specify a custom element to be shown to the user when the page stops loading and the list of elements filtered is empty. Is that just a Details object? A markdown body?

Footnotes

Generating the .idl

The .idl for this SDK can be generated directly from this file. To do so, run the following command:

.\generate-interface.ps1 > .\Microsoft.DevPalette.Extensions.idl

(After a pip3 install mistletoe)

Or, to generate straight to the place I'm consuming it from:

.\doc\initial-sdk-spec\generate-interface.ps1 > .\extensionsdk\Microsoft.CommandPalette.Extensions\Microsoft.CommandPalette.Extensions.Toolkit.idl

Adding APIs

Almost all of the SDK defined here is in terms of interfaces. Unfortunately, this prevents us from being able to use [contract] attributes to add to the interfaces. We'll instead need to rely on the tried-and-true method of adding a IFoo2 when we want to add methods to IFoo.

---

1. You know, I bet we could make this a frozen provider too. I be if we added INotifyItemsChanged to ICommandProvider, then when the "add bookmark" command is activated, we could raise provider.ItemsChanged, and have the palette re-cache the results of TopLevelItems. ↩︎

2. In this example, as in other places, I've referenced a Microsoft.DevPal.Extensions.InvokableCommand class, as the base for that action. Our SDK will include partial class implementations for interfaces like ICommand, IListPage, etc. These partial implementations will provide default implementations for common properties and methods, like PropertyChanged events, and Icon properties. Developers can choose to use these partial implementations, or implement the interfaces themselves. See the Default implementations section for more information. ↩︎

3. It is a little weird that IListItem has a FallbackHandler property, rather than just allowing ICommands to implement IFallbackHandler. This is unfortunately due to a quirk in Metadata-based marshalling (MBM) in WinRT. MBM doesn't clearly expose when a runtimeclass implements multiple non-derived interfaces. Something that implements IMarkdownPage and IFallbackHandler can't be trivially casted from one type to the other. However, by making the FallbackHandler a property of the ListItem itself, then the extension itself can cast between the types, without the need for MBM. Thanks to Mano for helping me figure this one out. ↩︎