Atualizar sua extensão do Visual Studio

Se você for um desenvolvedor de extensão, este artigo poderá 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á poucas mudanças disruptivas, atualizar sua extensão deve ser simples. Com o Visual Studio 2026, você pode testar sua extensão existente e fornecer seus comentários.

Nota

As informações neste artigo referem-se à 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 Visual Studio 2022 ou Visual Studio 2026, alterne para a versão do Visual Studio 2022 desta página usando a lista suspensa de versão, logo acima da tabela de conteúdos.

Para instalar e testar sua extensão:

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

Se sua extensão for uma 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 da falha

O IntegratedShell destino de instalação foi removido. Se a extensão for direcionada IntegratedShell, o InstallationTarget no manifesto do VSIX deverá ser atualizado para direcionar Microsoft.VisualStudio.Community. Para verificar ou alterar o InstallationTarget, abra o Manifesto VSIX no designer e selecione Instalar Destinos. Você pode abrir o .vsixmanifest arquivo no editor de texto XML para inspecionar as InstallationTarget configurações.

Para saber mais sobre alterações significativas, consulte Alterações significativas para Extensibilidade do Visual Studio.

Relatórios de comentários e problemas

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

Importante

O conselho neste artigo pode 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 os conselhos 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, alterne para a versão mais recente desta página usando o menu suspenso de versão, logo acima do sumário.

O Visual Studio 2022 é um aplicativo de 64 bits e apresenta algumas alterações significativas no SDK do Visual Studio. Este artigo explica as etapas necessárias para que sua extensão funcione com a versão prévia atual do Visual Studio 2022. Sua extensão pode estar pronta para que os usuários instalem antes que o Visual Studio 2022 atinja a disponibilidade geral.

Instalar o Visual Studio e compilar extensões

Instale o Visual Studio 2022 dos 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 de que você vai precisar.
O pacote Microsoft.VSSDK.BuildTools (versões 17.x) deve ser referenciado do seu projeto VSIX para que ele possa criar um VSIX compatível com o Visual Studio 2022.

Mesmo que você não faça referência a nenhuma alteração interruptiva, as extensões precisarão ser compiladas com a configuração Qualquer CPU ou a plataforma 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 alterações significativas, 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 precisam ser compiladas especificamente para o Visual Studio 2022. O Visual Studio 2022 não carregará nenhuma extensão direcionada 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:

Modernizar seus projetos.
Refatorar seu código-fonte em um projeto compartilhado para permitir a compatibilidade com o Visual Studio 2022 e versões mais antigas.
Adicione um projeto VSIX direcionado ao Visual Studio 2022 e uma tabela de remapeamento de pacote/assembly.
Faça os ajustes de código necessários.
Teste sua extensão do Visual Studio 2022.
Publicar sua extensão do Visual Studio 2022.

Extensões sem executar código

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

Em vez disso, modifique o VSIX para que seu arquivo source.extension.vsixmanifest 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 prossiga para os testes.

Nota

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

Tarefas do MSBuild

Se você criar tarefas do MSBuild, lembre-se de que, no Visual Studio 2022, é provável que elas sejam carregadas em um processo de MSBuild.exe de 64 bits. Se sua tarefa exigir 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.

Modernizar seu projeto VSIX

Antes de adicionar o suporte do Visual Studio 2022 à sua extensão, recomendamos que você limpe e modernize seu projeto existente:

Migrar de packages.config para PackageReference.

Substitua todas as referências diretas ao assembly do SDK do Visual Studio por itens de PackageReference:

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

Dica

Você pode substituir muitas referências ao 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 selecionar versões de pacote que correspondam à versão mínima do Visual Studio que você está visando.

Alguns assemblies que não são exclusivos do SDK do Visual Studio (por exemplo, Newtonsoft.Json.dll) podem ter sido detectáveis por meio de uma referência <Reference Include="Newtonsoft.Json" /> simples antes do Visual Studio 2022. Mas, no Visual Studio 2022, eles exigem uma referência de pacote. O motivo é 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 de assembly direto para referências de pacote NuGet, você poderia selecionar referências de assembly e pacotes de analisador adicionais porque o NuGet instala automaticamente o fechamento transitivo de dependências. Isso geralmente é OK, mas pode resultar em avisos adicionais durante o build. Trabalhe com esses avisos e resolva o máximo deles que conseguir. Considere usar regiões de #pragma warning disable <id> no código para suprimir avisos que você não pode resolver.

Usar projetos compartilhados para vários direcionamentos

Projetos compartilhados são um tipo de projeto que foi introduzido no Visual Studio 2015. Projetos compartilhados no Visual Studio permitem que os arquivos de código-fonte sejam compartilhados entre vários projetos e sejam 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 fornecerá 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 anterior. Cada um desses projetos conteria apenas uma instância de source.extension.vsixmanifest e o pacote faz referência 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 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 direcionado ao Visual Studio 2019 e que você deseja que sua extensão funcione no Visual Studio 2022.

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

Se ainda não fez isso, modernize seus projetos para facilitar as etapas mais adiante nesse processo de atualização.
Adicione um novo projeto compartilhado à sua solução para cada projeto existente que faça 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, a seguir, selecione o modelo Projeto Compartilhado.
Adicione uma referência de cada projeto de referência do SDK do Visual Studio ao seu equivalente de projeto compartilhado.
Mova todo o código-fonte (incluindo .cs e arquivos .resx) de cada projeto de referência do SDK do Visual Studio para seu equivalente 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 a Ação do Build como Conteúdo. Defina Incluir no VSIX como True.
- Para arquivos VSCT, defina a Ação do Build como VSCTCompile. Defina Incluir no VSIX como False.
  
  Se o Visual Studio reclamar que essa configuração não tem suporte, você poderá alterar manualmente a ação de build 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

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

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

