Atualize sua extensão do Visual Studio

Se você for um desenvolvedor de extensões, este artigo pode ajudá-lo a entender como suas extensões funcionam no Visual Studio 2026. Com o Visual Studio 2026, os usuários podem instalar facilmente suas extensões do Visual Studio 2022.

Como há mínimas alterações disruptivas, atualizar a sua extensão deve ser simples. Com o Visual Studio 2026, você pode testar sua extensão existente e nos fornecer seus comentários.

Observação

As informações neste artigo dizem respeito à atualização de uma extensão do Visual Studio 2022 para trabalhar com o Visual Studio 2026.

Para obter informações sobre como atualizar uma extensão do Visual Studio 2019 para funcionar com o Visual Studio 2022 ou Visual Studio 2026, mude para a versão Visual Studio 2022 desta página usando a lista suspensa de versões, logo acima do índice.

Para instalar e testar a sua extensão:

Instale o Visual Studio 2026 mais recente.
Navegue até o Gerenciador de extensões.
Use a função Pesquisar para encontrar sua extensão.
Instale-o e confirme se ele funciona conforme o esperado.

Se sua extensão for um MSI, talvez seja necessário modificar o instalador para permitir a instalação de extensões do Visual Studio 2022 no Visual Studio 2026.

Por enquanto, não há instruções para criar extensões especificamente para o Visual Studio 2026. No entanto, você pode testar e usar extensões do Visual Studio 2022 com o Visual Studio 2026

Alterações de grande impacto

O IntegratedShell destino de instalação foi removido. Se a sua extensão tem como alvo IntegratedShell, o manifesto VSIX InstallationTarget deve ser atualizado para ter como alvo Microsoft.VisualStudio.Community. Para verificar ou alterar o InstallationTarget, abra o Manifesto VSIX no designer, selecione Alvos de Instalação. Você pode abrir o .vsixmanifest arquivo no editor de texto XML para inspecionar as InstallationTarget configurações.

Para saber mais sobre alterações de quebra , consulte Alterações de quebra para extensibilidade do Visual Studio.

Feedback e relatórios de problemas

Se encontrar problemas com as suas extensões no Visual Studio 2026, relate o problema aqui e inclua uma referência ao ticket.

Importante

Os conselhos neste artigo podem orientar os desenvolvedores na atualização de extensões que exigem grandes alterações para funcionar no Visual Studio 2019 e no Visual Studio 2022 ou posterior. Nesses casos, recomendamos que você tenha dois projetos VSIX e compilação condicional.

Muitas extensões funcionarão no Visual Studio 2019 e no Visual Studio 2022 (ou posterior) com pequenas alterações que não exigirão seguir as recomendações sobre como modernizar sua extensão neste artigo. Experimente sua extensão no Visual Studio 2022 e avalie qual opção é melhor para sua extensão.

Para obter informações sobre como atualizar uma extensão do Visual Studio 2022 para funcionar com o Visual Studio 2026, selecione a versão mais recente desta página no menu suspenso de versão, localizado logo acima do índice.

O Visual Studio 2022 é um aplicativo de 64 bits e introduz algumas alterações significativas no SDK do Visual Studio. Este artigo orienta o leitor pelas etapas necessárias para que a sua extensão funcione com a pré-visualização atual do Visual Studio 2022. Sua extensão pode estar pronta para os usuários instalarem antes que o Visual Studio 2022 atinja a disponibilidade geral.

Instalar o Visual Studio e compilar extensões

Instale o Visual Studio 2022 a partir de downloads do Visual Studio 2022.

Extensões escritas em uma linguagem .NET

O SDK do Visual Studio destinado ao Visual Studio 2022 para extensões gerenciadas está exclusivamente no NuGet:

O metapacote Microsoft.VisualStudio.Sdk (versões 17.x) traz a maioria ou todos os assemblies de referência necessários.
O pacote Microsoft.VSSDK.BuildTools (versões 17.x) deve ser referenciado a partir do seu projeto VSIX para que ele possa criar um VSIX compatível com Visual Studio 2022.

