Skip to content

Commit 9cd1092

Browse files
alvinashcraftalvinashcraft
authored
Merge pull request #5279 from MicrosoftDocs/dev/migrie/get-started
Getting started docs for CmdPal
2 parents c8f554b + 54db542 commit 9cd1092

25 files changed

+981
-74
lines changed

‎hub/dev-environment/toc.yml

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,8 +127,32 @@ items:
127127
href: ../powertoys/command-palette/overview.md
128128
- name: Developer docs
129129
items:
130-
- name: Creating an extension
131-
href: ../powertoys/command-palette/creating-an-extension.md
130+
- name: Extensibility overview
131+
href: ../powertoys/command-palette/extensibility-overview.md
132+
- name: Authoring extensions
133+
items:
134+
- name: Creating an extension
135+
href: ../powertoys/command-palette/creating-an-extension.md
136+
- name: Adding commands
137+
href: ../powertoys/command-palette/adding-commands.md
138+
- name: Update a list of commands
139+
href: ../powertoys/command-palette/update-a-list-of-commands.md
140+
- name: Add top-level commands to your extension
141+
href: ../powertoys/command-palette/add-top-level-commands-to-your-extension.md
142+
- name: Command results
143+
href: ../powertoys/command-palette/command-results.md
144+
- name: Display markdown content
145+
href: ../powertoys/command-palette/using-markdown-content.md
146+
- name: Get user input with forms
147+
href: ../powertoys/command-palette/using-form-pages.md
148+
# - name: Handle the search text
149+
# href: ../powertoys/command-palette/dynamic-lists.md
150+
# - name: Adding details
151+
# href: ../powertoys/command-palette/add-details.md
152+
# - name: Tags
153+
# href: ../powertoys/command-palette/tags.md
154+
# - name: "Advanced: Adding an extension to your package"
155+
# href: ../powertoys/command-palette/adding-an-extension-to-your-package.md
132156
- name: Publishing your extension
133157
href: ../powertoys/command-palette/publish-extension.md
134158
- name: Extension samples

‎hub/images/command-palette/create-extension-page.png

212 KB
Loading

‎hub/images/command-palette/initial-created-extension-list.png

14.2 KB
Loading

‎hub/powertoys/command-palette/add-top-level-commands-to-your-extension.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Add top-level commands to your extension
3+
description: Learn how to add new top-level commands to your Command Palette extension.
4+
ms.date: 3/23/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+
# Adding top-level commands
11+
12+
**Previous**: [Update a list of commands](update-a-list-of-commands.md).
13+
14+
So far, we've only added commands to a single page, within your extension. You can also add more commands directly to the top-level list of commands too.
15+
16+
To do that, head on over to the `ExtensionNameCommandsProvider.cs` file. This file is where you'll add commands that should be shown at the top-level of the Command Palette. As you can see, there's currently only a single item there:
17+
18+
```csharp
19+
public ExtensionNameCommandsProvider()
20+
{
21+
DisplayName = "My sample extension";
22+
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
23+
_commands = [
24+
new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
25+
];
26+
}
27+
28+
public override ICommandItem[] TopLevelCommands()
29+
{
30+
return _commands;
31+
}
32+
```
33+
34+
In this very simple extension, we're simply creating a list of commands when the extension is created, and then returning that list whenever we're asked for the top-level commands. This prevents us from re-creating the list of commands every time we're asked for the top-level commands, which can be a performance optimization.
35+
36+
If we want to add another command to the top-level list of commands, we just need to add another `CommandItem`:
37+
38+
```csharp
39+
public ExtensionNameCommandsProvider()
40+
{
41+
DisplayName = "My sample extension";
42+
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
43+
_commands = [
44+
new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
45+
new CommandItem(new ShowMessageCommand()) { Title = "Send a message" },
46+
];
47+
}
48+
```
49+
50+
There you have it. Now you can add additional top-level commands to your extension.
51+
52+
If you'd like to update the list of top-level commands dynamically, you can do so in the same way as you would update a list page. This can be useful for cases like an extension that might first require the user to log in, before showing certain commands. In that case, you can show the "log in" command at the top level initially. Then, once the user logs in successfully, you can update the list of top-level commands to include the commands that required authentication.
53+
54+
Once you've determined that you need to change the top level list, call [`RaiseItemsChanged()`](./microsoft-commandpalette-extensions-toolkit/commandprovider_raiseitemschanged.md) on your `CommandProvider`. Command Palette will then ask for the top-level commands via `TopLevelCommands()` again, and you can return the updated list.
55+
56+
> [!TIP]
57+
> Create the `CommandItem`s for the top-level commands before calling `RaiseItemsChanged()`. This will ensure that the new commands are available when Command Palette asks for the top-level commands. This will help keep the work being done in call to `TopLevelCommands()` method to a minimum.
58+
59+
### Next up: [Command Results](command-results.md)
60+
61+
## Related content
62+
63+
- [PowerToys Command Palette utility](overview.md)
64+
- [Extensibility overview](extensibility-overview.md)
65+
- [Extension samples](samples.md)

