dotnet restore

Este artigo se aplica a: ✔️ SDK do .NET Core 3.1 e versões posteriores

Nome

dotnet restore – Restaura as dependências e as ferramentas de um projeto.

Sinopse

dotnet restore [<ROOT>] [--configfile <FILE>] [--disable-build-servers]
    [--disable-parallel]
    [-f|--force] [--force-evaluate] [--ignore-failed-sources]
    [--interactive] [--lock-file-path <LOCK_FILE_PATH>] [--locked-mode]
    [--no-cache] [--no-dependencies] [--packages <PACKAGES_DIRECTORY>]
    [-r|--runtime <RUNTIME_IDENTIFIER>] [-s|--source <SOURCE>]
    [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
    [--use-lock-file] [-v|--verbosity <LEVEL>]

dotnet restore -h|--help

Descrição

Um projeto do .NET normalmente faz referência a bibliotecas externas em pacotes NuGet que fornecem funcionalidade adicional. Essas dependências externas são referenciadas no arquivo de projeto (.csproj ou .vbproj). Quando você executa o comando dotnet restore, a CLI do .NET usa o NuGet para procurar essas dependências e baixá-las, se necessário. Ele também garante que todas as dependências exigidas pelo projeto sejam compatíveis entre si e que não haja conflitos entre elas. Depois que o comando for concluído, todas as dependências exigidas pelo projeto estarão disponíveis em um cache local e poderão ser usadas pela CLI do .NET para compilar e executar o aplicativo.

Na maioria dos casos, você não precisa usar o comando dotnet restore explicitamente, pois, se uma restauração do NuGet for necessária, os seguintes comandos a executarão implicitamente:

• dotnet new
• dotnet build
• dotnet build-server
• dotnet run
• dotnet test
• dotnet publish
• dotnet pack

Às vezes, pode ser inconveniente executar a restauração implícita do NuGet com esses comandos. Por exemplo, alguns sistemas automatizados, como os sistemas de compilação, precisam chamar o dotnet restore explicitamente para controlar o momento em que a restauração ocorre para que possam controlar o uso de rede. Para evitar a restauração implícita do NuGet, use o sinalizador --no-restore com um desses comandos.

Observação

A verificação de pacote assinado durante as operações de restauração requer um repositório raiz de certificado válido para assinatura de código e carimbo de data/hora. Para obter mais informações, consulte Verificação de pacote assinado pelo NuGet.

Especificar feeds

Para restaurar as dependências, o NuGet precisa dos feeds nos quais os pacotes estão localizados. Os feeds são geralmente fornecidos por meio do arquivo de configuração nuget.config. Um arquivo de configuração padrão é fornecido quando o SDK do .NET é instalado. Para especificar feeds adicionais, execute uma das seguintes ações:

• Crie um arquivo nuget.config no diretório do projeto. Para obter mais informações, confira Configurações comuns do NuGet e Diferenças do nuget.config mais adiante neste artigo.
• Use os comandos dotnet nuget como dotnet nuget add source.

Você pode substituir os feeds do nuget.config com a opção -s.

Para obter informações de como usar feeds autenticados, confira Como consumir pacotes de feeds autenticados.

Pasta de pacotes globais

Para dependências, você pode especificar onde os pacotes restaurados são colocados durante a operação de restauração usando o argumento --packages. Se não é especificado, o cache do pacote NuGet padrão é usado, o qual pode ser encontrado no diretório .nuget/packages do diretório base do usuário em todos os sistemas operacionais. Por exemplo, /home/user1 no Linux ou C:\Usuário\user1 no Windows.

Ferramentas específicas do projeto

Para ferramentas específicas do projeto, o dotnet restore primeiro restaura o pacote no qual a ferramenta foi empacotada e prossegue com a restauração das dependências da ferramenta conforme especificado no seu arquivo de projeto.

Diferenças do nuget.config

O comportamento do comando dotnet restore será afetado pelas configurações no arquivo nuget.config, se estiver presente. Por exemplo, a definição da globalPackagesFolder em nuget.config coloca os pacotes NuGet restaurados na pasta especificada. Essa é uma alternativa para especificar a opção --packages no comando dotnet restore. Para obter mais informações, confira a Referência do nuget.config.

Há três configurações específicas que são ignoradas por dotnet restore:

• bindingRedirects

  Os redirecionamentos de associação não funcionam com elementos <PackageReference> e o .NET só dá suporte a elementos <PackageReference> em pacotes NuGet.

• solução

  Essa configuração é específica do Visual Studio e não se aplica ao .NET. O .NET não usa um arquivo packages.config, ele usa elementos <PackageReference> para pacotes NuGet.

• trustedSigners

  O suporte para verificação de assinatura de pacote multiplataforma foi adicionado ao SDK do .NET 5.0.100.

Downloads de manifesto de carga de trabalho

Quando você executa esse comando, ele inicia um download assíncrono em segundo plano de manifestos de publicidade para cargas de trabalho. Se o download ainda estiver em execução quando esse comando for concluído, o download será interrompido. Para saber mais, confira Manifestos de publicidade.

Argumentos

• ROOT

  Caminho opcional para o arquivo de projeto a ser restaurado.

Opções

• -a|--arch <ARCHITECTURE>

  Especifica a arquitetura de destino. Essa é uma sintaxe abreviada para definir o RID (Identificador de Runtime), em que o valor fornecido é combinado com o RID padrão. Por exemplo, em um computador win-x64, a especificação de --arch x86 define o RID como win-x86. Se você usar essa opção, não use a opção -r|--runtime. Disponível desde a versão prévia 7 do .NET 6.

• --configfile <FILE>

  O arquivo de configuração do NuGet (nuget.config) a ser usado. Se esse arquivo for especificado, serão usadas somente as configurações dele. Se ele não for especificado, será usada a hierarquia de arquivos de configuração do diretório atual. Para obter mais informações, confira Configurações comuns do NuGet.

• --disable-build-servers

  Força o comando a ignorar todos os servidores de build persistentes. Essa opção fornece uma maneira consistente de desativar todo o uso do cache de compilação, o que força uma compilação do zero. Uma compilação que não depende de caches é útil quando os caches podem estar corrompidos ou incorretos por algum motivo. Disponível desde o SDK do .NET 7.

• --disable-parallel

  Desabilita a restauração de vários projetos paralelamente.

• --force

  Forçará todas as dependências a serem resolvidas mesmo se última restauração tiver sido bem-sucedida. A especificação desse sinalizador é o mesmo que a exclusão do arquivo project.assets.json.

• --force-evaluate

  Força a restauração a reavaliar todas as dependências, mesmo quando já existe um arquivo de bloqueio.

• -?|-h|--help

  Imprime uma descrição de como usar o comando.

• --ignore-failed-sources

  Avise somente sobre fontes com falha se houver pacotes que atendem ao requisito de versão.

• --interactive

  Permite que o comando pare e aguarde entrada ou ação do usuário. Por exemplo, para concluir a autenticação.

• --lock-file-path <LOCK_FILE_PATH>

  Local de saída em que o arquivo de bloqueio de projeto é gravado. Por padrão, é PROJECT_ROOT\packages.lock.json.

• --locked-mode

  Não permitir a atualização do arquivo de bloqueio do projeto.

• --no-cache

  Especifica que as solicitações HTTP não devem ser armazenadas em cache.

• --no-dependencies

  Ao restaurar um projeto com referências de P2P (projeto a projeto), restaura o projeto raiz, não as referências.

• --packages <PACKAGES_DIRECTORY>

  Especifica o diretório para os pacotes restaurados.

• -r|--runtime <RUNTIME_IDENTIFIER>

  Especifica um runtime para a restauração do pacote. Isso é usado para restaurar pacotes para runtimes não listados explicitamente na marca <RuntimeIdentifiers> no arquivo .csproj. Para obter uma lista de RIDs (Identificadores de Runtime), veja o Catálogo de RIDs.

• -s|--source <SOURCE>

  Especifica o URI da origem do pacote NuGet a ser usado durante a operação de restauração. Essa configuração substitui todas as fontes especificadas nos arquivos nuget.config. Diversas fontes podem ser fornecidas especificando essa opção várias vezes.

• --tl:[auto|on|off]

  Especifica se o agente de terminal deve ser usado para a saída de build. O padrão é auto, que primeiro verifica o ambiente antes de habilitar o registro em log do terminal. A verificação de ambiente confirma se o terminal é capaz de usar recursos de saída modernos e não está usando uma saída padrão redirecionada antes de habilitar o novo agente. on ignora a verificação de ambiente e habilita o registro em log do terminal. off ignora a verificação de ambiente e usa o agente de console padrão.

  O agente de terminal mostra a fase de restauração seguida pela fase de build. Durante cada fase, os projetos de construção atuais aparecem na parte inferior do terminal. Cada projeto que está sendo criado gera tanto o destino do MSBuild em construção no momento quanto o tempo gasto nesse destino. Você pode pesquisar essas informações para saber mais sobre o build. Quando a build de um projeto é concluída, é gravada uma única seção "build concluída" que captura:

  • O nome do projeto criado.
  • A estrutura de destino (se houver vários destinos).
  • O status dessa build.
  • A saída primária dessa build (que contém um hiperlink).
  • Qualquer diagnóstico gerado para esse projeto.

  Esta opção está disponível desde o .NET 8.

• --use-current-runtime, --ucr [true|false]

  Define RuntimeIdentifier como uma plataforma portátil RuntimeIdentifier com base em um de seus computadores. Isso acontece implicitamente com propriedades que exigem RuntimeIdentifier, como SelfContained, PublishAot, PublishSelfContained, PublishSingleFile e PublishReadyToRun. Se a propriedade for definida como false, essa resolução implícita não ocorrerá mais.

• --use-lock-file

  Permite que o arquivo de bloqueio do projeto seja gerado e usado com a restauração.

• -v|--verbosity <LEVEL>

  Define o nível de detalhes do comando. Os valores permitidos são q[uiet], m[inimal], n[ormal], d[etailed] e diag[nostic]. O padrão é minimal. Para obter mais informações, consulte LoggerVerbosity.

Exemplos

• Restaure as dependências e as ferramentas para o projeto no diretório atual:

  dotnet restore
  

• Restaure as dependências e as ferramentas para o projeto app1 encontrado no caminho fornecido:

  dotnet restore ./projects/app1/app1.csproj
  

• Restaure as dependências e as ferramentas para o projeto no diretório atual usando o caminho de arquivo fornecido como a fonte:

  dotnet restore -s c:\packages\mypackages
  

• Restaure as dependências e as ferramentas para o projeto no diretório atual usando os caminhos dos dois arquivos fornecidos como fontes:

  dotnet restore -s c:\packages\mypackages -s c:\packages\myotherpackages
  

• Restaure as dependências e as ferramentas do projeto no diretório atual, mostrando a saída detalhada:

  dotnet restore --verbosity detailed
  

Auditar vulnerabilidades de segurança

A partir do .NET 8, dotnet restore inclui a auditoria de segurança do NuGet. Essa auditoria produz um relatório de vulnerabilidades de segurança com o nome do pacote afetado, a gravidade da vulnerabilidade e um link para o aviso para obter mais detalhes.

Para recusar a auditoria de segurança, defina a <NuGetAudit> propriedade MSBuild como false em seu arquivo de projeto.

Para recuperar o conjunto de dados de vulnerabilidade conhecido, certifique-se de ter o registro central NuGet.org definido como uma das fontes do pacote:

<packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
</packageSources>

Você pode configurar o nível no qual a auditoria falhará definindo a propriedade <NuGetAuditLevel> do MSBuild. Os valores possíveis são low, moderate, high e critical. Por exemplo, se quiser ver apenas avisos moderados, altos e críticos, poderá definir a propriedade como moderate.

A partir do .NET 9, o NuGet audita referências de pacote diretas e transitivas, por padrão. No .NET 8, somente as referências diretas de pacote são auditadas. Você pode alterar o modo definindo a <NuGetAuditMode> propriedade MSBuild como direct ou all.

Para obter mais informações, consulte Auditando dependências de pacote para vulnerabilidades de segurança.