Crie a sua primeira extensão para o Visual Studio

Este documento é um início rápido que mostra como criar a sua primeira extensão usando o VisualStudio.Extensibilidade. A extensão fica fora do processo, ou seja, fora do processo do Visual Studio.

Prerequisites

  • Recomenda-se o Visual Studio 2026, versão 18.11 ou posterior, com a carga de trabalho de desenvolvimento de extensões do Visual Studio. Para versões anteriores, o VisualStudio.Extensibility requer o Visual Studio 2022 versão 17.9 ou posterior.

Criar o projeto de extensão

Utilize o modelo Modern VSIX Project e selecione VisualStudio.Extensibility (Out-Of-Process) em Tipo de Extensão. O modelo é VSSDK por defeito, por isso seleciona a opção de fora de processo para este quickstart.

Siga as instruções em Criar uma extensão com o modelo Modern VSIX Project para os passos do assistente e as opções do SDK do projeto.

Versões anteriores do Visual Studio

Use o modelo VisualStudio.Extensibility Project para criar um novo projeto de extensibilidade.

Captura de ecrã do modelo de VSExtensibilidade.

Neste ponto, está pronto para começar a expandir o Visual Studio adicionando comandos e componentes do editor à sua extensão.

A classe Extensão

O modelo cria uma classe que estende Extension ↗. Esta classe é a primeira que é instanciada quando a sua extensão é carregada. Nesse InitializeServices ↗ método, pode adicionar os seus próprios serviços à coleção de serviços para os disponibilizar para injeção de dependências.

[VisualStudioContribution]
internal class ExtensionEntrypoint : Extension
{
    public override ExtensionConfiguration ExtensionConfiguration => new()
    {
        Metadata = new(
            id: "MyExtension.abc123",
            version: this.ExtensionAssemblyVersion,
            publisherName: "My Company",
            displayName: "My Extension"),
    };

    protected override void InitializeServices(IServiceCollection serviceCollection)
    {
        base.InitializeServices(serviceCollection);

        // You can configure dependency injection here by adding services to the serviceCollection.
    }
}

Também pode ver o VisualStudioContribution ↗ atributo que é usado para marcar componentes de extensão que devem ser consumidos pelo Visual Studio. Este atributo pode ser aplicado a classes que implementam IVisualStudioContributionClass ↗ ou propriedades estáticas de um tipo que implementa IVisualStudioContributionProperty ↗ .

Adiciona o teu primeiro comando

O modelo cria Command1.cs como o seu primeiro processador de comandos, que pode usar como ponto de partida. Como queremos fazer com que o Visual Studio reconheça este comando, e a classe Command ↗ implementa IVisualStudioContributionClass ↗, o comando é marcado com o atributo VisualStudioContribution.

[VisualStudioContribution]
internal class Command1 : Command
{

O comando tem uma propriedade de configuração chamada CommandConfiguration ↗ , que define o seu nome de visualização, ícone e localização no Extensions menu.

    public override CommandConfiguration CommandConfiguration => new("%MyExtension.Command1.DisplayName%")
    {
        // Use this object initializer to set optional parameters for the command. The required parameter,
        // displayName, is set above. DisplayName is localized and references an entry in .vsextension\string-resources.json.
        Icon = new(ImageMoniker.KnownValues.Extension, IconSettings.IconAndText),
        Placements = new[] { CommandPlacement.KnownPlacements.ExtensionsMenu },
    };

As propriedades de configuração são avaliadas pelo compilador C# ao construir a extensão e os seus valores são guardados como metadados de extensão para que o Visual Studio possa lê-los sem carregar a assembly da extensão. Por esta razão, as propriedades de configuração têm restrições adicionais em comparação com as propriedades normais (por exemplo, devem ser apenas de leitura).

Pode ver que o nome de exibição do comando é "%MyExtension.Command1.DisplayName%", que faz referência à MyExtension.Command1.DisplayName cadeia no .vsextension/string-resources.json ficheiro, permitindo que esta cadeia seja localizada.

Quando o comando é executado, o Visual Studio invoca o método ExecuteCommandAsync ↗ onde pode colocar um ponto de interrupção. Podes usar o context argumento ou this.Extensibility para interagir com o Visual Studio.

Por exemplo, um controlador de comandos pode ser o seguinte:

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    await this.Extensibility.Shell().ShowPromptAsync(
        "Hello from an extension!", 
        PromptOptions.OK, 
        cancellationToken);
}

Para mais informações sobre como adicionar comandos, consulte a secção Comandos .

Depurar a sua extensão

  1. Certifica-te de que o teu projeto de extensão está selecionado como projeto de arranque no Visual Studio e carrega em F5 para iniciar a depuração.

  2. Ao premir F5, constróis a tua extensão e implementa-la na instância experimental da versão do Visual Studio que estás a usar. O depurador deve ser ligado assim que a sua extensão estiver carregada.

  3. Pode encontrar o novo comando no Extensions menu, como mostrado na imagem seguinte:

    Captura de ecrã a mostrar o comando de exemplo em Visual Studio.

    Captura de ecrã a mostrar comando de exemplo.

Passos seguintes