Skip to content

Commit 928b85a

Browse files
alvinashcraftalvinashcraft
committed
Update formatting for new how-to content in CmdPal
1 parent 7025b1a commit 928b85a

9 files changed

+152
-138
lines changed

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

Lines changed: 31 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -2,59 +2,61 @@
22
title: Add top-level commands to your extension
33
description: Learn how to add new top-level commands to your Command Palette extension.
44
ms.date: 3/23/2025
5-
ms.topic: concept-article
5+
ms.topic: how-to
66
no-loc: [PowerToys, Windows, Insider]
77
# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
88
---
99

10-
# Adding top-level commands
10+
# Adding top-level commands to your extension
1111

1212
**Previous**: [Update a list of commands](update-a-list-of-commands.md).
1313

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.
14+
So far, you'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+
## Adding the top-level commands
1517

1618
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:
1719

1820
```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-
}
21+
public ExtensionNameCommandsProvider()
22+
{
23+
DisplayName = "My sample extension";
24+
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
25+
_commands = [
26+
new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
27+
];
28+
}
29+
30+
public override ICommandItem[] TopLevelCommands()
31+
{
32+
return _commands;
33+
}
3234
```
3335

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.
36+
This sample extension creates a list of commands when the extension is created and returns that list whenever it's asked for the top-level commands. This prevents the extension from re-creating the list of commands every time the top-level commands are requested. This is a performance optimization.
3537

36-
If we want to add another command to the top-level list of commands, we just need to add another `CommandItem`:
38+
If you want to add another command to the top-level list of commands, you can add another **CommandItem**:
3739

3840
```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-
}
41+
public ExtensionNameCommandsProvider()
42+
{
43+
DisplayName = "My sample extension";
44+
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
45+
_commands = [
46+
new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
47+
new CommandItem(new ShowMessageCommand()) { Title = "Send a message" },
48+
];
49+
}
4850
```
4951

5052
There you have it. Now you can add additional top-level commands to your extension.
5153

5254
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.
5355

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.
56+
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 request the top-level commands via **TopLevelCommands** again, and you can return the updated list.
5557

5658
> [!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.
59+
> Create the **CommandItem** objects for the top-level commands before calling **RaiseItemsChanged**. This will ensure that the new commands are available when Command Palette requests the top-level commands. This will ensure that the work being executed in each call to **TopLevelCommands** method to a minimum.
5860
5961
### Next up: [Command Results](command-results.md)
6062

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

Lines changed: 54 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,57 @@
11
---
2-
title: Adding commands
2+
title: Adding commands to your extension
33
description: Learn how to add new commands to your Command Palette extension.
44
ms.date: 3/23/2025
5-
ms.topic: concept-article
5+
ms.topic: how-to
66
no-loc: [PowerToys, Windows, Insider]
77
# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
88
---
99

10-
# Adding commands
10+
# Adding commands to your extension
1111

1212
**Previous**: [Creating an extension](creating-an-extension.md). We'll be starting with the project created in that article.
1313

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:
14+
Now that you've created your extension, it's time to add some commands to it.
15+
16+
## Add some commands
17+
18+
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:
1519

1620
```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-
}
21+
public ExtensionNamePage()
22+
{
23+
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
24+
Title = "My sample extension";
25+
Name = "Open";
26+
}
27+
public override IListItem[] GetItems()
28+
{
29+
return [
30+
new ListItem(new NoOpCommand()) { Title = "TODO: Implement your extension here" }
31+
];
32+
}
2933
```
3034

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.
35+
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.
3236

33-
We can change the implementation of `GetItems()` to the following:
37+
We can change the implementation of **GetItems** to the following:
3438

3539
```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-
}
40+
public override IListItem[] GetItems()
41+
{
42+
var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/adding-commands");
43+
return [
44+
new ListItem(command)
45+
{
46+
Title = "Open the Command Palette documentation",
47+
}
48+
];
49+
}
4650
```
4751

4852
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.
4953

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`
54+
The **OpenUrlCommand** is a helper for opening a URL in the user's default web browser. You can also 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**.
5155

5256
```csharp
5357
using System.Runtime.InteropServices;
@@ -75,18 +79,18 @@ internal sealed partial class ShowMessageCommand : InvokableCommand
7579
Now we can add this command to the list of commands in the `ExtensionNamePage.cs` file:
7680

7781
```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-
}
82+
public override IListItem[] GetItems()
83+
{
84+
var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
85+
var showMessageCommand = new ShowMessageCommand();
86+
return [
87+
new ListItem(command)
88+
{
89+
Title = "Open the Command Palette documentation",
90+
},
91+
new ListItem(showMessageCommand),
92+
];
93+
}
9094
```
9195

9296
Deploy and reload, and presto - a command to show a message box!
@@ -99,19 +103,19 @@ Deploy and reload, and presto - a command to show a message box!
99103
## Adding more pages
100104

101105
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**.
106+
- **IInvokableCommand** - These are commands that *do something*.
107+
- **IPage** - These are commands that *show something*.
104108

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.
109+
Because **IPage** implementations are **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.
106110

107111
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+
- [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.
113+
- [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:
114+
- [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.
115+
- [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.
112116

113117

114-
We'll start by adding a new page that shows a list of commands. We can create a new class that implements `ListPage`:
118+
Start by adding a new page that shows a list of commands. Create a new class that implements **ListPage**:
115119

116120
```csharp
117121
using Microsoft.CommandPalette.Extensions.Toolkit;
@@ -141,7 +145,7 @@ internal sealed partial class MySecondPage : ListPage
141145
}
142146
```
143147

144-
Then we go update our `ExtensionNamePage.cs` to include this new page:
148+
Next, update the `ExtensionNamePage.cs` to include this new page:
145149

146150
```diff
147151
public override IListItem[] GetItems()

0 commit comments

Comments
 (0)