Restaurar pacotes com a Restauração de Pacotes NuGet

  • Artigo

A Restauração de Pacotes NuGet restaura todas as dependências de um projeto listadas em um arquivo de projeto ou em um arquivo packages.config. Restaure pacotes manualmente com nuget restore, dotnet restore, msbuild -t:restore ou com o Visual Studio. Os comandos dotnet build e dotnet run restauram pacotes automaticamente, e você pode configurar o Visual Studio para fazer o mesmo quando ele criar um projeto.

Para promover um ambiente de desenvolvimento mais limpo e reduzir o tamanho do repositório, a Restauração de Pacotes disponibiliza todas as dependências de um projeto sem precisar armazená-las no controle do código-fonte. Para configurar o repositório do controle do código-fonte para excluir binários do pacote, confira Pacotes e controle do código-fonte.

Comportamento da Restauração de Pacote

A Restauração de Pacote tenta instalar todas as dependências de pacotes no estado correspondente aos <PackageReference> em um arquivo do projeto, como .csproj, ou aos <package> em um arquivo packages.config. Primeiro, a Restauração de Pacote instala as dependências diretas de um projeto, conforme necessário, e, em seguida, instala as dependências desses pacotes em todo o grafo de dependência.

Se um pacote necessário ainda não estiver instalado, o NuGet primeiro tentará recuperá-lo dos pacotes globais ou das pastas de cache HTTP locais. Se o pacote não estiver nas pastas locais, o NuGet tentará baixá-lo de todas as origens configuradas no Visual Studio, em Ferramentas>Opções>Gerenciador de Pacotes NuGet>Origens do Pacote no Visual Studio.

Durante a restauração, o NuGet ignora a ordem das origens do pacote e usa o pacote da primeira origem que responder às solicitações. Se a restauração falhar, o NuGet não indicará a falha até que ele verifique todas as origens. O NuGet então relatará uma falha somente para a última origem na lista. O erro implica que o pacote não estava presente em nenhuma das origens, embora não liste as outras falhas individualmente.

Para obter mais informações sobre o comportamento do NuGet, confira Configurações comuns do NuGet.

Restaurar pacotes

Se as referências de pacote no arquivo do projeto ou no arquivo packages.config estiverem corretas, use a ferramenta de sua preferência para restaurar os pacotes:

Após uma restauração bem-sucedida:

  • Para projetos que usam <PackageReference>, o pacote está presente na pasta global-packages local e o arquivo obj/project.assets.json do projeto é recriado.
  • Para projetos que usam packages.config, o pacote aparece na pasta packages do projeto.
  • Nesse momento, o projeto deverá ser compilado com êxito.

Se as referências de pacote no seu arquivo do projeto ou no arquivo packages.config estiverem incorretas e não corresponderem ao estado desejado, instale ou atualize os pacotes corretos em vez de usar a Restauração de Pacote.

Se alguns pacotes ainda estiverem ausentes ou ocorrerem erros relacionados a pacotes depois que você executar a Restauração de Pacote, siga as instruções descritas em Solução de erros de restauração de pacote ou Reinstale ou atualize os pacotes. No Visual Studio, o Console do Gerenciador de Pacotes fornece várias opções para reinstalar os pacotes. Para obter mais informações, consulte Use Package-Update.

Restauração de pacotes no Visual Studio

No Visual Studio no Windows, você pode restaurar pacotes automaticamente ou manualmente. Primeiro, configure a Restauração de Pacote acessando Ferramentas>Opções>Gerenciador de Pacotes NuGet.

Configurar as opções de restauração de pacote do Visual Studio

Configure as seguintes opções de Restauração de Pacotes em Ferramentas>Opções>Gerenciador de Pacotes NuGet>Geral.

Screenshot that shows the NuGet Package Manager options.

Permitir que o NuGet baixe pacotes ausentes

Selecione Permitir que o NuGet baixe pacotes ausentes para habilitar a restauração de pacotes e o comando Restaurar Pacotes NuGet. Essa seleção define a configuração packageRestore/enabled como True na seção packageRestore do arquivo global NuGet.Config em %AppData%\Roaming\NuGet no Windows ou ~/.nuget/NuGet/ no Mac ou Linux.

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Observação

Para substituir globalmente a configuração packageRestore/enabled, defina a variável de ambiente EnableNuGetPackageRestore como True ou False antes de abrir o Visual Studio ou iniciar um build.

Para habilitar ou desabilitar a Restauração de Pacotes para todos os usuários em um computador, você pode adicionar as definições de configuração ao arquivo NuGet.Config global no Windows em %ProgramData%\NuGet\Config, às vezes em uma pasta <IDE>\<Version>\<SKU> do Visual Studio específica ou no Mac/Linux em ~/.local/share. Usuários individuais poderão, então, habilitar seletivamente a restauração conforme necessário no nível do projeto. Para obter mais detalhes sobre como o NuGet prioriza vários arquivos de configuração, confira Configurações comuns do NuGet.

Importante