Mesmo sem referir quaisquer alterações significativas, as extensões devem ser compiladas com a plataforma Any CPU ou x64. A plataforma x86 é incompatível com o processo de 64 bits no Visual Studio 2022.

Extensões escritas em C++

O SDK do Visual Studio para extensões compiladas com C++ está disponível com o SDK do Visual Studio instalado, como de costume.

Mesmo que você não faça referência a nenhuma alteração de quebra, as extensões devem ser compiladas especificamente para o SDK do Visual Studio 2022 e para AMD64.

Extensões com código em execução

As extensões com código em execução devem ser compiladas especificamente para o Visual Studio 2022. O Visual Studio 2022 não carregará nenhuma extensão destinada a uma versão anterior do Visual Studio.

Saiba como migrar suas extensões para versões anteriores do Visual Studio para o Visual Studio 2022:

Modernize seus projetos.
Refatore seu código-fonte em um projeto compartilhado para permitir o direcionamento do Visual Studio 2022 e versões mais antigas.
Adicione um projeto VSIX direcionado ao Visual Studio 2022 e uma tabela de remapeamento de pacotes/assemblies.
Faça os ajustes de código necessários.
Teste sua extensão do Visual Studio 2022.
Publique sua extensão do Visual Studio 2022.

Extensões sem código em execução

As extensões que não contêm nenhum código em execução (por exemplo, modelos de projeto ou item) não precisam seguir as etapas anteriores, incluindo a produção de dois VSIXs distintos.

Em vez disso, modifique um VSIX para que seu source.extension.vsixmanifest arquivo declare dois destinos de instalação:

<Installation>
   <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[15.0,17.0)">
      <ProductArchitecture>x86</ProductArchitecture>
   </InstallationTarget>
   <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0,18.0)">
      <ProductArchitecture>amd64</ProductArchitecture>
   </InstallationTarget>
</Installation>

Você pode ignorar as etapas neste artigo sobre como usar projetos compartilhados e vários VSIXs. Você pode prosseguir com os testes.

Observação

Se você estiver criando uma nova extensão do Visual Studio usando o Visual Studio 2022 e quiser direcionar também o Visual Studio 2019 ou uma versão anterior, consulte este guia.

Tarefas do MSBuild

Se você criar tarefas do MSBuild, esteja ciente de que, no Visual Studio 2022, é provável que elas sejam carregadas em um processo de MSBuild.exe de 64 bits. Se sua tarefa requer um processo de 32 bits para ser executada, consulte Configurar destinos e tarefas para garantir que o MSBuild carregue sua tarefa em um processo de 32 bits.

Modernize seu projeto VSIX

Antes de adicionar suporte ao Visual Studio 2022 à sua extensão, é altamente recomendável limpar e modernizar seu projeto existente:

Migrar do packages.config para o PackageReference.

Substitua quaisquer referências diretas de assembly do SDK do Visual Studio por PackageReference itens:

-<Reference Include="Microsoft.VisualStudio.OLE.Interop" />
+<PackageReference Include="Microsoft.VisualStudio.OLE.Interop" Version="..." />

Sugestão

Você pode substituir muitas referências de assembly por apenas umaPackageReference instância para o metapacote:

-<Reference Include="Microsoft.VisualStudio.OLE.Interop" />
-<Reference Include="Microsoft.VisualStudio.Interop" />
-<Reference Include="Microsoft.VisualStudio.Interop.8.0" />
+<PackageReference Include="Microsoft.VisualStudio.Sdk" Version="..." />

Certifique-se de escolher versões de pacote compatíveis com a versão mínima do Visual Studio que pretende utilizar.

Alguns assemblies que não são exclusivos do SDK do Visual Studio (por exemplo, Newtonsoft.Json.dll) podem ter sido descobertos por meio de uma referência simples <Reference Include="Newtonsoft.Json" /> antes do Visual Studio 2022. Mas, no Visual Studio 2022, eles exigem uma referência de pacote. A razão é que alguns diretórios de runtime e SDK do Visual Studio foram removidos do caminho de pesquisa de assembly padrão no MSBuild.