Adicione um novo projeto VSIX à sua solução. Este projeto terá como destino 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 o VSIX visando o Visual Studio 2019 menciona.
Verifique se o novo projeto VSIX é compilado corretamente. Talvez seja necessário adicionar referências para corresponder ao projeto VSIX original para resolver erros do compilador.
Para extensões gerenciadas do Visual Studio, atualize suas referências de pacote de 16.x (ou anteriores) para as versões do pacote 17.x no seu arquivo de projeto visando o 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 versões que estejam disponíveis no site do NuGet.

Em muitos casos, as IDs do pacote foram alteradas. Para uma lista de mudanças no Visual Studio 2022, consulte a tabela de mapeamento de pacotes/assemblies .

As extensões escritas no 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, pense em alterar o projeto de "compilar para Qualquer CPU" para "visar 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 funciona, mas pode produzir avisos se você fizer referência a qualquer binário nativo somente x64.

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

Edite seu arquivo source.extension.vsixmanifest para refletir que está visando o Visual Studio 2022. Defina a tag <InstallationTarget> para indicar o Visual Studio 2022. Defina o elemento ProductArchitecture para indicar uma carga AMD64.

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

Importante

No Visual Studio 2019, o designer desse arquivo não expõe o novo elemento ProductArchitecture. Você precisa usar um editor XML para fazer essa alteração. Para acessar o editor XML, acesse o Gerenciador de Soluções e selecione o comando Abrir com.

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

Elemento	Valor	Descrição
`ProductArchitecture`	`x86`, `amd64`	As plataformas compatíveis com esse VSIX. Não diferencia maiúsculas de minúsculas. Use uma plataforma por elemento e um elemento por instância `InstallationTarget`. Para versões de produto menores que 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 todos os outros ajustes necessários em source.extension.vsixmanifest para corresponder ao que tem como destino o Visual Studio 2019 (se houver).

Se você estiver publicando duas versões da extensão direcionadas a uma versão diferente do Visual Studio, verifique se a ID do VSIX no elemento Identity do manifesto é diferente para cada extensão.

Neste ponto, você tem uma extensão VSIX direcionada ao Visual Studio 2022. Você deve criar seu projeto VSIX visando o Visual Studio 2022 e solucionar todas as quebras de build que aparecem. Se você não tiver quebras de build no seu projeto VSIX visando o Visual Studio 2022, parabéns! Você está pronto para teste.

Resolva as alterações interruptivas de API

As alterações interruptivas de API podem requerer atualizações no código que era executado em versões anteriores do Visual Studio. Para obter dicas sobre como atualizar seu código, consulte Alterações de API radicais no Visual Studio 2022.

Ao adaptar seu código, recomendamos que você use a compilação condicional. Seu código pode continuar a dar suporte a versões anteriores do Visual Studio, ao mesmo tempo em que adiciona suporte para o Visual Studio 2022.

Quando você receber sua compilação de extensão visando o Visual Studio 2022, prossiga 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 criar um fork do seu código para adaptá-lo às alterações interruptivas. A compilação condicional é um recurso das linguagens C#, Visual Basic e C++. Ele pode ser usado para compartilhar a maioria dos códigos ao acomodar 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 como 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 o símbolo de compilação como uma diretiva de pré-processador (#if), conforme mostrado no código a seguir. Em seguida, você poderá criar um fork do seu código para lidar com uma alteração interruptiva 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ê poderá usar var para evitar denominar o tipo e evitar a necessidade de regiões #if. O snippet 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);

Ao usar a sintaxe #if, observe como você pode usar a lista suspensa para o contexto de serviço de linguagem para alterar o realce da sintaxe. A outra lista suspensa ajuda o serviço de linguagem a concentrar a atenção em uma versão de destino do Visual Studio para essa 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 nenhum 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 versões anteriores ainda pode ser representável 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 sua extensão

Para testar uma extensão direcionada 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 se elas são direcionadas 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 testar com cada versão do Visual Studio que você deseja que a extensão dê 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 e permitir que o mundo a admire.

Visual Studio Marketplace

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

No futuro, o Marketplace permitirá que você carregue vários VSIXs em apenas uma listagem do Marketplace. Em seguida, você pode carregar seu VSIX direcionado ao Visual Studio 2022 e um VSIX para uma versão anterior do Visual Studio. Os usuários obterão automaticamente o VSIX certo para a versão do Visual Studio instalada 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 executar vsixinstaller.exe para instalar (parte de) sua extensão, saiba que o instalador do 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 nessa versão do Visual Studio.

O instalador VSIX no Visual Studio 2022 também instala extensões aplicáveis direcionadas a versões anteriores do Visual Studio que existem com o Visual Studio 2022 no mesmo computador.

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

Dependências

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

Não há problema se o VSIX dependente der suporte a mais destinos e arquiteturas que os seus, mas não menos. Essa restrição significa que a abordagem de implantação e distribuição de um VSIX com dependências deve espelhar a de seus dependentes.

Perguntas e Respostas

Q: 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! Confira Extensões sem executar código para obter informações sobre isso.

P: Uma dependência do NuGet está trazendo assemblies de interoperabilidade antigos e causando conflito de classes. O que devo fazer?

R: Adicione a seguinte linha ao seu arquivo .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.

Q: Meus comandos e teclas de acesso 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 da amostra do Otimizador de Imagens mostra como adicionar arquivos VSCT como itens vinculados para que sejam compilados dentro do 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

Compartilhar via