Skip to content

Commit 9d74761

Browse files
Merge pull request MicrosoftDocs#5506 from MicrosoftDocs/main
Merged by Learn.Build PR Management system
2 parents 821386f + ee65c92 commit 9d74761

11 files changed

+310
-327
lines changed

hub/images/command-palette/reload.png

29.5 KB
Loading

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,15 @@ So far, you've only added commands to a single page within your extension. You c
1515

1616
## Adding the top-level commands
1717

18-
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:
18+
To do that, head on over to the `<ExtensionName>CommandsProvider.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:
1919

2020
```csharp
21-
public ExtensionNameCommandsProvider()
21+
public <ExtensionName>CommandsProvider()
2222
{
2323
DisplayName = "My sample extension";
2424
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
2525
_commands = [
26-
new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
26+
new CommandItem(new <ExtensionName>Page()) { Title = DisplayName },
2727
];
2828
}
2929

@@ -38,12 +38,12 @@ This sample extension creates a list of commands when the extension is created a
3838
If you want to add another command to the top-level list of commands, you can add another **CommandItem**:
3939

4040
```csharp
41-
public ExtensionNameCommandsProvider()
41+
public <ExtensionName>CommandsProvider()
4242
{
4343
DisplayName = "My sample extension";
4444
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
4545
_commands = [
46-
new CommandItem(new ExtensionNamePage()) { Title = DisplayName },
46+
new CommandItem(new <ExtensionName>Page()) { Title = DisplayName },
4747
new CommandItem(new ShowMessageCommand()) { Title = "Send a message" },
4848
];
4949
}

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,10 @@ Now that you've created your extension, it's time to add some commands to it.
1515

1616
## Add some commands
1717

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:
18+
We can start by navigating to the `<ExtensionName>Page.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:
1919

2020
```csharp
21-
public ExtensionNamePage()
21+
public <ExtensionName>Page()
2222
{
2323
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
2424
Title = "My sample extension";
@@ -56,7 +56,7 @@ The **OpenUrlCommand** is a helper for opening a URL in the user's default web b
5656
```csharp
5757
using System.Runtime.InteropServices;
5858

59-
namespace ExtensionName;
59+
namespace <ExtensionName>;
6060

6161
internal sealed partial class ShowMessageCommand : InvokableCommand
6262
{
@@ -76,7 +76,7 @@ internal sealed partial class ShowMessageCommand : InvokableCommand
7676
}
7777
```
7878

79-
Now we can add this command to the list of commands in the `ExtensionNamePage.cs` file:
79+
Now we can add this command to the list of commands in the `<ExtensionName>Page.cs` file:
8080

8181
```csharp
8282
public override IListItem[] GetItems()
@@ -121,7 +121,7 @@ Start by adding a new page that shows a list of commands. Create a new class tha
121121
using Microsoft.CommandPalette.Extensions.Toolkit;
122122
using System.Linq;
123123

124-
namespace ExtensionName;
124+
namespace <ExtensionName>;
125125

126126
internal sealed partial class MySecondPage : ListPage
127127
{
@@ -145,7 +145,7 @@ internal sealed partial class MySecondPage : ListPage
145145
}
146146
```
147147

148-
Next, update the `ExtensionNamePage.cs` to include this new page:
148+
Next, update the `<ExtensionName>Page.cs` to include this new page:
149149

150150
```diff
151151
public override IListItem[] GetItems()

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

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,10 @@ no-loc: [PowerToys, Windows, Insider]
1313

1414
An [IInvokableCommand](./microsoft-commandpalette-extensions/iinvokablecommand.md) is a fundamental unit 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 type of command result.
1515

16-
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.
16+
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.
17+
18+
> [!NOTE]
19+
> There are code examples for the various CommandResult methods listed on this page.
1720
1821
<!-- GoToPage currently omitted from these docs, because it's not remotely implemented -->
1922

@@ -38,7 +41,7 @@ This result takes the user back to the main page of the Command Palette. It will
3841

3942
## Dismiss command result
4043