Se você editar as configurações de packageRestore diretamente em NuGet.Config, reinicie o Visual Studio para que a caixa de diálogo Opções mostre os valores atuais.

Verificar automaticamente se há pacotes ausentes durante o build

Selecione Verificar automaticamente se há pacotes ausentes durante o build no Visual Studio para restaurar automaticamente todos os pacotes ausentes quando você executar um build do Visual Studio. Essa configuração não afeta os builds executados na linha de comando do MSBuild. Essa seleção define a configuração packageRestore/automatic como True na seção packageRestore do arquivo NuGet.Config.

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

Para projetos que não sejam do estilo SDK, selecione Permitir que o NuGet baixe pacotes ausentes, bem como Verificar automaticamente se há pacotes ausentes durante o build no Visual Studio em Opções para habilitar a restauração automática.

Escolha o formato de gerenciamento de pacotes padrão

O NuGet tem dois formatos de gerenciamento de pacotes, PackageReference e packages.config. Selecione o formato que deseja usar na lista suspensa em Gerenciamento de Pacotes. Selecione também se deseja permitir a seleção do formato na primeira instalação do pacote.

Observação

  • Se um projeto não for compatível com os dois formatos de gerenciamento de pacotes, o NuGet usará o formato de gerenciamento de pacotes compatível com o projeto, que pode não ser o padrão definido nas opções. O NuGet então não solicitará a seleção na primeira instalação, mesmo que você tenha escolhido essa opção.

  • Se você usar o Console do Gerenciador de Pacotes para instalar o primeiro pacote em um projeto, o NuGet não solicitará a seleção do formato, mesmo se essa opção estiver selecionada em Opções.

Restaurar pacotes manualmente ou automaticamente

Após habilitar a restauração de pacotes em Opções, clique com o botão direito do mouse na solução em Gerenciador de Soluções e selecione Restaurar Pacotes NuGet para restaurar os pacotes a qualquer momento.

Se você habilitou a restauração automática em Opções, a restauração ocorrerá automaticamente quando você criar um projeto com base em um modelo ou compilar um projeto. Para o NuGet 4.0 e posterior, a restauração também ocorre automaticamente quando você faz alterações em um projeto do estilo SDK.

Para projetos que usam o <PackageReference>, consulte as referências de pacote no Gerenciador de Soluções do Visual Studio, em Pacotes de>dependências. Os pacotes que não são instalados corretamente quando você restaura manualmente ou executa uma build exibem ícones de erro no Gerenciador de Soluções. Clique com o botão direito do mouse e selecione Gerenciar Pacotes NuGet e use o Gerenciador de Pacotes NuGet para desinstalar e reinstalar os pacotes afetados. Para obter mais informações, confira Reinstalar e atualizar pacotes.

Se você receber o erro Este projeto referencia pacotes NuGet que estão ausentes neste computador ou Um ou mais pacotes NuGet precisam ser restaurados, mas não foi possível fazer isso, pois não houve consentimento, habilite a restauração automática. Para projetos mais antigos, confira Migrar para a restauração de pacote automática. Confira também Solução de problemas de erros de restauração de pacote.

Restaurar usando a CLI do dotnet

O comando dotnet restore restaura pacotes que o arquivo de projeto lista com <PackageReference>. Para obter mais informações, consulte PackageReference em arquivos de projeto.

Os comandos dotnet build e dotnet run do .NET Core 2.0 em diante restauram os pacotes automaticamente. No NuGet 4.0, dotnet restore executa o mesmo código que nuget restore.

Para restaurar um pacote com dotnet restore:

  1. Abra uma linha de comando e alterne para o diretório que contém o arquivo de projeto.
  2. Execute dotnet restore.

Importante

Para adicionar uma referência de pacote ausente ao arquivo de projeto, use dotnet add package, que também executa o restore.

Restaurar usando a CLI do NuGet

O comando restore da CLI do NuGet baixa e instala todos os pacotes ausentes. O comando funciona em projetos que usam PackageReference ou packages.config para referências de pacote.

Como install, o comando restore só adiciona pacotes ao disco, mas não modifica o arquivo de projeto ou packages.config. Para adicionar dependências de projeto, use a interface do usuário ou o console do Gerenciador de Pacotes do Visual Studio.

Para restaurar pacotes, execute o seguinte comando:

nuget restore <projectPath>

O comando restore usa um arquivo de solução ou um arquivo package.config no caminho do projeto especificado.

Por exemplo, para restaurar todos os pacotes para MySolution.sln no diretório atual, execute:

nuget restore MySolution.sln

Observação

Para projetos estilo não SDK que usam PackageReference, use msbuild -t:restore para restaurar pacotes.

Restaurar usando o MSBuild

Você pode usar o msbuild -t:restore para restaurar pacotes no NuGet 4.x+ e MSBuild 15.1+, que estão incluídos no Visual Studio 2017 e superior.