‎hub/powertoys/command-palette/adding-commands.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Adding commands
3+
description: Learn how to add new commands to your Command Palette extension.
4+
ms.date: 3/23/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+
# Adding commands
11+
12+
**Previous**: [Creating an extension](creating-an-extension.md). We'll be starting with the project created in that article.
13+
14+
Now that you've created your extension, it's time to add some commands to it. 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:
15+
16+
```csharp
17+
public ExtensionNamePage()
18+
{
19+
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
20+
Title = "My sample extension";
21+
Name = "Open";
22+
}
23+
public override IListItem[] GetItems()
24+
{
25+
return [
26+
new ListItem(new NoOpCommand()) { Title = "TODO: Implement your extension here" }
27+
];
28+
}
29+
```
30+
31+
Here you can see that we've set the icon for the page, the title, and the name that's shown at the top-level when you have the command selected. The `GetItems` method is where you'll return the list of commands that you want to show on this page. Right now, that's just returning a single command that does nothing. Let's instead try making that command open _this_ page in the user's default web browser.
32+
33+
We can change the implementation of `GetItems()` to the following:
34+
35+
```csharp
36+
public override IListItem[] GetItems()
37+
{
38+
var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/adding-commands");
39+
return [
40+
new ListItem(command)
41+
{
42+
Title = "Open the Command Palette documentation",
43+
}
44+
];
45+
}
46+
```
47+
48+
Re-deploy your app, run the "reload" command to refresh the extensions in the palette, and head to your extension. You should see that the command now opens the Command Palette documentation.
49+
50+
The `OpenUrlCommand` is a helper for just opening a URL in the user's default web browser. You can also just implement an extension however you want. Let's instead make a new command, that shows a MessageBox. To do that, we need to create a new class that implements `IInvokableCommand`
51+
52+
```csharp
53+
using System.Runtime.InteropServices;
54+
55+
namespace ExtensionName;
56+
57+
internal sealed partial class ShowMessageCommand : InvokableCommand
58+
{
59+
public override string Name => "Show message";
60+
public override IconInfo Icon => new("\uE8A7");
61+
62+
public override CommandResult Invoke()
63+
{
64+
// 0x00001000 is MB_SYSTEMMODAL, which will display the message box on top of other windows.
65+
_ = MessageBox(0, "I came from the Command Palette", "What's up?", 0x00001000);
66+
return CommandResult.KeepOpen();
67+
}
68+
69+
70+
[DllImport("user32.dll", CharSet = CharSet.Unicode)]
71+
public static extern int MessageBox(IntPtr hWnd, string text, string caption, uint type);
72+
}
73+
```
74+
75+
Now we can add this command to the list of commands in the `ExtensionNamePage.cs` file:
76+
77+
```csharp
78+
public override IListItem[] GetItems()
79+
{
80+
var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
81+
var showMessageCommand = new ShowMessageCommand();
82+
return [
83+
new ListItem(command)
84+
{
85+
Title = "Open the Command Palette documentation",
86+
},
87+
new ListItem(showMessageCommand),
88+
];
89+
}
90+
```
91+
92+
Deploy and reload, and presto - a command to show a message box!
93+
94+
> [!TIP]
95+
> At about this point, you'll probably want to initialize a git repo / {other source control method of your choice} for your project. This will make it easier to track changes, and to share your extension with others.
96+
>
97+
> We recommend using GitHub, as it's easy to collaborate on your extension with others, and get feedback, and share it with the world.
98+
99+
## Adding more pages
100+
101+
So far, we've only worked with commands that "do something". However, you can also add commands that show additional pages withing the Command Palette. There are basically two types of "Commands" in the Palette:
102+
* `IInvokableCommand` - These are commands that **do something**.
103+
* `IPage` - These are commands that **show something**.
104+
105+
Because `IPage`s are just `ICommand`s, you can use them anywhere you can use commands. This means you can add them to the top-level list of commands, or to a list of commands on a page, the context menu on an item, etc.
106+
107+
There are two different kinds of pages you can show:
108+
* [`ListPage`](./microsoft-commandpalette-extensions-toolkit/listpage.md) - This is a page that shows a list of commands. This is what we've been working with so far.
109+
* [`ContentPage`](./microsoft-commandpalette-extensions-toolkit/contentpage.md) - This is a page that shows rich content to the user. This allows you to specify abstract content, and let Command Palette worry about rendering the content in a native experience. There are two different types of content supported so far:
110+
* [Markdown content](./using-markdown-content.md) - This is content that's written in Markdown, and is rendered in the Command Palette. See [`MarkdownContent`](./microsoft-commandpalette-extensions-toolkit/markdowncontent.md) for details.
111+
* [Form content](./using-form-pages.md) - This is content that shows a form to the user, and then returns the results of that form to the extension. These are powered by [Adaptive Cards](https://aka.ms/adaptive-cards) This is useful for getting user input, or displaying more complex layouts of information. See [`FormContent`](./microsoft-commandpalette-extensions-toolkit/formcontent.md) for details.
112+
113+
114+
We'll start by adding a new page that shows a list of commands. We can create a new class that implements `ListPage`:
115+
116+
```csharp
117+
using Microsoft.CommandPalette.Extensions.Toolkit;
118+
using System.Linq;
119+
120+
namespace ExtensionName;
121+
122+
internal sealed partial class MySecondPage : ListPage
123+
{
124+
public MySecondPage()
125+
{
126+
Icon = new("\uF147"); // Dial2
127+
Title = "My second page";
128+
Name = "Open";
129+
}
130+
131+
public override IListItem[] GetItems()
132+
{
133+
// Return 100 CopyText commands
134+
return Enumerable
135+
.Range(0, 100)
136+
.Select(i => new ListItem(new CopyTextCommand($"{i}"))
137+
{
138+
Title = $"Copy text {i}"
139+
}).ToArray();
140+
}
141+
}
142+
```
143+
144+
Then we go update our `ExtensionNamePage.cs` to include this new page:
145+
146+
```diff
147+
public override IListItem[] GetItems()
148+
{
149+
OpenUrlCommand command = new("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
150+
return [
151+
new ListItem(command)
152+
{
153+
Title = "Open the Command Palette documentation",
154+
},
155+
new ListItem(new ShowMessageCommand()),
156+
+ new ListItem(new MySecondPage()) { Title = "My second page", Subtitle = "A second page of commands" },
157+
];
158+
}
159+
```
160+
161+
Deploy, reload, and you should now see a new page in your extension that shows 100 commands that copy a number to the clipboard.
162+
163+
### Next up: [Update a list of commands](update-a-list-of-commands.md)
164+
165+
## Related content
166+
167+
- [PowerToys Command Palette utility](overview.md)
168+
- [Extensibility overview](extensibility-overview.md)
169+
- [Extension samples](samples.md)

‎hub/powertoys/command-palette/command-results.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: Command results
3+
description: Learn what the different kinds of Command Palette command results do.
4+
ms.date: 3/23/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+
# Command results
11+
12+
**Previous**: [Add top-level commands to your extension](add-top-level-commands-to-your-extension.md)
13+
14+
15+
[`IInvokableCommand`](./microsoft-commandpalette-extensions/iinvokablecommand.md)s are the fundamental units of "do something" in the Command Palette. The [`Invoke`](./microsoft-commandpalette-extensions/iinvokablecommand.md) method is called when the user selects the command, and it's where you _do something_ in your extension. The `Invoke` method returns an `ICommandResult`, which tells the Command Palette what to do after the command has been invoked. This page details what's possible with each kind of command result.
16+
17+
The toolkit provides a number of helper methods to create command results. These are all static methods on the `CommandResult` class. Calling these methods on their own won't do anything - you must return those objects as the result of a `Invoke` method, for Command Palette to handle them.
18+
19+
<!-- GoToPage currently omitted from these docs, because it's not remotely implemented -->
20+
21+
## `KeepOpen`
22+
23+
This command result does nothing. It leaves the palette in its current state, with the current page stack and query. This can be useful for commands that want to keep the the user in the Command Palette, to keep working with the current page.
24+
25+
> [!NOTE]
26+
> Even when returing `KeepOpen`, launching a new app or window from the Command Palette will automatically hide the palette the next window recieves focus.
27+
28+
## `Hide`
29+
30+
This command result keeps the current page open, but hides the Command Palette. This can be useful for commands that want to take the user briefly out of the Command Palette, but then come back to this context.
31+
32+
## `GoBack`
33+
34+
This result takes the user back a page in the Command Palette, and keeps the window visible. This is perfect for form pages, where doing the command should take you the user back to the previous context.
35+
36+
## `GoHome`
37+
38+
This result takes the user back to the main page of the Command Palette. It will leave the Palette visible (unless the palette otherwise loses focus). Consider using this for scenarios where you've changed your top-level commands.
39+
40+
## `Dismiss`
41+
42+
This result hides the Command Palette after the action is executed, and takes it back to the hme page. On the next launch, the Command Palette will start from the main page with a blank query. This is useful for commands that are one-off actions, or that don't need to keep the Command Palette open.
43+
44+
If you don't know what else to use, this should be your default. Ideally, users should come into the palette, find what they need, and be done with it.
45+
46+
## `ShowToast`
47+
48+
This result displays 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.
49+
50+
Consider the [CopyTextCommand](./microsoft-commandpalette-extensions-toolkit/copytextcommand.md) in the helpers - this command will show a toast with the text "Copied to clipboard", then dismiss the palette.
51+
52+
By default, [`CommandResult.ShowToast(string)`](./microsoft-commandpalette-extensions-toolkit/commandresult_showtoast_string.md) helper will have a `Result` of `CommandResult.Dismiss`. However, you can instead change the result to any of the other results if you want. This allows you to display a toast and keep the palette open, if you'd like.
53+
54+
## `Confirm`
55+
56+
This result displays a confirmation dialog to the user. If the user confirms the dialog, then the `PrimaryCommand` of the `ConfirmationArgs` will be performed.
57+
58+
This is useful for commands that might have destructive actions, or that need to confirm user intent.
59+
60+
## Example
61+
62+
As an example, here's a page with one command for each kind of command result:
63+
64+
```csharp
65+
66+
using Microsoft.CommandPalette.Extensions.Toolkit;
67+
68+
internal sealed partial class CommandResultsPage : ListPage
69+
{
70+
public CommandResultsPage()
71+
{
72+
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
73+
Title = "Example command results";
74+
Name = "Open";
75+
}
76+
77+
public override IListItem[] GetItems()
78+
{
79+
ConfirmationArgs confirmArgs = new()
80+
{
81+
PrimaryCommand = new AnonymousCommand(
82+
() =>
83+
{
84+
ToastStatusMessage t = new("The dialog was confirmed");
85+
t.Show();
86+
})
87+
{
88+
Name = "Confirm",
89+
Result = CommandResult.KeepOpen(),
90+
},
91+
Title = "You can set a title for the dialog",
92+
Description = "Are you really sure you want to do the thing?",
93+
};
94+
95+
return
96+
[
97+
new ListItem(new AnonymousCommand(null) { Result = CommandResult.KeepOpen() }) { Title = "Keep the palette open" },
98+
new ListItem(new AnonymousCommand(null) { Result = CommandResult.Hide() }) { Title = "Hide the palette" },
99+
new ListItem(new AnonymousCommand(null) { Result = CommandResult.GoBack() }) { Title = "Go back" },
100+
new ListItem(new AnonymousCommand(null) { Result = CommandResult.GoHome() }) { Title = "Go home" },
101+
new ListItem(new AnonymousCommand(null) { Result = CommandResult.Dismiss() }) { Title = "Dismiss the palette" },
102+
new ListItem(new AnonymousCommand(null) { Result = CommandResult.ShowToast("What's up") }) { Title = "Show a toast" },
103+
new ListItem(new AnonymousCommand(null) { Result = CommandResult.Confirm(confirmArgs) }) { Title = "Confirm something" },
104+
];
105+
}
106+
}
107+
```
108+
109+
### Next up: [Display markdown content](using-markdown-content.md)
110+
111+
## Related content
112+
113+
- [PowerToys Command Palette utility](overview.md)
114+
- [Extensibility overview](extensibility-overview.md)
115+
- [Extension samples](samples.md)

0 commit comments

Comments
 (0)