Ao alternar de referências diretas de assembly para referências de pacote NuGet, poderá obter referências de assembly adicionais e pacotes de analyzers porque o NuGet instala automaticamente o encerramento transitivo de dependências. Isto geralmente está bem, mas pode resultar em avisos adicionais durante o processo de compilação. Analise esses avisos e resolva o maior número possível. Considere o uso de regiões no código #pragma warning disable <id> para suprimir avisos que não podem ser resolvidos.

Usar projetos compartilhados para multisegmentação

Projetos compartilhados são um tipo de projeto que foi introduzido no Visual Studio 2015. Projetos compartilhados no Visual Studio permitem que arquivos de código-fonte sejam compartilhados entre vários projetos e compilados de forma diferente usando símbolos de compilação condicional e conjuntos exclusivos de referências.

O Visual Studio 2022 requer um conjunto distinto de assemblies de referência de todas as versões anteriores do Visual Studio. Portanto, recomendamos que você use projetos compartilhados para direcionar convenientemente sua extensão para o Visual Studio 2022, versões anteriores e versões posteriores. Essa técnica lhe dará compartilhamento de código, mas referências distintas.

No contexto das extensões do Visual Studio, você pode ter um projeto VSIX para Visual Studio 2022 e posterior, e um projeto VSIX para Visual Studio 2019 e anteriores. Cada um desses projetos conteria apenas uma source.extension.vsixmanifest instância e as referências do pacote ao SDK 16.x ou ao SDK 17.x. Esses projetos VSIX também teriam uma referência de projeto compartilhado para um novo projeto compartilhado que hospedará todo o seu código-fonte que pode ser compartilhado entre as duas versões do Visual Studio.

Esta seção pressupõe que você já tenha um projeto VSIX destinado ao Visual Studio 2019 e que você queira que sua extensão funcione no Visual Studio 2022.

Você pode concluir todas estas etapas usando o Visual Studio 2019:

Se você ainda não tiver feito isso, modernize seus projetos para facilitar as etapas posteriores neste processo de atualização.
Adicione um novo projeto compartilhado à sua solução para cada projeto existente que faz referência ao SDK do Visual Studio. Clique com o botão direito do mouse na solução e selecione Adicionar>Novo Projeto.
Na caixa de diálogo Adicionar um novo projeto , procure projeto compartilhado e selecione o modelo Projeto compartilhado .
Adicione uma referência de cada projeto de referência do SDK do Visual Studio ao seu homólogo de projeto compartilhado.
Mova todo o código-fonte (incluindo arquivos .cs e .resx ) de cada projeto de referência ao SDK do Visual Studio para sua contraparte de projeto compartilhado. Deixe o arquivo source.extension.vsixmanifest no projeto VSIX.
Mova arquivos de metadados (por exemplo, notas de versão, licença e ícones) e arquivos VSCT para um diretório compartilhado. Em seguida, adicione-os como arquivos vinculados ao projeto VSIX. Observe que o diretório compartilhado é separado do projeto compartilhado.
- Para arquivos de metadados, defina Build Action como Content. Defina Incluir no VSIX como True.
- Para arquivos VSCT, defina Build Action como VSCTCompile. Defina Incluir no VSIX como Falso.
  
  Se o Visual Studio reclamar que essa configuração não é suportada, você pode alterar manualmente a ação de compilação descarregando o projeto e alterando Content para VSCTCompile:
```
-<Content Include="..\SharedFiles\VSIXProject1Package.vsct">
-  <Link>VSIXProject1Package.vsct</Link>
-</Content>
+<VSCTCompile Include="..\SharedFiles\VSIXProject1Package.vsct">
+  <Link>VSIXProject1Package.vsct</Link>
+  <ResourceName>Menus.ctmenu</ResourceName>
+</VSCTCompile>
```
Crie seu projeto para confirmar que você não introduziu nenhum erro.

Seu projeto agora está pronto para adicionar suporte ao Visual Studio 2022.

Adicionar um alvo do Visual Studio 2022

Esta seção pressupõe que você concluiu as etapas para fatorar sua extensão do Visual Studio com projetos compartilhados.

Adicione suporte ao Visual Studio 2022 à sua extensão usando as etapas a seguir. Você pode concluí-los usando o Visual Studio 2019.