41-
This result hides the Command Palette after the action is executed, and takes it back to the home 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.
44+
This result hides the Command Palette after the action is executed, and takes it back to the home 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.
4245

4346
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.
4447

@@ -60,6 +63,9 @@ This is useful for commands that might have destructive actions, or that need to
6063

6164
As an example, here's a page with one command for each kind of command result:
6265

66+
> [!NOTE]
67+
> If working from prior section, modify the code below from `CommandResultsPage` to `<ExtensionName>Page`.
68+
6369
```csharp
6470

6571
using Microsoft.CommandPalette.Extensions;

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

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Extensions are written in C#. The fastest way to get started writing extensions
1515

1616
The form will ask you for the following information:
1717

18-
- **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.
18+
- **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. Reference in docs as `<ExtensionName>`.
1919
- **Extension Display Name**: The name of your extension as it will appear in the Command Palette. This can be a more human-readable name.
2020
- **Output Path**: The folder where the project will be created.
2121
- The project will be created in a subdirectory of the path you provided.
@@ -26,38 +26,38 @@ The form will ask you for the following information:
2626
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:
2727

2828
```plaintext
29-
ExtensionName/
29+
<ExtensionName>/
3030
│ Directory.Build.props
3131
│ Directory.Packages.props
3232
│ nuget.config
33-
│ ExtensionName.sln
34-
└───ExtensionName
33+
<ExtensionName>.sln
34+
└───<ExtensionName>
3535
│ app.manifest
3636
│ Package.appxmanifest
3737
│ Program.cs
38-
│ ExtensionName.cs
39-
│ ExtensionName.csproj
40-
ExtensionNameCommandsProvider.cs
38+
<ExtensionName>.cs
39+
<ExtensionName>.csproj
40+
<ExtensionName>CommandsProvider.cs
4141
├───Assets
4242
│ <A bunch of placeholder images>
4343
├───Pages
44-
ExtensionNamePage.cs
44+
<ExtensionName>Page.cs
4545
└───Properties
4646
│ launchSettings.json
4747
└───PublishProfiles
4848
win-arm64.pubxml
4949
win-x64.pubxml
5050
```
5151

52-
(with `ExtensionName` replaced with the name you provided)
52+
(with `<ExtensionName>` replaced with the name you provided)
5353

54-
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.
54+
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.
5555

5656
> [!TIP]
5757
> Make sure you _deploy_ your app! Just **build**ing your application won't update the package in the same way that deploying it will.
5858
5959
> [!WARNING]
60-
> Running "ExtensionName (Unpackaged)" from Visual Studio will not **deploy** your app package.
60+
> Running "\<ExtensionName\> (Unpackaged)" from Visual Studio will not **deploy** your app package.
6161
>
6262
> If you're using `git` for source control, and you used the standard `.gitignore` file for C#, you'll want to remove the following two lines from your `.gitignore` file:
6363
> ```
@@ -74,6 +74,9 @@ Congrats! You've made your first extension! Now let's go ahead and actually add
7474
7575
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.
7676
77+
![Screenshot of reload](../../images/command-palette/reload.png)
78+
79+
7780
### Next up: [Add commands to your extension](adding-commands.md)
7881
7982
## Related content

hub/powertoys/command-palette/update-a-list-of-commands.md

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ So far we've shown how to return a list of static items in your extension. Howev
1515

1616
## Updating a command
1717

18-
Almost all extension objects in the Command Palette implement the **IPropChanged** interface. This allows them to notify the Command Palette when they've changed, and the Command Palette will update the UI to reflect those changes. If you're using the toolkit implementations, this interface has already been implemented for you for properties that support it.
18+
Almost all extension objects in the Command Palette implement the **IPropChanged** interface. This allows them to notify the Command Palette when they've changed, and the Command Palette will update the UI to reflect those changes. If you're using the [toolkit](/windows/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/microsoft-commandpalette-extensions-toolkit) implementations, this interface has already been implemented for you for properties that support it.
1919

2020
As a simple example, you can update the title of the page. To do this, you can add a command which will simply update the title of the page.
2121

