Partilhar via

Tornar as extensões compatíveis com o Visual Studio 2019/2017 e o Visual Studio 2015

Este documento explica como fazer projetos de extensibilidade de ida e volta entre o Visual Studio 2015 e o Visual Studio 2019 ou o Visual Studio 2017. Depois de concluir essa atualização, um projeto poderá abrir, compilar, instalar e executar no Visual Studio 2015 e no Visual Studio 2019 ou 2017. Como referência, algumas extensões que podem fazer uma viagem de ida e volta entre o Visual Studio 2015 e o Visual Studio 2019 ou 2017 podem ser encontradas no exemplos de extensibilidade do VSSDK.

Se você pretende criar apenas no Visual Studio 2019/2017, mas deseja que o VSIX de saída seja executado no Visual Studio 2015 e no Visual Studio 2019/2017, consulte o documento de migração Extension.

Observação

Devido a alterações no Visual Studio entre versões, algumas coisas que funcionaram em uma versão não funcionam em outra. Certifique-se de que os recursos que você está tentando acessar estão disponíveis em ambas as versões ou a extensão terá resultados inesperados.

Aqui está um esboço das etapas que você concluirá neste documento para fazer uma viagem de ida e volta a um VSIX:

  1. Importe pacotes NuGet corretos.

  2. Atualizar Manifesto da Extensão

    • Destino da instalação
    • Pré-requisitos

  3. Atualizar CSProj:

    • Atualização <MinimumVisualStudioVersion>.
    • Adicione a propriedade <VsixType>.
    • Adicione a propriedade de depuração ($DevEnvDir) 3 vezes.
    • Adicione condições para importar ferramentas de compilação e alvos.

  4. Construir e testar

Configuração do ambiente

Este documento pressupõe que você tenha o seguinte instalado em sua máquina:

  • Visual Studio 2015 com o VSSDK instalado
  • Visual Studio 2019 ou 2017 com o workload de Extensibilidade instalado

É altamente recomendável iniciar essa atualização com o Visual Studio 2015, em vez do Visual Studio 2019 ou 2017. O principal benefício do desenvolvimento no Visual Studio 2015 é garantir que você não faça referência a assemblies que não estão disponíveis no Visual Studio 2015. Se você fizer o desenvolvimento no Visual Studio 2019 ou 2017, há um risco de que você possa introduzir uma dependência em um assembly que só existe no Visual Studio 2019 ou 2017.

Certifique-se de que não há referência a project.json

Mais adiante neste documento, inseriremos declarações de importação condicional no arquivo *.csproj. Isso não funcionará se suas referências do NuGet estiverem armazenadas no project.json. Como tal, é aconselhável mover todas as referências do NuGet para o arquivo packages.config. Se o seu projeto contiver um arquivo project.json:

  • Tome nota das referências em project.json.
  • No Gerenciador de Soluções, exclua o arquivo project.json do projeto. Isso exclui o arquivo project.json e o remove do projeto.
  • Adicione as referências do NuGet de volta ao projeto:
    • Clique com o botão direito do mouse no Solução e escolha Gerenciar pacotes NuGet para a solução.
    • O Visual Studio cria automaticamente o arquivo packages.config para você.

Observação

Se o seu projeto continha pacotes EnvDTE, talvez seja necessário adicioná-los clicando com o botão direito do mouse em Referências, selecionando Adicionar referência e adicionando a referência apropriada. Usar pacotes NuGet pode criar erros ao tentar criar seu projeto.

Adicionar ferramentas de compilação apropriadas

Precisamos garantir que adicionamos as ferramentas de compilação que nos permitirão compilar e depurar de forma adequada. A Microsoft criou um assembly para isso chamado Microsoft.VisualStudio.Sdk.BuildTasks.

Para criar e implantar um VSIXv3 no Visual Studio 2015 e 2019/2017, você precisará dos seguintes pacotes NuGet:

Versão Ferramentas Construídas
Visual Studio 2015 Microsoft.VisualStudio.Sdk.BuildTasks.14.0
Visual Studio 2019 ou 2017 Microsoft.VSSDK.BuildTool

Para tal:

  • Adicione o pacote NuGet Microsoft.VisualStudio.Sdk.BuildTasks.14.0 ao seu projeto.
  • Se o seu projeto não contiver Microsoft.VSSDK.BuildTools, adicione-o.
  • Verifique se a versão Microsoft.VSSDK.BuildTools é 15.x ou superior.

Atualizar o manifesto da extensão

1. Objetivos de instalação

Precisamos dizer ao Visual Studio quais versões segmentar para criar um VSIX. Normalmente, essas referências são para a versão 14.0 (Visual Studio 2015), versão 15.0 (Visual Studio 2017) ou versão 16.0 (Visual Studio 2019). No nosso caso, queremos construir um VSIX que instalará uma extensão para ambos, então precisamos direcionar ambas as versões. Se você quiser que seu VSIX construa e instale em versões anteriores à 14.0, isso pode ser feito definindo o número da versão anterior; no entanto, a versão 10.0 e anteriores não são mais suportadas.

  • Abra o arquivo de source.extension.vsixmanifest no Visual Studio.
  • Abra a guia Alvos de Instalação.
  • Altere o intervalo de versões para [14.0, 17.0]. O '[' diz ao Visual Studio para incluir o 14.0 e todas as versões anteriores a ele. O ')' indica ao Visual Studio para incluir todas as versões até, mas não incluindo, a versão 17.0.
  • Salve todas as alterações e feche todas as instâncias do Visual Studio.

Imagem de Destinos de Instalação

2. Adicionar pré-requisitos ao ficheiro de extensão extension.vsixmanifest

Precisamos do Editor Principal do Visual Studio como pré-requisito. Abra o Visual Studio e use o designer de manifesto atualizado para inserir os pré-requisitos.

Para fazer isso manualmente:

  • Navegue até o diretório do projeto no Explorador de Arquivos.
  • Abra o ficheiro de extension.vsixmanifest com um editor de texto.
  • Adicione a seguinte tag:
<Prerequisites>
    <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[15.0,16.0)" DisplayName="Visual Studio core editor" />
</Prerequisites>
  • Salve e feche o arquivo.

Observação

Talvez seja necessário editar manualmente a versão de pré-requisito para garantir que ela seja compatível com todas as versões do Visual Studio 2019 ou 2017. Isso ocorre porque o designer irá inserir a versão mínima como sua versão atual do Visual Studio (por exemplo, 15.0.26208.0). No entanto, como outros usuários podem ter uma versão anterior, você desejará editá-la manualmente para 15.0.

Neste ponto, seu arquivo de manifesto deve ter esta aparência:

Exemplo de pré-requisitos

Modificar o arquivo de projeto (myproject.csproj)

É altamente recomendável ter uma referência a um .csproj modificado aberto ao executar esta etapa. Pode encontrar vários exemplos aqui. Selecione qualquer exemplo de extensibilidade, encontre o ficheiro .csproj para referência e execute os seguintes passos.

  • Navegue até o diretório do projeto no Explorador de Arquivos .
  • Abra o arquivo de myproject.csproj com um editor de texto.

1. Atualize o MinimumVisualStudioVersion

  • Defina a versão mínima do visual studio como $(VisualStudioVersion) e adicione uma instrução condicional para ela. Adicione essas tags se elas não existirem. Certifique-se de que as tags estão definidas como abaixo:
<VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">14.0</VisualStudioVersion>
<MinimumVisualStudioVersion>$(VisualStudioVersion)</MinimumVisualStudioVersion>

2. Adicione a propriedade VsixType.

  • Adicione a seguinte tag <VsixType>v3</VsixType> a um grupo de propriedades.

Observação

Recomenda-se adicioná-lo abaixo da tag <OutputType></OutputType>.

3. Adicione as propriedades de depuração

  • Adicione o seguinte grupo de propriedades:
<PropertyGroup>
    <StartAction>Program</StartAction>
    <StartProgram>$(DevEnvDir)devenv.exe</StartProgram>
    <StartArguments>/rootsuffix Exp</StartArguments>
</PropertyGroup>
  • Exclua todas as instâncias do exemplo de código seguinte do arquivo .csproj e de qualquer arquivo .csproj.user.
<StartAction>Program</StartAction>
<StartProgram>$(ProgramFiles)\Microsoft Visual Studio 14.0\Common7\IDE\devenv.exe</StartProgram>
<StartArguments>/rootsuffix Exp</StartArguments>

4. Adicione condições às importações de ferramentas de compilação

  • Adicione instruções condicionais adicionais aos marcadores <import> que têm uma referência a Microsoft.VSSDK.BuildTools. Insira '$(VisualStudioVersion)' != '14.0' And na frente da declaração de condição. Essas instruções aparecerão no cabeçalho e rodapé do arquivo csproj.

Por exemplo:

<Import Project="packages\Microsoft.VSSDK.BuildTools.15.0.26201…" Condition="'$(VisualStudioVersion)' != '14.0' And Exists(…" />
  • Adicione instruções condicionais adicionais às marcas <import> que têm Microsoft.VisualStudio.Sdk.BuildTasks.14.0. Insira '$(VisualStudioVersion)' == '14.0' And na frente da declaração de condição. Essas instruções aparecerão no cabeçalho e rodapé do arquivo csproj.

Por exemplo:

<Import Project="packages\Microsoft.VisualStudio.Sdk.BuildTasks.14.0.14.0…" Condition="'$(VisualStudioVersion)' == '14.0' And Exists(…" />
  • Adicione instruções condicionais adicionais às etiquetas <Error> com uma referência a Microsoft.VSSDK.BuildTools. Faça isso inserindo '$(VisualStudioVersion)' != '14.0' And na frente da declaração condicional. Essas instruções aparecerão no rodapé do arquivo csproj.

Por exemplo:

<Error Condition="'$(VisualStudioVersion)' != '14.0' And Exists('packages\Microsoft.VSSDK.BuildTools.15.0.26201…" />
  • Adicione instruções condicionais adicionais às marcas <Error> que têm Microsoft.VisualStudio.Sdk.BuildTasks.14.0. Insira '$(VisualStudioVersion)' == '14.0' And na frente da declaração de condição. Essas instruções aparecerão no rodapé do arquivo csproj.

Por exemplo:

<Error Condition="'$(VisualStudioVersion)' == '14.0' And Exists('packages\Microsoft.VisualStudio.Sdk.BuildTasks.14.0.14.0…" />
  • Salve o arquivo csproj e feche-o.
    • Observe que, se você estiver usando mais de um projeto na solução, defina este projeto como Projeto de Inicialização usando "Definir como Projeto de Inicialização" no menu de contexto do projeto). Isso garante que o Visual Studio reabra este projeto depois de descarregá-lo.

Testar as instalações da extensão no Visual Studio 2015 e Visual Studio 2019 ou 2017

Neste ponto, seu projeto deve estar pronto para criar um VSIXv3 que possa ser instalado no Visual Studio 2015 e no Visual Studio 2017.

  • Abra seu projeto no Visual Studio 2015.
  • Construa o seu projeto e confirme na saída que um VSIX é construído com sucesso.
  • Navegue até o diretório do projeto.
  • Abra a pasta \bin\Debug.
  • Clique duas vezes no arquivo VSIX e instale sua extensão no Visual Studio 2015 e Visual Studio 2019/2017.
  • Certifica-te de que tu podes ver a extensão em Ferramentas>Extensões e Atualizações na seção Instalada.
  • Tente executar/usar a extensão para verificar se ela funciona.

Encontre um VSIX

Observação

Se o seu projeto parar de responder com a mensagem ao abrir o arquivo, force o encerramento do Visual Studio, navegue até o diretório do projeto, mostre as pastas ocultas e elimine a pasta .vs.