Adicione um novo projeto VSIX à sua solução. Este projeto terá como alvo o Visual Studio 2022. Remova qualquer código-fonte que veio com o modelo, mas mantenha o arquivo source.extension.vsixmanifest .
Em seu novo projeto VSIX, adicione uma referência ao mesmo projeto compartilhado que seu Visual Studio 2019-targeting VSIX referencia.
Verifique se o novo projeto VSIX é compilado corretamente. Talvez seja necessário adicionar referências para corresponder ao seu projeto VSIX original para resolver quaisquer erros do compilador.
Para extensões gerenciadas do Visual Studio, atualize suas referências de pacote de 16.x (ou anterior) para as versões de pacote 17.x em seu arquivo de projeto direcionado ao Visual Studio 2022. Use o Gerenciador de Pacotes NuGet ou edite diretamente o arquivo de projeto:
```
-<PackageReference Include="Microsoft.VisualStudio.SDK" Version="16.0.206" />
+<PackageReference Include="Microsoft.VisualStudio.SDK" Version="17.0" />
-<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="16.10.32" />
+<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="17.0" />
```
As versões mostradas no código anterior são apenas para demonstração. No seu código, use as versões disponíveis no site do NuGet.

Em muitos casos, as IDs do pacote foram alteradas. Para obter uma lista de alterações no Visual Studio 2022, consulte a tabela de mapeamento de pacote/assembly.

As extensões escritas em C++ ainda não têm um SDK disponível para compilar.
Para projetos C++, as extensões devem ser compiladas para AMD64. Para extensões gerenciadas, considere alterar seu projeto de criação para qualquer CPU para direcionamento x64. Essa alteração garante que, no Visual Studio 2022, sua extensão sempre seja carregada em um processo de 64 bits. Qualquer CPU também é adequada, mas pode produzir avisos se referir a binários nativos exclusivos para x64.

Qualquer dependência que sua extensão possa ter em um módulo nativo terá que ser atualizada de uma imagem x86 para uma imagem AMD64.

Edite o seu ficheiro source.extension.vsixmanifest para refletir o alvo do Visual Studio 2022. Defina o <InstallationTarget> para indicar o Visual Studio 2022. Defina o elemento ProductArchitecture para indicar uma carga útil AMD64.

<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0,18.0)">
   <ProductArchitecture>amd64</ProductArchitecture>
</InstallationTarget>

Importante

No Visual Studio 2019, o designer para este arquivo não expõe o novo ProductArchitecture elemento. Você precisa usar um editor XML para fazer essa alteração. Para acessar o editor XML, vá para Solution Explorer e selecione o comando Abrir com .

O ProductArchitecture elemento é crítico. O Visual Studio 2022 não instalará sua extensão sem ele.

Elemento	Valor	Description
`ProductArchitecture`	`x86`, `amd64`	As plataformas que este VSIX suporta. Não diferencia maiúsculas de minúsculas. Use uma plataforma por elemento e um elemento por `InstallationTarget` instância. Para versões de produto inferiores a 17.0, o valor padrão é `x86` e pode ser omitido. Para as versões do produto 17.0 e posteriores, esse elemento é necessário e não há nenhum valor padrão. Para o Visual Studio 2022, o único conteúdo válido para esse elemento é `amd64`.

Faça quaisquer outros ajustes necessários em source.extension.vsixmanifest para corresponder ao que se destina ao Visual Studio 2019 (se houver).

Se você estiver publicando duas versões de sua extensão que visam cada uma uma versão diferente do Visual Studio, certifique-se de que a ID do VSIX no Identity elemento do manifesto é diferente para cada extensão.

Neste ponto, você tem uma extensão VSIX direcionada ao Visual Studio 2022. Você deve compilar o seu projeto VSIX direcionado para o Visual Studio 2022 e resolver quaisquer falhas de compilação que surgirem. Se você não tiver quebras de compilação em seu projeto VSIX direcionado para Visual Studio 2022, parabéns! Você está pronto para o teste.

Lidar com alterações de API que causam ruptura

