Sua primeira extensão do Visual Studio

Este artigo explica algumas etapas simples para colocar sua primeira extensão do Visual Studio em execução. Uma extensão do Visual Studio é escrita utilizando o .NET Framework e C#. Se você já for um desenvolvedor .NET, verá que escrever extensões é semelhante a escrever a maioria dos outros programas e bibliotecas .NET.

A extensão que você irá escrever hoje adiciona um comando que insere um novo GUID no editor de texto quando executado. É simples, útil e fornece uma boa introdução aos vários aspectos do desenvolvimento de extensão.

Se você for um aprendiz visual, confira este breve vídeo de alguém seguindo o tutorial.

Antes de começar a escrever sua primeira extensão do Visual Studio (é fácil, prometo!), verifique se você tem as ferramentas necessárias.

Criar o projeto

Há vários modelos de projeto para escolher, portanto, você deseja fazer a escolha certa. Os modelos usados neste kit de ferramentas da comunidade têm o moniker (Comunidade) no nome.

O modelo VSIX Project w/Command (Community) vem com um comando integrado, facilitando o início do desenvolvimento. Esse é um ótimo ponto de partida para a maioria das extensões. Se você sabe que deseja uma janela de ferramentas, use o modelo Projeto VSIX com Janela de Ferramentas (Comunidade). Ele também tem um comando para abrir a janela de ferramentas.

Use os modelos Projeto VSIX Vazio (Comunidade) ou Projeto VSIX (Comunidade) para extensões MEF-only ou outros cenários avançados.

Desta vez, você selecionará o modelo do VsIX Project w/Command (Community), conforme mostrado na captura de tela abaixo.

Caixa de diálogo Novo Projeto mostrando modelos de projeto VSIX.

Depois de selecionar o modelo de projeto, você precisa dar um nome ao projeto. Chame-o InsertGuid.

Configure seu novo projeto.

Depois de apertar o botão Criar , você deve acabar com um Projeto VSIX básico com esta aparência:

Novos arquivos e pastas de projeto.

Arquivos importantes

Vamos examinar os arquivos mais importantes.

InsertGuidPackage.cs é o que é chamado de classe Package. Seu InitializeAsync(...) método é chamado pelo Visual Studio para inicializar sua extensão. É a partir daqui que você adiciona ouvintes de eventos e registra comandos, janelas de ferramentas, configurações e outras coisas.

source.extension.vsixmanifest é o arquivo de manifesto para sua extensão. Ele contém metadados, como título e descrição, mas também informações sobre o que a extensão contém.

VSCommandTable.vsct é um arquivo XML em que comandos e associações de chave são definidos declarativamente, para que possam ser registrados no Visual Studio.

Commands/MyCommand.cs é o manipulador de comandos para o comando definido no arquivo VSCommandTable.vsct . Ele controla o que acontece quando o comando é executado clicando no botão.

Modificando o comando

Primeiro, você deseja verificar se o comando tem o nome, o ícone e a posição certos no sistema de menus do Visual Studio.

Abra o arquivo VSCommandTable.vsct e localize um <Group> e um <Button>. Observe como o botão especifica o grupo como seu pai e o pai do grupo é o menu embutido VSMainMenu/Tools.

Para a sua extensão, você deseja que o botão de comando Inserir GUID esteja localizado no menu principal Editar. Portanto, você vai realocar o grupo para o menu Editar. Substitua As Ferramentas por Editar da seguinte maneira:

<Group guid="InsertGuid" id="MyMenuGroup" priority="0x0600">
  <Parent guid="VSMainMenu" id="Edit"/>
</Group>

Você obtém o IntelliSense completo para os posicionamentos para facilitar a localização certa.

IntelliSense pai do VSCT.

