Instalar e usar um pacote NuGet no Visual Studio

  • Artigo

Às vezes, as referências de pacote podem não funcionar em um projeto do Visual Studio. Desinstalar e reinstalar a mesma versão do pacote restaura o funcionamento correto dessas referências. A atualização de 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 e projetos com problemas.

Observação

A orientação neste artigo se aplica somente a projetos que usam o formato de gerenciamento packages.config. Para projetos PackageReference, uma operação de restauração corrige automaticamente as referências que estiverem com problemas.

Cenários comuns

Aqui estão alguns cenários comuns onde você pode encontrar referências de pacotes com problemas em seu projeto do Visual Studio.

Cenário Descrição Resolução
Referências com problemas após a restauração de pacote Você abre seu projeto do Visual Studio e restaura os pacotes NuGet, porém as referências dos pacotes com problemas permanecem. Para corrigir as referências, tente reinstalar cada pacote separadamente.
Projeto com problemas devido a arquivos excluídos Arquivos de pacote excluídos (ausentes) causam problemas no projeto. O NuGet não impede a exclusão de itens que você adiciona dos pacotes. Não é difícil modificar inadvertidamente o conteúdo instalado de um pacote e causar problemas no seu projeto. Para restaurar seu projeto, tente reinstalar os pacotes afetados.
Problemas no projeto após a atualização do pacote Uma atualização de pacote causa problemas em seu projeto. As atualizações complementares para um pacote de dependências geralmente causam esse tipo de falha. Para restaurar o funcionamento da dependência ao estado anterior, tente reinstalar o pacote dependente específico.
Referências com problemas após o redirecionamento ou atualização do projeto Um processo de redirecionamento ou atualização de projeto causa problemas nas referências do pacote. Depois de redirecionar seu projeto, o NuGet mostra um erro de build. Crie pacotes com lista de avisos, alertando que talvez precisem ser reinstalados. Ou, após a atualização do projeto, o NuGet mostra um erro no log da atualização do projeto. O arquivo de log lista os 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 pacotes em desenvolvimento Os autores de pacotes geralmente precisam reinstalar a mesma versão do pacote que está sendo desenvolvida para testar as 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, use o comando Update-Package -reinstall.

Opções de implementação

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

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 e, em seguida, instale-o novamente. Abra a guia Instalado, selecione um pacote, registre seu nome e escolha Desinstalar. Mude para a guia Procurar, pesquise pelo nome do pacote, selecione-o e escolha Instalar).

Console do Gerenciador de Pacotes

Acesse o Console Gerenciador de Pacotes: Ferramentas>Gerenciador de Pacotes NuGet>Console Gerenciador de Pacotes.

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

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

Para obter mais informações, confira o comando Update-Package e as seções Considerações sobre a reinstalação de pacotes.

CLI do NuGet

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

  • Para atualizar os pacotes instalados, execute o comando nuget update.

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

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

Observação

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

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

Por padrão, reinstalar ou atualizar um pacote sempre instala a versão mais recente disponível da origem do pacote. No entanto, os projetos que usam o formato de gerenciamento packages.config podem limitar especificamente o intervalo de versões 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, restrinja as atualizações do pacote NuGet somente para as versões 1.x. Essa limitação ajuda a evitar atualizações acidentais que podem causar problemas em seu aplicativo.

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

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

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

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

Em todo os casos, use a notação descrita em 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 lidar com as referências não funcionais. No entanto, essa abordagem não pode ser usada 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 estiver instalado na configuração, o comando retornará um erro. Consulte a seção Considerações sobre a reinstalação de pacotes antes de usar o comando.

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

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

Reinstalar opções de pacote

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 -Id opcional.

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

Usar o comando Update-Package é muito mais fácil do que remover um pacote e depois tentar localizá-lo na Galeria do NuGet com a mesma versão.

Opções do pacote de atualização

O mesmo comando sem as atualizações do parâmetro -reinstall 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 projetos e soluções

Por padrão, o comando Update-Package afeta todos os projetos em uma solução. Para limitar a ação a um projeto específico, use o parâmetro -ProjectName. 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 parâmetro <package_name>.

# 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 parâmetro -ProjectName, 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 comando Update-Package sozinho sem nenhum outro argumento ou parâmetro.

Importante

Use a seguinte forma do comando cuidadosamente. O processo do 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 comando Update-Package para reinstalar pacotes, examine as considerações a seguir para garantir a compatibilidade com o seu cenário de configuração.

  • Os pacotes e suas dependências podem não ser compatíveis com uma estrutura de destino de projeto redirecionada.
  • Quando o atributo requireReinstallation é definido como true, o Visual Studio emite avisos do build para os pacotes afetados.
  • A reinstalação de um pacote e as restrições de versão podem introduzir problemas de compatibilidade da versão da dependência.
  • A reinstalação de um pacote específico pode causar problemas nos pacotes dependentes.

O pacote não é compatível com a estrutura de destino do projeto

Se você redirecionar a estrutura de destino do projeto, um ou mais pacotes podem não ser compatíveis com a nova configuração de destino.

Normalmente, a reinstalação de um pacote com o comando Update-Package –reinstall <package_name> 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 ser compatível com a nova estrutura de destino. Aqui estão alguns dos problemas que você poderá encontrar:

  • Se um pacote for compatível com as bibliotecas de classes portáteis (PCLs) e você redirecionar o projeto para uma combinação de plataformas compatíveis com o pacote, as referências ao pacote poderão se perder após a reinstalação.

  • Esse problema pode surgir nos pacotes que você estiver usando diretamente ou em pacotes instalados como dependências. Qualquer pacote que você usar diretamente poderá ser compatível com a nova estrutura de destino, enquanto suas dependências podem não ser.

  • Se reinstalar os pacotes após redirecionar seu aplicativo resultar em erros de build ou runtime, poderá ser necessário reverter a estrutura de destino ou procurar pacotes alternativos com suporte adequado à nova estrutura de destino.

Atributo requireReinstallation definido como true

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

Incompatibilidade de versão da dependência de pacote

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

  • Se as configurações de restrição revertem uma dependência para uma versão anterior durante a reinstalação do pacote, você poderá resolver o problema com o comando Update-Package <dependency_name>. Este 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 as dependências. O uso dessa abordagem ao atualizar as dependências de pacote pode resultar em um estado de configuração com problemas.

Pacote dependente com problemas

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 causar problemas em um pacote dependente.