Adicionar comandos à sua extensão

Anterior: Criando uma extensão. Vamos começar com o projeto criado nesse artigo.

Agora que você criou sua extensão, é hora de adicionar comandos a ela.

Adicionar comandos

Podemos começar navegando até o /Pages/<ExtensionName>Page.cs arquivo. Este arquivo é o ListPage que será exibido quando o usuário selecionar sua extensão. Lá você deve ver:

public <ExtensionName>Page()
{
    Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
    Title = "My sample extension";
    Name = "Open";
}
public override IListItem[] GetItems()
{
    return [
        new ListItem(new NoOpCommand()) { Title = "TODO: Implement your extension here" }
    ];
}

Aqui você pode ver que definimos o ícone para a página, o título e o nome que é mostrado no nível superior quando você tem o comando selecionado. O GetItems método é onde você retornará a lista de comandos que deseja mostrar nesta página. No momento, está apenas retornando um único comando que não faz nada. Em vez disso, vamos tentar fazer com que esse comando abra esta página no navegador da Web padrão do usuário.

1. Atualize GetItems para o seguinte:

public override IListItem[] GetItems()
{
    var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/adding-commands");
    return [
        new ListItem(command)
        {
            Title = "Open the Command Palette documentation",
        }
    ];
}

Para atualizar a extensão na Paleta de Comandos, você precisa:

1. Implante sua extensão
2. Na Paleta de comandos, digite o comando "reload" para atualizar as extensões na paleta

1. Role para baixo até a extensão e pressione Enter
2. Pressione enter em Open the Command Palette documentation
3. Você verá que o comando abre a documentação da Paleta de Comandos

O OpenUrlCommand é um auxiliar para abrir uma URL no navegador da Web padrão do usuário.

Extensão de depuração

Ao criar a sua extensão, você provavelmente desejará depurá-la.

1. Adicione uma mensagem de depuração à GetItems função.

    public override IListItem[] GetItems()
    {
        var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/adding-commands");
    
+       Debug.Write("Debug message from GetItems");
    
        return [
            new ListItem(command)
            {
                Title = "Open the Command Palette documentation",
            }
        ];
    }

1. Implante sua extensão
2. Confirme se você está na configuração de depuração

1. Execute a aplicação no modo de depuração ao pressionar o botão ▶️ verde "Iniciar" ou pressione F5
2. Verifique se a janela de saída está definida para mostrar Debug (Ctrl + Alt + O)

1. Na Paleta de Comandos, execute reload
2. Vá para a sua extensão e selecione Open the Command Palette documentation.
3. Na janela de Saída de Resultados do Visual Studio, deve ver Debug message from GetItems

Comando InvokableCommand

Vamos continuar criando um novo comando, que mostra um MessageBox. Para fazer isso, precisamos criar uma nova classe que implemente InvokableCommand.

1. No Visual Studio, adicione um novo arquivo de classe ao seu Pages diretório
   • Atalho de teclado: pressione Ctrl + Shift + A
   • Ou no Gerenciador de Soluções, vá para Projeto > Adicionar Novo Item...
2. Na caixa de diálogo Adicionar Novo Item:
   1. Selecione Classe na lista.
   2. Nomeie seu arquivo de classe: ShowMessageCommand.cs
   3. Clique em Adicionar.
3. Substitua o código de classe padrão por:

using System.Runtime.InteropServices;

namespace <ExtensionName>;

internal sealed partial class ShowMessageCommand : InvokableCommand
{
    public override string Name => "Show message";
    public override IconInfo Icon => new("\uE8A7");

    public override CommandResult Invoke()
    {
        // 0x00001000 is MB_SYSTEMMODAL, which will display the message box on top of other windows.
        _ = MessageBox(0, "I came from the Command Palette", "What's up?", 0x00001000);
        return CommandResult.KeepOpen();
    }


    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
    public static extern int MessageBox(IntPtr hWnd, string text, string caption, uint type);
}

Agora podemos adicionar este comando à lista de comandos no <ExtensionName>Page.cs arquivo:

1. No <ExtensionName>.cs, atualize o GetItems.

public override IListItem[] GetItems()
{
    var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
    var showMessageCommand = new ShowMessageCommand();
    return [
        new ListItem(command)
        {
            Title = "Open the Command Palette documentation",
        },
        new ListItem(showMessageCommand),
    ];
}

1. Implante sua extensão
2. Na Paleta de Comandos, Reload

E presto - um comando para mostrar uma caixa de mensagem!

Tipos de Páginas

Até agora, só trabalhamos com comandos que "fazem alguma coisa". No entanto, você também pode adicionar comandos que mostram páginas adicionais dentro da Paleta de Comandos. Existem dois tipos de "Comandos" na Paleta:

• InvokableCommand - São comandos que fazem alguma coisa
• IPage - São comandos que mostram alguma coisa

Como as implementações de IPage são ICommand, podem ser usadas em qualquer lugar onde se possa usar comandos. Isso significa que você pode adicioná-los à lista de comandos de nível superior ou a uma lista de comandos em uma página, ao menu de contexto de um item, etc.

Há dois tipos diferentes de páginas que você pode mostrar:

• ListPage - Esta é uma página que mostra uma lista de comandos. É com isso que temos trabalhado até agora.

• ContentPage - Esta é uma página que mostra conteúdo rico para o usuário. Isso permite que você especifique conteúdo abstrato e deixe a Paleta de Comandos se preocupar em renderizar o conteúdo em uma experiência nativa. Existem dois tipos diferentes de conteúdo suportados até agora:
  • Conteúdo de Markdown - Este é o conteúdo escrito em Markdown e é renderizado na Paleta de Comandos. Consulte MarkdownContent para obter detalhes.

• Conteúdo do formulário - Este é o conteúdo que mostra um formulário para o usuário e, em seguida, retorna os resultados desse formulário para a extensão. Estes são alimentados por cartões adaptáveis Isso é útil para obter a entrada do usuário ou exibir layouts mais complexos de informações. Consulte FormContent para obter detalhes.

Adicionar mais comandos

Comece adicionando uma nova página que mostre uma lista de comandos. Crie uma nova classe que implemente ListPage.

1. Pages Na pasta, crie uma nova classe chamadaMySecondPage
2. Atualize o código para:

using Microsoft.CommandPalette.Extensions.Toolkit;
using System.Linq;

namespace <ExtensionName>;

internal sealed partial class MySecondPage : ListPage
{
    public MySecondPage()
    {
        Icon = new("\uF147"); // Dial2
        Title = "My second page";
        Name = "Open";
    }

    public override IListItem[] GetItems()
    {
        // Return 100 CopyText commands
        return Enumerable
            .Range(0, 100)
            .Select(i => new ListItem(new CopyTextCommand($"{i}")) 
            {
                Title = $"Copy text {i}" 
            }).ToArray();
    }
}

1.Atualize o <ExtensionName>Page.cs para incluir esta nova página:

    public override IListItem[] GetItems()
    {
        OpenUrlCommand command = new("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
        return [
            new ListItem(command)
            {
                Title = "Open the Command Palette documentation",
            },
            new ListItem(new ShowMessageCommand()),
+           new ListItem(new MySecondPage()) { Title = "My second page", Subtitle = "A second page of commands" },
        ];
    }

1. Implante sua extensão
2. Na Paleta de Comandos, Reload

Agora você deve ver uma nova página em sua extensão que mostra 100 comandos que copiam um número para a área de transferência.

Próximo: Atualizar uma lista de comandos

Conteúdo relacionado

• PowerToys Utilitário Paleta de Comandos
• Visão geral da extensibilidade
• Amostras de extensão