Skip to content

Commit 36237f1

Browse files
niels9001Copilot
niels9001
and
Copilot
authored
Command Palette doc updates (#6622)
* Init * Push * Push * Update toc.yml * Push * Push * Fix publishing * Add CmdPal extension settings how-to and document markdown in Details.Body - Add new how-to guide: adding-extension-settings.md with examples for ToggleSetting, TextSetting, ChoiceSetSetting, reading values, and reacting to changes - Update IDetails.Body and Details.Body descriptions to document that the content is rendered as markdown - Add TOC entry for the new extension settings guide Co-authored-by: Copilot <[email protected]> * Push --------- Co-authored-by: Copilot <[email protected]>
1 parent 2e67afd commit 36237f1

16 files changed

Lines changed: 1993 additions & 1711 deletions

‎hub/powertoys/command-palette/adding-extension-settings.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: Add settings to your Command Palette extension
3+
description: Learn how to add a settings page to your Command Palette extension so users can configure its behavior with toggles, text fields, and choice sets.
4+
ms.date: 04/12/2026
5+
ms.topic: how-to
6+
no-loc: [PowerToys, Windows, Insider]
7+
# Customer intent: As a Windows developer, I want to learn how to add configurable settings to my Command Palette extension, so that users can customize the extension's behavior.
8+
---
9+
10+
# Add settings to your extension
11+
12+
**Previous**: [Adding Dock support](adding-dock-support.md)
13+
14+
Extensions can provide their own settings page, letting users configure extension behavior directly within the Command Palette. The settings helpers in the toolkit make it easy to define toggles, text fields, and choice sets without writing UI code.
15+
16+
## How extension settings work
17+
18+
The toolkit provides a [Settings](./microsoft-commandpalette-extensions-toolkit/settings.md) class that manages a collection of typed settings. You define the settings you need, convert them to content for display, and react to changes through an event. Command Palette renders the settings form automatically.
19+
20+
## Add a settings page
21+
22+
1. In the `Pages` directory, add a new class
23+
1. Name the class `MySettingsPage.cs`
24+
1. Update the file to:
25+
26+
```csharp
27+
using Microsoft.CommandPalette.Extensions;
28+
using Microsoft.CommandPalette.Extensions.Toolkit;
29+
30+
internal sealed partial class MySettingsPage : ContentPage
31+
{
32+
private readonly Settings _settings = new();
33+
34+
public MySettingsPage()
35+
{
36+
Name = "Settings";
37+
Icon = new IconInfo("\uE713"); // Settings gear icon
38+
Title = "Extension Settings";
39+
40+
_settings.Add(new ToggleSetting("notifications", true)
41+
{
42+
Label = "Enable notifications",
43+
Description = "Show a notification when a task completes",
44+
});
45+
_settings.Add(new TextSetting("defaultQuery", string.Empty)
46+
{
47+
Label = "Default search query",
48+
Description = "Pre-fill the search box with this text",
49+
});
50+
51+
_settings.SettingsChanged += OnSettingsChanged;
52+
}
53+
54+
public override IContent[] GetContent()
55+
{
56+
return _settings.ToContent();
57+
}
58+
59+
private void OnSettingsChanged(object sender, Settings args)
60+
{
61+
// Read updated values
62+
var notificationsEnabled = _settings.GetSetting<bool>("notifications");
63+
var defaultQuery = _settings.GetSetting<string>("defaultQuery");
64+
}
65+
}
66+
```
67+
68+
## Available setting types
69+
70+
| Type | Description | Default value type |
71+
| :--- | :--- | :--- |
72+
| [ToggleSetting](./microsoft-commandpalette-extensions-toolkit/togglesetting.md) | A checkbox / toggle switch | `bool` |
73+
| [TextSetting](./microsoft-commandpalette-extensions-toolkit/textsetting.md) | A single-line text input | `string` |
74+
| [ChoiceSetSetting](./microsoft-commandpalette-extensions-toolkit/choicesetsetting.md) | A drop-down list of choices | `string` (selected value) |
75+
76+
### Choice set example
77+
78+
```csharp
79+
var choices = new List<ChoiceSetSetting.Choice>
80+
{
81+
new("Small", "sm"),
82+
new("Medium", "md"),
83+
new("Large", "lg"),
84+
};
85+
86+
_settings.Add(new ChoiceSetSetting("size", choices)
87+
{
88+
Label = "Result size",
89+
Description = "Choose how results are displayed",
90+
});
91+
```
92+
93+
## Read setting values
94+
95+
Use `GetSetting<T>` to read a setting value by key at any time:
96+
97+
```csharp
98+
var isEnabled = _settings.GetSetting<bool>("notifications");
99+
```
100+
101+
Use `TryGetSetting<T>` when the setting might not exist:
102+
103+
```csharp
104+
if (_settings.TryGetSetting<string>("defaultQuery", out var query))
105+
{
106+
// use query
107+
}
108+
```
109+
110+
## React to changes
111+
112+
Subscribe to the `SettingsChanged` event to be notified when the user modifies any setting:
113+
114+
```csharp
115+
_settings.SettingsChanged += (sender, args) =>
116+
{
117+
// Refresh your extension state based on the new settings
118+
};
119+
```
120+
121+
## Wire the settings page to your extension
122+
123+
To make the settings page accessible from the Command Palette extension manager, expose it from your `ListPage` as a list item, or wire it through your command provider.
124+
125+
```csharp
126+
new ListItem(new MySettingsPage())
127+
{
128+
Title = "Settings",
129+
Subtitle = "Configure extension options",
130+
Icon = new IconInfo("\uE713"),
131+
}
132+
```
133+
134+
## Related content
135+
136+
- [Settings class reference](./microsoft-commandpalette-extensions-toolkit/settings.md)
137+
- [ICommandSettings interface](./microsoft-commandpalette-extensions/icommandsettings.md)
138+
- [Extension samples](samples.md)

‎hub/powertoys/command-palette/creating-an-extension.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ no-loc: [PowerToys, Windows, Insider]
88
# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
99
---
1010

11-
# How to create Command Palette extensions
11+
# Getting started with Command Palette extensions
1212

1313
Learn how to build custom extensions for the Command Palette using C#. This comprehensive guide covers everything from project setup to deployment, helping you enhance this powerful productivity tool for Windows.
1414

@@ -25,9 +25,7 @@ The Command Palette extension system allows developers to create custom commands
2525

2626
**Prerequisites:**
2727

28-
- Visual Studio with the following workloads
29-
- C# development workload
30-
- WinUI application development workload
28+
- [Set up your Windows development environment](/windows/apps/get-started/start-here) — install Visual Studio with the required workloads for WinUI and the Windows App SDK
3129
- Windows 11 with PowerToys installed
3230
- Enable [Developer mode on Windows](/windows/advanced-settings/developer-mode)
3331
- Basic knowledge of C# programming

‎hub/powertoys/command-palette/extensibility-overview.md‎

Lines changed: 46 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,21 @@
11
---
2-
title: Command Palette Extensibility
3-
description: The Command Palette provides a full extension model, allowing you to create custom experiences for the palette. Learn how to create an extension and publish it.
4-
ms.date: 2/28/2025
2+
title: How Command Palette extensions work
3+
description: Understand the Command Palette extension model, including how extensions register, communicate, and provide commands and pages.
4+
ms.date: 04/10/2026
55
ms.topic: concept-article
66
no-loc: [PowerToys, Windows, Insider]
7-
# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
7+
# Customer intent: As a Windows developer, I want to understand how the Command Palette extension model works.
88
---
99

10-
# Extensibility overview
10+
# How Command Palette extensions work
1111

12-
The Command Palette provides a full extension model, allowing developers to create their own experiences for the palette.
12+
Command Palette extensions are standalone .NET applications that communicate with Command Palette through a WinRT API. Each extension runs in its own process and registers with Command Palette through its app manifest, making extensions isolated, secure, and easy to deploy.
1313

14-
The fastest way to get started writing extensions is from the Command Palette itself. Just run the "Create a new extension" command, fill out the fields to populate the template project, and you should be ready to start.
14+
This page explains the core concepts behind the extension model — how extensions are discovered, how they provide commands and pages, and what kinds of experiences you can build.
1515

16-
For more detailed instructions, you can follow these pages:
16+
## How Command Palette discovers installed extensions
1717

18-
* [Creating an extension](../command-palette/creating-an-extension.md)
19-
* [Adding commands](../command-palette/adding-commands.md)
20-
* [Update a list of commands](../command-palette/update-a-list-of-commands.md)
21-
* [Add top-level commands to your extension](../command-palette/add-top-level-commands-to-your-extension.md)
22-
* [Command results](../command-palette/command-results.md)
23-
* [Display markdown content](../command-palette/using-markdown-content.md)
24-
* [Get user input with forms](../command-palette/using-form-pages.md)
25-
* [Adding Dock support](../command-palette/adding-dock-support.md)
26-
<!-- * [Handle the search text](../command-palette/dynamic-lists.md) -->
27-
<!-- * [Advanced: Adding an extension to your package](../command-palette/adding-an-extension-to-your-package.md) -->
28-
29-
30-
## Extension details
31-
32-
Command Palette defines a WinRT API ([Microsoft.CommandPalette.Extensions](./microsoft-commandpalette-extensions/microsoft-commandpalette-extensions.md)), which is how extensions can communicate with Command Palette.
33-
34-
Command Palette will use the Package Catalog to find apps that list themselves as an `windows.appExtension` for `com.microsoft.commandpalette`.
35-
36-
### Registering your extension
37-
38-
Extensions can register themselves with the Command Palette using their `.appxmanifest`. As an example:
18+
Command Palette uses the Windows Package Catalog to find installed apps that declare themselves as Command Palette extensions. Extensions register through their `.appxmanifest` by declaring a `windows.appExtension` with the name `com.microsoft.commandpalette`:
3919

4020
```xml
4121
<Extensions>
@@ -67,19 +47,47 @@ Extensions can register themselves with the Command Palette using their `.appxma
6747
</Extensions>
6848
```
6949

70-
In this manifest, we're using an out-of-process COM server to act as the communication layer between your app and Command Palette. **Don't worry about this**! The template project will take care of creating a COM server for you, starting it, and marshalling your objects to Command Palette.
50+
Extensions use an out-of-process COM server as the communication layer between your app and Command Palette. **Don't worry about the details** — the template project handles creating the COM server, starting it, and marshalling your objects to Command Palette automatically.
51+
52+
### Important notes about the manifest
53+
54+
- The `AppExtension` must set `Name` to `com.microsoft.commandpalette`. This is the unique identifier that Command Palette uses to discover extensions.
55+
- The `ComServer` element registers a COM class GUID that Command Palette uses to instantiate your extension. Make sure this CLSID is unique and matches across all three locations in the manifest.
56+
- The `CmdPalProvider` element in the `Properties` section specifies the CLSID of the COM class that Command Palette will instantiate. Currently, only `Commands` is supported.
57+
58+
## The extension API
7159

72-
### Important notes
60+
Command Palette defines a WinRT API ([Microsoft.CommandPalette.Extensions](./microsoft-commandpalette-extensions/microsoft-commandpalette-extensions.md)) that extensions use to communicate with Command Palette. A companion toolkit library ([Microsoft.CommandPalette.Extensions.Toolkit](./microsoft-commandpalette-extensions-toolkit/microsoft-commandpalette-extensions-toolkit.md)) provides base classes and helpers that simplify common patterns.
7361

74-
Some notable elements about the manifest example:
62+
Every extension implements the `IExtension` interface, which provides a `GetProvider` method that returns your `ICommandProvider`. The command provider is where you define the commands and pages that your extension offers.
7563

76-
- The application must specify a `Extensions.uap3Extension.AppExtension` with the Name set to `com.microsoft.commandpalette`. This is the unique identifier which Command Palette uses to find it's extensions.
77-
- 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.
78-
- Make sure that this CLSID is unique, and matches the one in your application. If you change one, you need to change all three.
79-
- In the `Properties` of your `AppExtension`, you must specify a `CmdPalProvider` element. This is where you specify the CLSID of the COM class that Command Palette will instantiate to interact with your extension.
80-
- Currently, only `Commands` is supported.
64+
## Commands and pages
65+
66+
Extensions can provide several types of content:
67+
68+
- **Top-level commands** — Commands that appear on the Command Palette home page, making them immediately accessible to users.
69+
- **Fallback commands** — Commands that are triggered when no other results match a user's query, useful for search-based or catch-all functionality.
70+
- **Context menu items** — Additional actions that appear in the right-click context menu of other commands.
71+
72+
Each command can navigate to a **page** that displays content. Command Palette supports the following page types:
73+
74+
| Page type | Description |
75+
| :--- | :--- |
76+
| **List pages** | Display a searchable list of selectable items. |
77+
| **Detail pages** | Show rich content with sections, tags, and links. |
78+
| **Form pages** | Present user input fields for interactive workflows. |
79+
| **Markdown pages** | Render formatted markdown content. |
80+
| **Grid pages** | Display items in a gallery or grid layout. |
81+
82+
Extensions can also provide their own settings pages for per-extension configuration, and support pinning commands to the [Dock](dock.md).
83+
84+
## Get started
85+
86+
Ready to build your first extension? Head to [Getting started](creating-an-extension.md) to set up your project and create your first command.
8187

8288
## Related content
8389

84-
- [PowerToys Command Palette utility](overview.md)
90+
- [Getting started](creating-an-extension.md)
8591
- [Extension samples](samples.md)
92+
- [API reference](sdk-namespaces.md)
93+
- [PowerToys Command Palette utility](overview.md)

‎hub/powertoys/command-palette/extension-development.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Command Palette extension development
3+
description: Build extensions for PowerToys Command Palette and bring your tools, workflows, and ideas to millions of Windows power users.
4+
ms.date: 04/10/2026
5+
ms.topic: concept-article
6+
no-loc: [PowerToys, Windows, Insider]
7+
# Customer intent: Understand the value proposition of building Command Palette extensions and find where to get started.
8+
---
9+
10+
# Welcome to Command Palette extension development
11+
12+
Command Palette is the go-to launcher for Windows power users — a fast, extensible interface for launching apps, running commands, and getting things done. With the Command Palette extension platform, you can build tools that plug directly into that workflow — putting your ideas right where people are already working.
13+
14+
:::image type="content" source="../images/gallery.png" alt-text="A screenshot of the Command Palette Extension Gallery showing a list of available extensions.":::
15+
16+
Whether you want to build something for yourself, share it with the community, or distribute it to your team, the platform is designed to get you from idea to working extension quickly.
17+
18+
## Why build for Command Palette?
19+
20+
- **Reach users where they are.** Your extension shows up right in the Command Palette — no separate app to open, no context switching.
21+
- **Built on .NET.** Use C# and the tools you already know. Leverage the full NuGet ecosystem to build what you imagine.
22+
- **Rich UI without the overhead.** Use built-in page types — lists, forms, markdown, detail views, and grids — to create polished experiences without designing UI from scratch.
23+
- **Scaffold and go.** Run the `Create extension` command directly from Command Palette to generate a ready-to-build project in seconds.
24+
- **Share with the community.** Publish your extension to the built-in Gallery and make it available to every Command Palette user.
25+
26+
## How to build and publish an extension
27+
28+
Here's the high-level process for creating and sharing a Command Palette extension:
29+
30+
1. **[Understand how it works](extensibility-overview.md)** — Learn how the extension model works, including page types, commands, and how extensions communicate with Command Palette.
31+
2. **[Build your extension](creating-an-extension.md)** — Set up your project, add commands and pages, and test your extension locally.
32+
3. **[Publish your extension](publish-extension.md)** — Distribute your extension through the Microsoft Store, WinGet, or your own hosting.
33+
34+
## What's in the docs
35+
36+
- **[How it works](extensibility-overview.md)** — Understand the extension architecture, page types, and core concepts.
37+
- **[Getting started](creating-an-extension.md)** — Step-by-step guide to building your first extension.
38+
- **[Building your extension](adding-commands.md)** — Deep dives into commands, lists, forms, markdown, and Dock support.
39+
- **[Publishing your extension](publish-extension.md)** — Learn how to package and publish to the Gallery.
40+
- **[Extension samples](samples.md)** — Open-source examples to learn from and build on.
41+
- **[API reference](sdk-namespaces.md)** — Detailed API reference for the Command Palette SDK.
42+
43+
Now, let's build. 💪

‎hub/powertoys/command-palette/extension-gallery.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Making your extension discoverable in Command Palette
3+
description: Learn how to list your Command Palette extension in the Extension Gallery so users can discover it from within Command Palette settings.
4+
ms.date: 04/10/2026
5+
ms.topic: how-to
6+
no-loc: [PowerToys, Windows, Insider]
7+
# Customer intent: As a Windows developer, I want to list my extension in the Command Palette Extension Gallery.
8+
---
9+
10+
# Making your extension discoverable
11+
12+
The Extension Gallery is a curated directory of Command Palette extensions that users can browse directly from within Command Palette settings. Listing your extension in the Gallery makes it discoverable to all Command Palette users — they can see your extension's description, screenshots, and install it with a single click.
13+
14+
:::image type="content" source="../images/gallery.png" alt-text="A screenshot of the Command Palette Extension Gallery showing a list of available extensions.":::
15+
16+
The Gallery itself doesn't host extensions. Instead, it links to your extension's install source — whether that's [WinGet](publish-extension-winget.md), the [Microsoft Store](publish-extension-store.md), or a direct download URL (such as a GitHub Releases page). When a user installs your extension from the Gallery, Command Palette uses the install source you specified.
17+
18+
## How to list your extension
19+
20+
The Extension Gallery is powered by the [microsoft/CmdPal-Extensions](https://github.com/microsoft/CmdPal-Extensions) repository on GitHub. The Contributing Guide covers the full submission process including folder structure, metadata format, and pull request requirements.
21+
22+
[Get started listing your extension in the Gallery](https://github.com/microsoft/CmdPal-Extensions/blob/main/docs/CONTRIBUTING.md)
23+
24+
Once listed, your extension's detail page is displayed directly in Command Palette, giving users a rich preview before they install.
25+
26+
:::image type="content" source="../images/details.png" alt-text="A screenshot of an extension detail page in Command Palette showing the extension description, screenshots, and install button.":::
27+
28+
## Related content
29+
30+
- [Publishing overview](publish-extension.md)
31+
- [Publish to WinGet](publish-extension-winget.md)
32+
- [Publish to Microsoft Store](publish-extension-store.md)
33+
- [Finding and installing extensions](finding-and-installing-extensions.md)

0 commit comments

Comments
 (0)