Compartilhar via

Reinstalar e atualizar pacotes NuGet no Visual Studio

Às vezes, as referências de pacote podem falhar dentro de um projeto do Visual Studio. Desinstalar e reinstalar a mesma versão do pacote geralmente restaura as referências à ordem de trabalho. Atualizar um pacote, que instala uma versão atualizada, também pode resolver o problema. Este artigo descreve como reinstalar e atualizar pacotes NuGet para abordar referências de pacotes quebrados e projetos interrompidos.

Observação

As diretrizes neste artigo se aplicam somente a projetos que usam o formato de gerenciamento packages.config. Para projetos PackageReference, uma operação de restauração corrige automaticamente referências quebradas.

Cenários comuns

Em seu projeto do Visual Studio, aqui estão alguns cenários comuns em que você pode encontrar referências de pacotes quebradas.

Scenario Description Resolução
Referências quebradas após a restauração do pacote Abra o projeto no Visual Studio e restaure os pacotes NuGet, mas as referências de pacotes quebradas permanecem. Para corrigir as referências, tente reinstalar cada pacote separadamente.
Projeto interrompido devido a arquivos excluídos Os arquivos de pacote excluídos (ausentes) fazem com que o projeto seja interrompido. O NuGet não impede a exclusão de itens que você adiciona de pacotes. Pode ser fácil modificar inadvertidamente o conteúdo instalado de um pacote e interromper seu projeto. Para restaurar seu projeto, tente reinstalar os pacotes afetados.
Projeto interrompido após a atualização do pacote Uma atualização de pacote interrompe seu projeto. Atualizações complementares para um pacote de dependência geralmente causam esse tipo de falha. Para restaurar o estado funcional anterior da dependência, tente reinstalar o pacote dependente específico.
Referências interrompidas após o redirecionamento ou atualização do projeto Um processo de redirecionamento ou atualização do projeto causa referências de pacotes quebradas. Depois de redirecionar seu projeto, o NuGet mostrará um erro de build. Crie pacotes de lista de avisos que talvez precisem ser reinstalados. Ou, depois de atualizar seu projeto, o NuGet mostrará um erro no log de atualização do projeto. O arquivo de log lista pacotes que talvez precisem ser reinstalados. Para resolver problemas devido a uma alteração na estrutura de destino, tente reinstalar um ou mais pacotes.
Alterações de pacote em desenvolvimento Os autores de pacotes geralmente precisam reinstalar a mesma versão de um pacote que estão desenvolvendo no momento para testar suas alterações. O Console do Gerenciador de Pacotes NuGet no Visual Studio fornece opções flexíveis para atualizar e reinstalar pacotes. Para reinstalar um pacote em desenvolvimento, você pode usar o Update-Package -reinstall comando.

Opções de implementação

Você tem várias opções de como atualizar e reinstalar pacotes NuGet. Os métodos comuns incluem opções de interface do usuário do Gerenciador de Pacotes NuGet, o Console do Gerenciador de Pacotes NuGet e a CLI do NuGet (Interface de Linha de Comando).

Interface do usuário do Gerenciador de Pacotes

Além da interface do console, a interface do usuário do Gerenciador de Pacotes também fornece opções de menu para instalar, atualizar e desinstalar pacotes.

  • Para atualizar um pacote, abra a guia Atualizações , escolha um ou mais pacotes e selecione Atualizar.

  • Para reinstalar um pacote, primeiro desinstale o pacote e instale-o novamente. Abra a guia Instalado , escolha um pacote e registre seu nome e, em seguida, selecione Desinstalar. Alterne para a guia Procurar e pesquise o nome do pacote, escolha o pacote e selecione Instalar.

Console do Gerenciador de Pacotes

Você pode acessar o Console do Gerenciador de Pacotes em Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.

  • Para atualizar um pacote, o Console do Gerenciador de Pacotes fornece o Update-Package comando.

  • Para reinstalar um pacote, você pode usar o mesmo comando com o -reinstall parâmetro. Essa abordagem é a opção mais fácil, se for compatível com sua configuração.

Para obter mais informações, consulte as seções de considerações sobre o comandoUpdate-Package e a reinstalação do pacote .

CLI do NuGet