A <Button> também precisa de atualização. Você associará a ele um novo ícone, atualizando o atributo id do elemento <Icon> para PasteAppend. Atualize o <ButtonText> texto com um nome bom e descritivo e atualize o <LocCanonicalName> nome técnico do seu comando. Esse é o nome mostrado aos usuários quando eles atribuem atalhos de teclado personalizados ao seu comando na caixa de diálogo Teclado do Ambiente > de Opções > de Ferramentas>.

<Button guid="InsertGuid" id="MyCommand" priority="0x0100" type="Button">
  <Parent guid="InsertGuid" id="MyMenuGroup" />
  <Icon guid="ImageCatalogGuid" id="PasteAppend" />
  <CommandFlag>IconIsMoniker</CommandFlag>
  <Strings>
    <ButtonText>Insert GUID</ButtonText>
    <LocCanonicalName>.Edit.InsertGuid</LocCanonicalName>
  </Strings>
</Button>

Observação

Sempre comece o <LocCanonicalName> com um caractere de ponto. Ele garante que nenhum outro texto seja automaticamente pré-adicionado e que o ponto não será mostrado.

Você pode usar os milhares de ícones disponíveis na biblioteca de imagens do Visual Studio e até mesmo obter uma visualização mostrada no IntelliSense:

Agora, você atualizou o nome, o ícone e o local do nosso comando e é hora de escrever algum código para inserir o guid no editor de texto.

Abra o arquivo /Commands/MyCommand.cs e modifique-o para inserir um novo guid quando executado:

using System;
using Community.VisualStudio.Toolkit;
using EnvDTE;
using Microsoft.VisualStudio.Shell;
using Task = System.Threading.Tasks.Task;

namespace InsertGuid
{
    [Command(PackageIds.MyCommand)]
    internal sealed class MyCommand : BaseCommand<MyCommand>
    {
        protected override async Task ExecuteAsync(OleMenuCmdEventArgs e)
        {
            await Package.JoinableTaskFactory.SwitchToMainThreadAsync();
            DocumentView docView = await VS.Documents.GetActiveDocumentViewAsync();
            if (docView?.TextView == null) return;
            SnapshotPoint position = docView.TextView.Caret.Position.BufferPosition;
            docView.TextBuffer?.Insert(position, Guid.NewGuid().ToString()); 
        }
    }
}

Você está usando o objeto VS para obter a exibição de texto do editor ativo e, em seguida, inserir o guid na posição do cursor do buffer de texto. VS é um objeto estático que fornece acesso aos elementos da interface do usuário do IDE do Visual Studio; consulte sua definição em VS.cs no repositório GitHub do Kit de Ferramentas da Comunidade DO VSIX.

Observação

Você verá await JoinableTaskFactory.SwitchToMainThreadAsync() e ThreadHelper.ThrowIfNotOnUIThread() em muitos lugares neste kit de ferramentas da comunidade. Eles lidam com as práticas recomendadas de comutação de threads e você não precisa saber quando e como usá-las neste momento - avisos do compilador com Correções de Código (lâmpadas) facilitam isso.

O primeiro rascunho da nossa extensão agora está concluído e é hora de testá-lo.

Execução e depuração

Executar sua extensão é tão fácil quanto executar qualquer outro projeto do .NET. Basta pressionar F5 para executar com o depurador anexado ou Ctrl+F5 para execução sem.

Isso iniciará a Instância Experimental do Visual Studio com sua extensão instalada. A Instância Experimental é sua versão regular do Visual Studio, mas com configurações e extensões separadas instaladas. Ajuda a manter as coisas separadas.

Quando a Instância Experimental for iniciada, você deverá ver o comando Inserir GUID no menu Editar principal.

Insira o comando GUID localizado no menu Editar principal.

Abra qualquer arquivo baseado em texto e execute o comando para inserir um novo guid. É isso!

Resumo

Agora você criou sua primeira extensão que adiciona um botão de comando ao menu principal e interage com o editor de texto quando executado.

Parabéns!!

Você pode encontrar o código dessa extensão no repositório de exemplos.

Last updated on 2025-12-12

Compartilhar via