Atualizar uma extensão do Visual Studio para Visual Studio 2022

Artigo
08/15/2023

Importante

O conselho neste artigo pode orientar os desenvolvedores na migração de extensões que exigem alterações importantes para funcionar no Visual Studio 2019 e no Visual Studio 2022. 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 com pequenas alterações que não exigirão seguir os conselhos sobre a modernização da extensão neste artigo. Experimente sua extensão no Visual Studio 2022 e avalie qual opção é melhor para sua extensão.

O Visual Studio 2022 é um aplicativo de 64 bits e introduz algumas alterações recentes no SDK do Visual Studio. Este artigo orienta você pelas etapas necessárias para fazer sua extensão funcionar com a 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 do seu projeto VSIX para que ele possa criar um VSIX compatível com Visual Studio 2022.

Mesmo que você não faça referência a nenhuma alteração de quebra, as extensões devem ser compiladas com a plataforma Qualquer 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 no 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 pacote/assembly.
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 são necessárias para 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 o teste.

Observação

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

tarefas MSBuild

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

Modernize seu projeto VSIX

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

Migre de packages.config para 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="..." />

Dica

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 que correspondam à versão mínima do Visual Studio que você está segmentando.

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. O motivo é que alguns diretórios SDK e de tempo de execução 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, você pode pegar referências de assembly adicionais e pacotes de analisador porque o NuGet instala automaticamente o fechamento transitivo de dependências. Isso geralmente é OK, mas pode resultar em avisos adicionais durante a compilação. Trabalhe com esses avisos e resolva o máximo que puder. Considere o uso de regiões no código #pragma warning disable <id> para suprimir avisos que você não pode resolver.

Usar projetos compartilhados para multidirecionamento

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 compilar 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 versões anteriores. Cada um desses projetos conteria apenas uma source.extension.vsixmanifest instância e as referências de pacote ao SDK 16.x ou ao SDK 17.x. Esses projetos VSIX também teriam uma referência de projeto compartilhada 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 destinado ao Visual Studio 2019 e que deseja 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 à sua contraparte de projeto compartilhado.
Mova todo o código-fonte (incluindo arquivos .cs e .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ção de Criação como Conteúdo. Defina Include in VSIX como True.
- Para arquivos VSCT, defina Build Action como VSCTCompile. Defina Include in VSIX como False.
  
  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 destino 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 do 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 as referências de pacote de 16.x (ou anterior) para as versões de pacote 17.x no arquivo de projeto de destino do 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. Em seu código, use versões disponíveis no site do NuGet.

Em muitos casos, as IDs de 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 criar para Qualquer CPU para direcionar 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 é boa, 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 terá que ser atualizada de uma imagem x86 para uma imagem AMD64.

Edite o arquivo source.extension.vsixmanifest para refletir a segmentação do Visual Studio 2022. Defina a marca para indicar o <InstallationTarget> Visual Studio 2022. Defina o ProductArchitecture elemento 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 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 Gerenciador de Soluções 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	Descrição
`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 menores que 17.0, o valor padrão é `x86` e pode ser omitido. Para 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 àquele que se destina ao Visual Studio 2019 (se houver).

Se você estiver publicando duas versões de sua extensão que cada um direciona 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 criar seu projeto VSIX direcionado ao Visual Studio 2022 e trabalhar em todas as quebras de compilação que aparecerem. Se você não tiver quebras de compilação em seu projeto VSIX direcionado ao Visual Studio 2022, parabéns! Você está pronto para o teste.

Lidar com alterações de API de quebra

Quebrar alterações de API pode exigir atualizações para o código que executado em versões anteriores do Visual Studio. Para obter dicas sobre como atualizar seu código, consulte Breaking API changes in Visual Studio 2022.

Ao adaptar 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 você obtiver sua compilação de extensão direcionada ao Visual Studio 2022, prossiga para o teste.

Usar símbolos de compilação condicional

Se você quiser usar o mesmo código-fonte, até 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 do código enquanto acomoda APIs divergentes em lugares 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 então 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:

Screenshot that shows the box for entering a conditional compilation symbol.

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, você pode bifurcar seu código para lidar com uma alteração de quebra entre 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 estiver usando a sintaxe, observe como você pode usar a lista suspensa para o contexto do serviço de idioma para alterar o #if realce da sintaxe. A outra lista suspensa ajuda o serviço de idioma a concentrar a atenção em uma versão do Visual Studio de destino para essa extensão em relação a outra.

Screenshot that shows conditional compilation in a shared project.

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 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}"

Testar 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, se elas se destinam 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 para suportar.

Publicar sua extensão

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

Visual Studio Marketplace

Publicar sua extensão no Visual Studio Marketplace é uma ótima maneira de fazer com que novos usuários localizem 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 de destino ao Visual Studio 2022 e um VSIX para uma versão anterior do Visual Studio. Seus usuários obterão automaticamente o VSIX correto 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 da) 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 VSIX no Visual Studio 2022 também instala extensões aplicáveis que visam versões anteriores do Visual Studio que existem com o Visual Studio 2022 no mesmo computador.

Você pode compartilhar sua extensão através de uma LAN ou de qualquer outra forma. Se você destinar 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 ajudem seus 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 <dependency> elemento , cada VSIX referenciado precisará ser instalado nos mesmos destinos e arquiteturas de produto que o 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 destinos e arquiteturas do que o seu, apenas 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

P: Minha extensão não requer alterações 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 executar código para obter informações sobre isso.

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

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

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

R: A etapa 2.4 do exemplo do Otimizador de Imagem 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.