Alterações de API de quebra podem exigir atualizações para o código executado em versões anteriores do Visual Studio. Para obter dicas sobre como atualizar seu código, consulte Quebrando alterações de API no Visual Studio 2022.

Quando você estiver adaptando seu código, recomendamos que você use a compilação condicional. Seu código pode continuar a oferecer suporte a versões anteriores do Visual Studio enquanto adiciona suporte para o Visual Studio 2022.

Quando tiver a sua extensão direcionada ao Visual Studio 2022 pronta, avance para os testes.

Usar símbolos de compilação condicional

Se você quiser usar o mesmo código-fonte, mesmo o mesmo arquivo, para o Visual Studio 2022 e versões anteriores, talvez seja necessário usar a compilação condicional. Em seguida, você pode bifurcar seu código para se adaptar às alterações de quebra. A compilação condicional é um recurso das linguagens C#, Visual Basic e C++. Ele pode ser usado para compartilhar a maioria dos códigos, acomodando APIs divergentes em locais específicos.

Para obter mais informações sobre o uso de diretivas de pré-processador e símbolos de compilação condicional, consulte Diretivas de pré-processador C#.

Seus projetos destinados a versões anteriores do Visual Studio precisarão de um símbolo de compilação condicional. Esse símbolo pode ser usado para bifurcar o código para usar as diferentes APIs. Você pode definir o símbolo de compilação condicional na página de propriedades do projeto:

Captura de tela que mostra a caixa para inserir um símbolo de compilação condicional.

Certifique-se de definir o símbolo de compilação para Todas as configurações. Por padrão, o símbolo inserido pode se aplicar a apenas uma configuração.

Técnicas de C#