Esse comando restaura pacotes em projetos que usam PackageReference para referências de pacote. A partir do MSBuild 16.5+, o comando também oferece suporte a referências de pacote packages.config, quando usado com o -p:RestorePackagesConfig=true.

Para usar a restauração do MSBuild:

  1. Abra um Prompt de Comando do Desenvolvedor procurando prompt de comando do desenvolvedor e iniciando o prompt no menu Iniciar do Windows, que configura todos os caminhos necessários para o MSBuild.

  2. Alterne para a pasta do projeto e digite msbuild -t:restore.

  3. Após a conclusão da restauração, insira msbuild para recriar o projeto. Verifique se a saída do MSBuild indica que a compilação foi concluída com êxito.

Observação

Você pode usar msbuild -restore para executar restore, recarregar o projeto e compilar o build, já que o build é o destino padrão. Para obter mais informações, consulte Restaurar e criar o build com um comando MSBuild.

Restaurar com o Azure Pipelines ou Azure DevOps Server

Ao criar uma definição de build no Azure Pipelines, inclua a tarefa Restaurar a CLI no NuGet ou a tarefa Restaurar a CLI do dotnet na definição, antes de qualquer tarefa do build. Alguns modelos de build incluem a tarefa de restauração por padrão.

O Azure DevOps Server e o TFS 2013 e posterior restaurarão pacotes automaticamente durante o build se você usar um modelo do Team Build do TFS 2013 ou posterior. Inclua uma etapa de build para executar uma opção de restauração da linha de comando ou, opcionalmente, migrar o modelo de build para uma versão posterior. Para obter mais informações, confira Configurar a restauração de pacote com o Team Foundation Build.

Restringir versões do pacote

O NuGet restaura por qualquer método que respeite todas as restrições de versões especificadas em packages.config ou no arquivo de projeto.

  • Em packages.config, você pode especificar um intervalo allowedVersions na dependência. Para obter mais informações, confira Restrições nas versões de atualização. Por exemplo:

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />

  • Em um arquivo de projeto, especifique um intervalo de versão na propriedade Version da dependência. Por exemplo:

    <PackageReference Include="Newtonsoft.json" Version="[6,7)" />

Em ambos os casos, use a notação descrita em Controle de versão do pacote.

Forçar a restauração das origens remotas de pacotes

Por padrão, as operações de restauração do NuGet usam pacotes das pastas global-packages e http-cache, conforme descrito em Gerenciar os pacotes globais e as pastas de cache. Para evitar o uso desses pacotes locais, use as opções a seguir.

Para limpar todos os caches locais:

  • No Visual Studio, selecione o botão Limpar todos os caches NuGet em Ferramentas>Opções>Gerenciador de pacotes NuGet>Geral.
  • Na CLI do dotnet use dotnet nuget locals all --clear.
  • Na CLI do NuGet, use nuget locals all -clear.

Para evitar o uso de pacotes na pasta global-packages:

  • Limpe a pasta usando nuget locals global-packages -clear ou dotnet nuget locals global-packages --clear.
  • Defina a variável de ambiente NUGET_PACKAGES para uma pasta diferente.
  • Crie um arquivo NuGet.Config que defina globalPackagesFolder para PackageReference, ou repositoryPath para packages.config, em uma pasta diferente. Para obter mais informações, confira Definições de configuração.
  • Somente para MSBuild: especifique uma pasta diferente com a propriedade RestorePackagesPath.

Para evitar o uso de pacotes no cache HTTP:

  • Limpe o cache usando nuget locals http-cache -clear ou dotnet nuget locals http-cache --clear.
  • Defina temporariamente a variável de ambiente NUGET_HTTP_CACHE_PATH em uma outra pasta.
  • Para nuget restore, use a opção -NoHttpCache ou para dotnet restore, use a opção --no-http-cache. Essas opções não afetam as operações de restauração por meio do console ou do Gerenciador de Pacotes do Visual Studio.

Migrar para a restauração automática de pacote

Versões anteriores do NuGet ofereciam suporte a uma restauração de pacote integrada ao MSBuild. Os projetos que usam a restauração de pacote integrada ao MSBuild preterida devem migrar para a restauração automática de pacotes.

Esses projetos geralmente contêm uma pasta .nuget com três arquivos: NuGet.config, nuget.exe e NuGet.targets. O arquivo NuGet.targets faz com que o NuGet use a abordagem integrada ao MSBuild, portanto, ele deve ser removido.

Para migrar para restauração automática de pacote:

  1. Habilite a restauração automática de pacotes.
  2. Feche o Visual Studio.
  3. Exclua .nuget/nuget.exe e .nuget/NuGet.targets.
  4. Para cada arquivo de projeto, remova o elemento <RestorePackages> e qualquer referência ao NuGet.targets.

Para testar a restauração automática de pacotes:

  1. Remova a pasta packages da solução.
  2. Abra a solução no Visual Studio e inicie uma compilação. A restauração automática de pacotes deve baixar e instalar cada pacote de dependência, sem adicioná-los ao controle do código fonte.

Próximas etapas