@@ -87,36 +87,36 @@ Update your list item to take a reference to the page, and add a method to incre
8787
```csharp
8888
internal sealed partial class IncrementingListItem : ListItem
8989
{
90-
public IncrementingListItem(ExtensionNamePage page) :
90+
public IncrementingListItem(<ExtensionName>Page page) :
9191
base(new NoOpCommand())
9292
{
9393
_page = page;
9494
Command = new AnonymousCommand(action: _page.Increment) { Result = CommandResult.KeepOpen() };
9595
Title = "Increment";
9696
}
9797

98-
private ExtensionNamePage _page;
98+
private <ExtensionName>Page _page;
9999
}
100100
```
101101

102102
Then, change your page as follows:
103103

104104
```cs
105-
public ExtensionNamePage()
105+
public <ExtensionName>Page()
106106
{
107107
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
108108
Title = "My sample extension";
109109
Name = "Open";
110110

111-
_items = [new IncrementingListItem2this) { Subtitle = $"Item 0" }];
111+
_items = [new IncrementingListItem(this) { Subtitle = $"Item 0" }];
112112
}
113113
public override IListItem[] GetItems()
114114
{
115115
return _items.ToArray();
116116
}
117117
internal void Increment()
118118
{
119-
_items += new IncrementingListItem(this) { Subtitle = $"Item {_items.Count}" };
119+
_items.Add(new IncrementingListItem(this) { Subtitle = $"Item {_items.Count}" });
120120
RaiseItemsChanged();
121121
}
122122
private List<ListItem> _items;
@@ -128,20 +128,24 @@ Now, every time you perform one of the **IncrementingListItem** commands, the li
128128

129129
Everything so far has been pretty instantaneous. Many extensions however may need to do some work that takes a lot longer. In that case, you can set **Page.IsLoading** to `true` to show a loading spinner. This will help indicate that the extension is doing something in the background.
130130

131+
> [!NOTE]
132+
> If working from prior section, modify the code below from `Page.IsLoading` to `this.IsLoading`.
133+
131134
```csharp
132135
internal void Increment()
133136
{
134137
Page.IsLoading = true;
135138
Task.Run(() =>
136139
{
137140
Thread.Sleep(5000);
138-
_items += new IncrementingListItem(this) { Subtitle = $"Item {_items.Count}" };
141+
_items.Add(new IncrementingListItem(this) { Subtitle = $"Item {_items.Count}" });
139142
RaiseItemsChanged();
140143
Page.IsLoading = false;
141144
});
142145
}
143146
```
144147

148+
145149
Best practice is to set **IsLoading** to `true` before starting the work. Then do all the work to build all the new **ListItems** you need to display to the user. Then, once the items are ready, call **RaiseItemsChanged** and set **IsLoading** back to `false`. This will ensure that the loading spinner is shown for the entire duration of the work, and that the UI is updated as soon as the work is done (without waiting for your extension to construct new **ListItem** objects).
146150

147151
### Next up: [Add top-level commands to your extension](add-top-level-commands-to-your-extension.md)

hub/powertoys/command-palette/using-markdown-content.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ So far, we've only shown how to display a list of commands in a **ListPage**. Ho
1919

2020
As a simple example, we can create the following page:
2121

22+
> [!NOTE]
23+
> If working from prior sections, modify the code below from `MarkdownPage` to `<ExtensionName>Page`.
24+
2225
```csharp
2326
public class MarkdownPage : ContentPage
2427
{

hub/powertoys/run.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -430,6 +430,8 @@ To search for Windows services, [enable the plugin](#plugin-manager), open Power
430430

431431
With the Window Walker plugin, you can switch to other windows, close them, or kill the window process.
432432

433+
You can enter the **Direct activation command** `<` to search for open windows. The plugin will search for the window title and the name of the process that owns the window.
434+
433435
#### Kill a window process
434436

435437
With the Window Walker plugin, you can kill the process of a window if it stops responding.

0 commit comments

Comments
 (0)