You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
8
8
---
9
9
10
-
# Extensibility overview
11
-
12
-
The Command Palette provides a full extension model, allowing developers to create their own experiences for the palette. This document provides information about how to create an extension and publish it. It also includes a sample extension that demonstrates the extensibility model.
13
-
14
-
## Registering your extension
15
-
16
-
Extensions can register themselves with the Command Palette using their `.appxmanifest`. As an example:
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.
13
+
14
+
The form will ask you for the following information:
15
+
***ExtensionName**: The name of your extension. This will be used as the name of the project and the name of the class that implements your commands. Make sure it's a valid C# class name - it shouldn't have any spaces or special characters, and should start with a capital letter.
16
+
***Extension Display Name**: The name of your extension as it will appear in the Command Palette. This can be a more human-readable name.
17
+
***Output Path**: The folder where the project will be created.
18
+
* The project will be created in a subdirectory of the path you provided.
19
+
* If this path doesn't exist, it will be created for you.
Once you submit the form, Command Palette will automatically generate the project for you. At this point, your projects structure should look like the following:
24
+
25
+
```plaintext
26
+
ExtensionName/
27
+
│ Directory.Build.props
28
+
│ Directory.Packages.props
29
+
│ nuget.config
30
+
│ ExtensionName.sln
31
+
└───ExtensionName
32
+
│ app.manifest
33
+
│ Package.appxmanifest
34
+
│ Program.cs
35
+
│ ExtensionName.cs
36
+
│ ExtensionName.csproj
37
+
│ ExtensionNameCommandsProvider.cs
38
+
├───Assets
39
+
│ <A bunch of placeholder images>
40
+
├───Pages
41
+
│ ExtensionNamePage.cs
42
+
└───Properties
43
+
│ launchSettings.json
44
+
└───PublishProfiles
45
+
win-arm64.pubxml
46
+
win-x64.pubxml
46
47
```
47
48
48
-
### Important notes
49
+
(with `ExtensionName` replaced with the name you provided)
50
+
51
+
From here, you can immediately build the project and run it. Once your package is deployed and running, Command Palette will automatically discover your extension and load it into the palette.
52
+
53
+
> [!TIP]
54
+
> Make sure you deploy your app! Just **build**ing your application won't update the package in the same way that deploying it will.
55
+
56
+
> [!WARNING]
57
+
> Running "ExtensionName (Unpackaged)" from Visual Studio will not **deploy** your app package.
58
+
59
+
You should be able to see your extension in the Command Palette at the end of the list of commands. Entering that command should take you to the page for your command, and you should see a single command that says "TODO: Implement your extension here".
Congrats! You've made your first extension! Now let's go ahead and actually add some commands to it.
64
+
65
+
When you make changes to your extension, you can rebuild your project and deploy it again. Command Palette will **not** notice changes to packages that are re-ran through Visual Studio, so you'll need to manually run the "**Reload**" command to force Command Palette to re-instantiate your extension.
66
+
67
+
Let's make that command do something.
68
+
69
+
We can start by navigating to the `ExtensionNamePage.cs` file. This file is the [`ListPage`](./microsoft-commandpalette-extensions-toolkit/listpage.md) that will be displayed when the user selects your extension. In there you should see:
- 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.
53
-
- Make sure that this CLSID is unique, and matches the one in your application
54
-
- 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.
55
-
- 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.
56
88
57
-
Currently, only `Commands` is supported. If we need to add more in the future, they will be added to the `SupportedInterfaces` element.
89
+
### Next up: [Update a list of commands](update-a-list-of-commands.md)
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
5
+
ms.topic: concept-article
6
+
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.
8
+
---
9
+
10
+
# Extensibility overview
11
+
12
+
The Command Palette provides a full extension model, allowing developers to create their own experiences for the palette.
13
+
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.
15
+
16
+
For more detailed instructions, you can follow these pages:
17
+
18
+
*[Creating an extension](../powertoys/command-palette/creating-an-extension.md)
19
+
*[Update a list of commands](../powertoys/command-palette/update-a-list-of-commands.md)
*[Get user input with forms](../powertoys/command-palette/using-form-pages.md)
24
+
*[Handle the search text](../powertoys/command-palette/dynamic-lists.md)
25
+
*[Advanced: Adding an extension to your package](../powertoys/command-palette/adding-an-extension-to-your-package.md)
26
+
27
+
28
+
## Extension details
29
+
30
+
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.
31
+
32
+
Command Palette will use the Package Catalog to find apps that list themselves as an `windows.appExtension` for `com.microsoft.commandpalette`.
33
+
34
+
### Registering your extension
35
+
36
+
Extensions can register themselves with the Command Palette using their `.appxmanifest`. As an example:
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.
69
+
70
+
### Important notes
71
+
72
+
Some notable elements about the manifest example:
73
+
74
+
- 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.
75
+
- 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.
76
+
- Make sure that this CLSID is unique, and matches the one in your application. If you change one, you need to change all three.
77
+
- 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.
Contains the interfaces to create extensions for the Command Palette.
12
12
13
+
These are the raw WinRT interfaces that Command Palette uses to communicate with your extension. These can be implemented however you'd like, in any language that supports implementing WinRT interfaces. For simplicity, there's a reference C# implementation of these interfaces in the [`Microsoft.CommandPalette.Extensions.Toolkit`](../microsoft-commandpalette-extensions-toolkit/microsoft-commandpalette-extensions-toolkit.md) namespace.
The Command Palette provides a full extension model, allowing developers to create their own experiences for the palette. This document provides information about how to publish an extension.
13
13
14
-
There is a "Sample Project" template included with the Command Palette. This can be used to quickly generate a project that creates a new extension. This will include the `.sln`, `.csproj`, and `.appxmanifest` files needed to create a new extension, as well as the plumbing to get it ready to be published. You will then open the project to the **MyCommandProvider** class and implement your commands.
14
+
There is a "Sample Project" template included with the Command Palette. This can be used to quickly generate a project that creates a new extension. This will include the `.sln`, `.csproj`, and `.appxmanifest` files needed to create a new extension, as well as the plumbing to get it ready to be published. You will then open the project to the `{ExtensionName}CommandsProvider` class (where `{ExtensionName}` is replaced with the name of your extension project) and implement your commands.
15
15
16
16
## Pre-requisites
17
17
18
18
The following tools are required to build and publish your extension:
19
19
20
20
-[Visual Studio 2022](https://visualstudio.microsoft.com/vs/) (Community, Professional, or Enterprise edition)
21
21
22
+
## WinGet
23
+
24
+
Publishing packages to WinGet is the recommended way to share your extensions with users. Extension packages which are listed on WinGet can be discovered and installed directly from the Command Palette.
25
+
26
+
For the most part, following the steps on [Submit packages to Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/package/) will get your extension onto WinGet itself.
27
+
28
+
Before submitting your manifest to WinGet, you'll need to check two things:
29
+
30
+
### Add `windows-commandpalette-extension` tag
31
+
32
+
### Ensure WindowsAppSdk is listed as a dependency
33
+
34
+
If you're using Windows App SDK, then you'll need to make sure that it is listed as a dependency of your package
35
+
36
+
If you're not using the template project, then this may not apply to you.
37
+
38
+
<!--
39
+
40
+
Some day soon:
41
+
42
+
As a part of the project template, there's a WinGet GitHub Actions workflow that allows you to publish your extension to the WinGet repository with the necessary tags to make it discoverable by the Command Palette. So, you don't need to understand the details of packaging. You add the extension to your GitHub repository and let the your GitHub Actions pipeline handle the publishing.
43
+
44
+
-->
45
+
22
46
## Microsoft Store
23
47
24
-
Command Palette extensions can be published to the Microsoft Store. The process is similar to publishing other apps or extensions. You create a new submission in the Partner Center and upload your `.appx` package. The Command Palette automatically discovers your extension when it's installed from the Microsoft Store.
48
+
Command Palette extensions can be published to the Microsoft Store. The process is similar to publishing other apps or extensions. You create a new submission in the Partner Center and upload your `.msix` package. The Command Palette automatically discovers your extension when it's installed from the Microsoft Store.
25
49
26
-
## WinGet
50
+
Command Palette cannot, however, search for & install extensions that are only listed in the store. You can find those by running the following command:
As a part of the project template, there's a WinGet GitHub Actions workflow that allows you to publish your extension to the WinGet repository with the necessary tags to make it discoverable by the Command Palette. So, you don't need to understand the details of packaging. You add the extension to your GitHub repository and let the your GitHub Actions pipeline handle the publishing.
56
+
You can run this from the "Run commands" command in Command Palette, or from the command-line, or from the Run dialog.
0 commit comments