Você pode usar seu símbolo de compilação como uma diretiva de pré-processador (#if), conforme mostrado no código a seguir. Em seguida, pode criar um fork do seu código para lidar com uma alteração incompatível entre as versões do Visual Studio.

    Guid myGuid = new Guid("{633FBA02-719B-40E7-96BF-0899767CD104}");
    uint myFlags = 0;
    IVsShell shell = await AsyncServiceProvider.GlobalProvider.GetServiceAsync<SVsShell, IVsShell>();
#if Dev16
    shell.LoadUILibrary(myGuid, myFlags, out uint ptrLib);
#else
    shell.LoadUILibrary(myGuid, myFlags, out IntPtr ptrLib);
#endif

Em alguns casos, você pode usar var para evitar nomear o tipo e evitar a necessidade de #if regiões. O trecho anterior também pode ser escrito como:

    Guid myGuid = new Guid("{633FBA02-719B-40E7-96BF-0899767CD104}");
    uint myFlags = 0;
    IVsShell shell = await AsyncServiceProvider.GlobalProvider.GetServiceAsync<SVsShell, IVsShell>();
    shell.LoadUILibrary(myGuid, myFlags, out var ptrLib);

Quando estiveres a usar a sintaxe #if, repara como podes usar a lista suspensa para o contexto de serviço de linguagem, para alterar o destaque de sintaxe. A outra lista suspensa ajuda o serviço de idioma a concentrar a atenção numa versão de destino do Visual Studio para esta extensão em comparação com outra.

Captura de tela que mostra a compilação condicional em um projeto compartilhado.

O XAML não tem pré-processador para permitir a personalização de conteúdo com base em símbolos de pré-processador. Talvez seja necessário copiar e manter duas páginas XAML cujo conteúdo difere entre o Visual Studio 2022 e versões anteriores.

Em alguns casos, uma referência a um tipo que existe em assemblies distintos no Visual Studio 2022 e em versões anteriores ainda pode ser representada em um arquivo XAML. Remova o namespace que faz referência ao assembly:

-xmlns:vsui="clr-namespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.14.0"
-Value="{DynamicResource {x:Static vsui:TreeViewColors.SelectedItemActiveBrushKey}}"
+Value="{DynamicResource TreeViewColors.SelectedItemActiveBrushKey}"

Teste a sua extensão

Para testar uma extensão destinada ao Visual Studio 2022, você precisa ter o Visual Studio 2022 instalado. Você não poderá executar extensões de 64 bits em versões anteriores do Visual Studio.

Você pode usar o Visual Studio 2022 para criar e testar suas extensões, sejam elas destinadas ao Visual Studio 2022 ou a uma versão anterior. Quando você abre um projeto VSIX do Visual Studio 2022, uma instância experimental do Visual Studio é aberta.

É altamente recomendável que você teste com cada versão do Visual Studio que você deseja que a extensão suporte.

Publique sua extensão

Você adicionou um alvo do Visual Studio 2022 à sua extensão e o testou. Agora você está pronto para publicar a extensão para que o mundo a admire.

Mercado do Visual Studio

Publicar sua extensão no Visual Studio Marketplace é uma ótima maneira de fazer com que novos usuários encontrem e instalem sua extensão. Se sua extensão se destina exclusivamente ao Visual Studio 2022 ou também a versões mais antigas do Visual Studio, o Marketplace está lá para apoiá-lo.

No futuro, o Marketplace permitirá que você carregue vários VSIXs para apenas uma listagem do Marketplace. Em seguida, você pode carregar seu VSIX direcionado para Visual Studio 2022 e um VSIX para uma versão anterior do Visual Studio. Seus usuários obterão automaticamente o VSIX certo para a versão do Visual Studio que instalaram, quando estiverem usando o gerenciador de extensões do Visual Studio.

Instalador personalizado

Se você criar um arquivo MSI ou EXE para instalar sua extensão e gerar vsixinstaller.exe para instalar (parte de) sua extensão, saiba que o instalador VSIX no Visual Studio 2022 foi atualizado. Os desenvolvedores precisam usar a versão do instalador VSIX que vem com o Visual Studio 2022 para instalar extensões para essa versão do Visual Studio.

O instalador do VSIX no Visual Studio 2022 também instala extensões aplicáveis destinadas a versões anteriores do Visual Studio que existem com o Visual Studio 2022 na mesma máquina.

Você pode compartilhar sua extensão através de uma LAN ou de qualquer outra forma. Se você segmentar o Visual Studio 2022 e versões anteriores, precisará compartilhar seus vários VSIXs individualmente. Dê a eles nomes de arquivos (ou coloque-os em pastas exclusivas) que ajudam seus usuários a saber qual VSIX instalar com base na versão do Visual Studio que eles instalaram.

Dependências

Se o seu VSIX especificar outros VSIXs como dependências através do elemento <dependency>, cada VSIX referenciado precisará ser instalado nos mesmos destinos e arquiteturas de produto que o seu VSIX. Se um VSIX dependente não oferecer suporte à instalação de destino do Visual Studio, seu VSIX falhará.

Não há problema em o VSIX dependente suportar mais alvos e arquiteturas do que o seu, mas não menos. Essa restrição significa que a abordagem de implantação e distribuição de um VSIX com dependências deve refletir a de seus dependentes.

Perguntas e Respostas

P: Minha extensão não requer nenhuma alteração de interoperabilidade porque apenas fornece dados (por exemplo, modelos). Posso criar uma única extensão que também inclua o Visual Studio 2022?

R: Sim! Consulte Extensões sem código em execução para obter informações sobre isso.

P: Uma dependência do NuGet está trazendo assemblies de interoperabilidade velhas e provocando conflitos de classes. O que devo fazer?

A: Adicione a seguinte linha ao seu ficheiro .csproj para evitar assemblies duplicados:

    <PackageReference Include="<Name of offending assembly>" ExcludeAssets="compile" PrivateAssets="all" />

Esse código impedirá que as referências de pacote importem a versão antiga do assembly de outras dependências.

P: Meus comandos e teclas de atalho pararam de funcionar no Visual Studio depois que mudei meus arquivos de origem para um projeto compartilhado. O que devo fazer?

R: A etapa 2.4 do exemplo do Image Optimizer mostra como adicionar arquivos VSCT como itens vinculados para que eles sejam compilados em seu arquivo VSCT.

Siga um exemplo passo a passo, ImageOptimizer, com links para o projeto e alterações de código para cada etapa.

Last updated on 2025-11-11

Partilhar via