A CLI nuget.exedo NuGet é o utilitário de linha de comando para Windows que fornece todos os recursos do NuGet.

  • Para atualizar um pacote instalado, execute o nuget update comando.

  • Para reinstalar todos os pacotes NuGet, exclua a pasta do pacote e execute o nuget install comando.

  • Para reinstalar um único pacote, exclua a pasta do pacote e execute o nuget install <id> comando, em que o <id> argumento é a ID do pacote específico.

Observação

Para a CLI do dotnet, o procedimento equivalente não é necessário. Quando você executa o dotnet restore comando, a CLI do dotnet usa o NuGet para determinar dependências e baixar todos os pacotes NuGet necessários. Para obter mais informações, consulte Restaurar pacotes NuGet com a CLI do dotnet.

Restrições em versões de atualização

Por padrão, reinstalar ou atualizar um pacote sempre instala a versão mais recente disponível na origem do pacote. No entanto, projetos que usam o packages.config formato de gerenciamento podem limitar especificamente o intervalo de versão do pacote NuGet permitido.

Suponha que seu aplicativo funcione apenas com a versão 1.x de um pacote, mas não com a versão 2.0 ou posterior, devido a uma grande alteração na API do pacote. Para garantir que seu aplicativo funcione conforme o esperado, você deseja restringir atualizações de pacote NuGet somente para versões 1.x. A limitação ajuda a evitar atualizações acidentais que podem interromper seu aplicativo.

Para definir uma restrição, abra o packages.config arquivo em um editor de texto. Localize a dependência que você deseja limitar e adicione o atributo com o allowedVersions intervalo de versão desejado.

O exemplo a seguir mostra como restringir as atualizações à versão 1.x definindo o allowedVersions atributo como [1,2):

<?xml version="1.0" encoding="utf-8"?>
<packages>
    <package id="ExamplePackage" version="1.1.0" allowedVersions="[1,2)" />

    <!-- ... -->
</packages>

Em todos os casos, use a notação descrita no controle de versão do pacote.

comando Update-Package

O comando Update-Package no Console do Gerenciador de Pacotes é a maneira mais fácil de reinstalar um pacote e corrigir referências quebradas. No entanto, essa abordagem não é utilizável em todos os cenários. Você pode usar o comando para atualizar um pacote instalado, mas não para fazer uma instalação inicial. Se você tentar atualizar ou reinstalar um pacote que ainda não está instalado na configuração, o comando retornará um erro. Examine a seção considerações de reinstalação do pacote antes de trabalhar com o comando.

Atualizar pacotes em um projeto ou solução usando PackageReference sempre atualiza para a versão mais recente do pacote (excluindo pacotes de pré-lançamento). Os projetos que usam o packages.config formato de gerenciamento podem limitar as versões de atualização, conforme descrito em Restrições em versões de atualização.

As seções a seguir fornecem exemplos para trabalhar com o comando.

Opções de pacote de reinstalação

Aqui está um uso básico do comando para fazer uma reinstalação. Para identificar um pacote NuGet específico, você pode usar o parâmetro opcional -Id .

# Reinstall the package named <package_name>
Update-Package -Id <package_name> –reinstall

Usar o Update-Package comando é mais fácil do que remover um pacote e, em seguida, tentar localizar o mesmo pacote na galeria do NuGet com a mesma versão.

Opções de pacote de atualização

O mesmo comando sem o -reinstall parâmetro atualiza um pacote para uma versão mais recente, se aplicável. O comando retornará um erro se o pacote especificado ainda não estiver instalado em um projeto.

# Update the package named <package_name>
Update-Package <package_name>

Opções de projeto e solução

Por padrão, o Update-Package comando afeta todos os projetos em uma solução. Para limitar a ação a um projeto específico, use o -ProjectName parâmetro. Forneça o nome do projeto como ele aparece no Gerenciador de Soluções do Visual Studio.

O comando a seguir reinstala um pacote NuGet para um projeto específico em sua solução. O nome do pacote NuGet específico a ser reinstalado é fornecido no <package_name> parâmetro.

# Reinstall the package named <package_name> in MyProject only
Update-Package <package_name> -ProjectName MyProject -reinstall

Se você quiser reinstalar todos os pacotes em seu projeto, use o -ProjectName parâmetro não especificando nenhum pacote específico. Você pode seguir essa mesma abordagem para atualizar os pacotes em seu projeto, conforme mostrado neste exemplo:

