Migrar do packages.config para o PackageReference

O Visual Studio 2017 Versão 15.7 e posterior oferece suporte à migração de um projeto do formato de gerenciamento de packages.config para o formato PackageReference .

Benefícios do uso do PackageReference

• Centralize todas as dependências do projeto num só lugar: tal como as referências de projeto a projeto e as referências de assembly, as referências de pacote NuGet (usando o nó PackageReference) são geridas diretamente nos ficheiros do projeto em vez de usar um ficheiro separado packages.config.
• Visão organizada de dependências de nível superior: ao contrário de packages.config, PackageReference lista apenas os pacotes NuGet que você instalou diretamente no projeto. Como resultado, a interface do usuário do Gerenciador de Pacotes NuGet e o arquivo de projeto não estão sobrecarregados com dependências de nível inferior.
• Melhorias de desempenho: Ao usar PackageReference, os pacotes são mantidos na pasta global-packages (conforme descrito em Gerenciando os pacotes globais e pastas de cache , em vez de em uma packages pasta dentro da solução. Como resultado, PackageReference tem um desempenho mais rápido e consome menos espaço em disco.
• Controle preciso sobre dependências e fluxo de conteúdo: o uso dos recursos existentes do MSBuild permite que você faça referência condicional a um pacote NuGet e escolha referências de pacote por estrutura de destino, configuração, plataforma ou outros pivôs.

Limitações

• NuGet PackageReference não está disponível no Visual Studio 2015 e versões anteriores. Os projetos migrados só podem ser abertos no Visual Studio 2017 e posterior.
• A migração não está disponível atualmente para projetos C++ e ASP.NET.
• Alguns pacotes podem não ser totalmente compatíveis com PackageReference. Para obter mais informações, consulte Problemas de compatibilidade de pacotes.

Além disso, existem algumas diferenças na forma como PackageReferences funciona em comparação com packages.config. Por exemplo, Restrições em versões de atualização não é suportado por PackageReference, mas PackageReference adiciona suporte para versões flutuantes.

Problemas conhecidos

1. A Migrate packages.config to PackageReference... opção não está disponível no menu de contexto do botão direito do rato

Questão

Quando um projeto é aberto pela primeira vez, o NuGet pode não ter sido inicializado até que uma operação do NuGet seja executada. Isso faz com que a opção de migração não apareça no menu de contexto do botão direito do mouse em packages.config ou References.

Solução

Execute qualquer uma das seguintes ações do NuGet:

• Abra a UI do Gerenciador de Pacotes - Clique com o botão direito do mouse em References e selecione Manage NuGet Packages...
• Abra o Console do Gerenciador de Pacotes - De Tools > NuGet Package Manager, selecione Package Manager Console
• Executar restauração do NuGet - Clique com o botão direito do mouse no nó da solução no Gerenciador de Soluções e selecione Restore NuGet Packages
• Crie o projeto que também desencadeia a restauração do NuGet

Agora você deve ser capaz de ver a opção de migração. Observe que essa opção não é suportada e não aparecerá para os tipos de projeto ASP.NET e C++.

Etapas de migração

1. Abra uma solução que contenha projeto usando packages.config.

2. No Gerenciador de Soluções, clique com o botão direito do mouse no nó Referências ou no packages.config arquivo e selecione Migrar packages.config para PackageReference....

3. O migrador analisa as referências de pacotes NuGet do projeto e tenta categorizá-las em dependências de nível superior (pacotes NuGet que você instalou diretamente) e dependências transitivas (pacotes que foram instalados como dependências de pacotes de nível superior).

   Observação

   PackageReference suporta restauração transitiva de pacotes e resolve dependências dinamicamente, o que significa que as dependências transitivas não precisam ser instaladas explicitamente.

4. (Opcional) Você pode optar por tratar um pacote NuGet classificado como uma dependência transitiva como uma dependência de nível superior selecionando a opção de nível superior para o pacote. Essa opção é definida automaticamente para pacotes que contêm ativos que não fluem transitivamente (aqueles nas pastas build, buildCrossTargeting, contentFiles, ou analyzers) e aqueles marcados como dependência de desenvolvimento (developmentDependency = "true").

5. Analise todos os problemas de compatibilidade de pacotes.

6. Selecione OK para iniciar a migração.

7. No final da migração, o Visual Studio fornece um relatório com um caminho para o backup, a lista de pacotes instalados (dependências de nível superior), uma lista de pacotes referenciados como dependências transitivas e uma lista de problemas de compatibilidade identificados no início da migração. O relatório é salvo na pasta de backup.

8. Valide se a solução é compilada e executada. Se você encontrar problemas, registre um problema no GitHub.

Como reverter para packages.config

1. Feche o projeto migrado.

2. Copie o arquivo de projeto e packages.config do backup (normalmente <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) para a pasta do projeto. Exclua a pasta obj se ela existir no diretório raiz do projeto.

3. Abra o projeto.

4. Abra a Consola do Gestor de Pacotes usando o comando Ferramentas > Gestor de Pacotes NuGet > Consola do Gestor de Pacotes do menu.

5. Execute o seguinte comando no Console:

   update-package -reinstall
   

Criar um pacote após a migração

Quando a migração estiver concluída, recomendamos que você copie os metadados do pacote de um .nuspec arquivo para as propriedades do MSBuild e, em seguida, você pode usar msbuild -t:pack para criar o pacote. Se você estiver usando o Visual Studio 2022 ou anterior, também precisará instalar o pacote NuGet.Build.Tasks.Pack. A partir do Visual Studio 2026, o pacote é incorporado ao MSBuild.

Problemas de compatibilidade de pacotes

Alguns aspetos que foram suportados no packages.config não são suportados em PackageReference. O migrador analisa e deteta esses problemas. Qualquer pacote que tenha um ou mais dos seguintes problemas pode não se comportar como esperado após a migração.

Os scripts "install.ps1" são ignorados quando o pacote é instalado após a migração

• Descrição: Com PackageReference, install.ps1 e uninstall.ps1 scripts PowerShell não são executados durante a instalação ou desinstalação de um pacote.

• Impacto potencial: os pacotes que dependem desses scripts para configurar algum comportamento no projeto de destino podem não funcionar conforme o esperado.

Os ativos de "conteúdo" não estão disponíveis quando o pacote é instalado após a migração

• Descrição: Os ativos na pasta de content um pacote não são suportados com PackageReference e são ignorados. PackageReference adiciona suporte para contentFiles ter melhor suporte transitivo e conteúdo compartilhado.

• Impacto potencial: Os ativos em content não são copiados para o projeto, e o código do projeto que depende da presença desses ativos requer refatoração.

As transformações XDT não são aplicadas quando o pacote é instalado após a atualização

• Descrição: As transformações XDT não são suportadas com PackageReference e .xdt os arquivos são ignorados ao instalar ou desinstalar um pacote.

• Impacto potencial: as transformações XDT não são aplicadas a nenhum arquivo XML do projeto, mais comumente, web.config.install.xdt e web.config.uninstall.xdt, o que significa que o arquivo do web.config projeto não é atualizado quando o pacote é instalado ou desinstalado.

Os assemblies na raiz lib são ignorados quando o pacote é instalado após a migração

• Descrição: Com o PackageReference, assemblies presentes na raiz da pasta são ignorados se não houver uma subpasta específica para o framework de destino. O NuGet procura uma subpasta correspondente ao identificador do framework de destino (TFM) correspondente ao framework de destino do projeto e instala os assemblies correspondentes no projeto.

• Impacto potencial: os pacotes que não têm uma subpasta correspondente ao moniker da estrutura de destino (TFM) correspondente à estrutura de destino do projeto podem não se comportar como esperado após a transição ou falhar na instalação durante a migração.

Encontrou um problema? Denuncie!

Se você tiver um problema com a experiência de migração, registre um problema no repositório NuGet GitHub.