# Update all packages in MyProject only
Update-Package -ProjectName MyProject

Para atualizar todos os pacotes em uma solução, basta usar o Update-Package comando sozinho sem outros argumentos ou parâmetros.

Importante

Certifique-se de usar a seguinte forma do comando com cuidado. O processo de comando pode levar um tempo considerável para executar todas as atualizações.

# Update all packages in all projects in the solution
Update-Package

Considerações sobre a reinstalação do pacote

Se você pretende usar o Update-Package comando para reinstalar pacotes, examine as considerações a seguir para garantir a compatibilidade com seu cenário de configuração.

  • Pacotes e suas dependências podem não dar suporte a uma estrutura de destino de projeto redirecionada.
  • Quando o requireReinstallation atributo é definido como true, o Visual Studio emite avisos de build para pacotes afetados.
  • A reinstalação de um pacote e restrições de versão podem introduzir problemas de compatibilidade de versões de dependências.
  • A reinstalação de um pacote específico pode fazer com que os pacotes dependentes sejam interrompidos.

O pacote não dá suporte à estrutura de destino do projeto

Se você redirecionar sua estrutura de destino do projeto, um ou mais pacotes poderão não dar suporte à nova configuração de destino.

Normalmente, a reinstalação de um pacote com o Update-Package –reinstall <package_name> comando funciona. Um pacote instalado em uma estrutura de destino antiga é desinstalado e o mesmo pacote é instalado na nova estrutura de destino do projeto.

Em alguns casos, um pacote pode não dar suporte à nova estrutura de destino. Aqui estão alguns dos problemas que você pode encontrar:

  • Se um pacote der suporte a PCLs (bibliotecas de classes portáteis) e você redirecionar o projeto para uma combinação de plataformas que não são mais compatíveis com o pacote, as referências ao pacote podem estar ausentes após a reinstalação.

  • Esse problema pode aparecer para pacotes que você usa diretamente ou para pacotes instalados como dependências. Qualquer pacote que você usa diretamente pode ser compatível com o novo framework de destino, enquanto suas dependências podem não ser.

  • Se a reinstalação de pacotes depois de redirecionar o aplicativo resultar em erros de build ou runtime, talvez seja necessário reverter a estrutura de destino ou pesquisar pacotes alternativos que dão suporte adequado à nova estrutura de destino.

atributo requireReinstallation definido como true

Depois de redirecionar a estrutura de destino do projeto ou atualizar pacotes NuGet, o NuGet poderá adicionar o requireReinstallation atributo ao packages.config arquivo do projeto. Se o NuGet detectar pacotes afetados durante o processo de redirecionamento ou atualização, ele adicionará um requireReinstallation="true" atributo ao packages.config arquivo para todas as referências de pacote afetadas. Como resultado, cada build subsequente do seu projeto no Visual Studio gera avisos de build para esses pacotes. Os avisos são apresentados como um lembrete para reinstalar o pacote afetado.

Incompatibilidade de versão de dependência do pacote

O Update-Package –reinstall comando reinstala a mesma versão de um pacote instalado e a versão mais recente de qualquer dependência. Para resolver problemas de incompatibilidade de versão, você pode definir restrições de intervalo de versão para controlar a configuração. O NuGet adere às restrições e atualiza as dependências do pacote para versões mais recentes apenas conforme necessário para corrigir um problema.

  • Se as configurações de restrição fizerem com que uma dependência seja revertida para uma versão anterior durante a reinstalação do pacote, você poderá resolver o problema com o Update-Package <dependency_name> comando. Esse comando reinstala a dependência especificada sem afetar o pacote dependente.

  • Use também o comando Update-Package –reinstall <packageName> -ignoreDependencies. Essa opção reinstala a mesma versão do pacote original, mas não reinstala dependências. Use esta abordagem quando atualizar as dependências do pacote pode resultar em um estado de configuração quebrado.

Pacote dependente desfeito

Quando você reinstala um pacote específico, todos os pacotes instalados que dependem do pacote reinstalado não são atualizados. As versões desses outros pacotes instalados permanecem as mesmas. Como resultado, a reinstalação de uma dependência pode interromper um pacote dependente.

  • Last updated on