dotnet restore

Este artigo aplica-se a: ✔️ .NET SDK 6 e versões posteriores

Nome

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

Sinopse

dotnet restore [<PROJECT>|<SOLUTION>|<FILE>]
  [-a|--arch <ARCHITECTURE>] [--artifacts-path <ARTIFACTS_DIR>] [--configfile <FILE>]
  [--disable-build-servers] [--disable-parallel] [-f|--force] [--force-evaluate]
  [--ignore-failed-sources] [--interactive] [--lock-file-path <LOCK_FILE_PATH>]
  [--locked-mode] [--no-dependencies] [--no-http-cache]
  [--os <OS>] [--packages <PACKAGES_DIRECTORY>]
  [-r|--runtime <RUNTIME_IDENTIFIER>] [-s|--source <SOURCE>]
  [--tl:[auto|on|off]] [--ucr|--use-current-runtime] [--use-lock-file]
  [-v|--verbosity <LEVEL>]

dotnet restore -h|--help

Descrição

Um projeto .NET normalmente faz referência a bibliotecas externas em pacotes NuGet que fornecem funcionalidades adicionais. Essas dependências externas são referenciadas no arquivo de projeto (.csproj ou .vbproj). Quando executas o comando dotnet restore, a CLI do .NET usa o NuGet para procurar estas dependências e descarregá-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. Uma vez concluído o comando, todas as dependências exigidas pelo projeto estão disponíveis numa cache local e podem ser usadas pela CLI .NET para construir e executar a aplicação.

Na maioria dos casos, você não precisa usar explicitamente o dotnet restore comando, pois se uma restauração do NuGet for necessária, os seguintes comandos o 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 sistemas de compilação, precisam chamar dotnet restore explicitamente para controlar quando a restauração ocorre para que possam controlar o uso da rede. Para evitar a restauração implícita do NuGet, você pode usar o --no-restore sinalizador com qualquer um desses comandos.

Especificar feeds

Para restaurar as dependências, o NuGet precisa dos feeds onde os pacotes estão localizados. Os feeds geralmente são fornecidos através do arquivo de configuração nuget.config . Um ficheiro de configuração padrão é fornecido quando o SDK .NET é instalado. Para especificar feeds adicionais, siga um destes procedimentos:

• Crie seu próprio arquivo nuget.config no diretório do projeto. Para obter mais informações, consulte Configurações comuns do NuGet e diferenças nuget.config mais adiante neste artigo.
• Use dotnet nuget comandos como dotnet nuget add source.

Você pode substituir os feeds nuget.config pela -s opção.

Para obter informações sobre como usar feeds autenticados, consulte Consumindo 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 --packages argumento. Se não for especificado, o cache de pacote NuGet padrão será usado, que é encontrado no .nuget/packages diretório no diretório inicial do usuário em todos os sistemas operacionais. Por exemplo, /home/user1 no Linux ou C:\Users\user1 no Windows.

Ferramentas específicas de Project

Para ferramentas específicas do projeto, dotnet restore primeiro restaura o pacote no qual a ferramenta está embalada e, em seguida, prossegue para restaurar as dependências da ferramenta conforme especificado em seu arquivo de projeto.

nuget.config diferenças

O comportamento do comando é afetado dotnet restore pelas configurações no arquivo nuget.config , se presente. Por exemplo, definir o globalPackagesFolder in nuget.config coloca os pacotes NuGet restaurados na pasta especificada. Esta é uma alternativa para especificar a --packagesdotnet restore opção no comando. Para obter mais informações, consulte a referência nuget.config.

Há três configurações específicas que dotnet restore ignoram:

• vinculaçãoRedirecionamentos

  Os redirecionamentos de binding não funcionam com elementos <PackageReference> e .NET só suporta elementos <PackageReference> para pacotes NuGet.

• Solução

  Esta definição é específica do Visual Studio e não se aplica ao .NET. .NET não usa um ficheiro packages.config e em vez disso usa elementos <PackageReference> para pacotes NuGet.

• trustedSigners

  O suporte para verificação de assinatura de pacotes multiplataforma foi adicionado no SDK .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 este comando terminar, o download será interrompido. Para obter mais informações, consulte Manifestos de publicidade.

Argumentos

PROJECT | SOLUTION | FILE

O projeto ou solução ou arquivo C# (aplicativo baseado em arquivo) para operar. Se um arquivo não for especificado, o MSBuild procurará um projeto ou solução no diretório atual.

• PROJECT é o caminho e nome de ficheiro de um ficheiro de projeto C#, F# ou Visual Basic, ou o caminho para uma pasta que contém um ficheiro de projeto C#, F# ou Visual Basic.

• SOLUTION é o caminho e o nome do arquivo de solução (.sln ou extensão .slnx) ou o caminho para um diretório que contém um arquivo de solução.

• FILE é um argumento adicionado em .NET 10. O caminho e o nome do arquivo de um aplicativo baseado em arquivo. Os aplicativos baseados em arquivo estão contidos em um único arquivo que é criado e executado sem um arquivo de projeto correspondente (.csproj). Para obter mais informações, consulte Criar aplicativos C# baseados em arquivo.

Opções

• -a|--arch <ARCHITECTURE>

  Especifica a arquitetura de destino. Esta é uma sintaxe abreviada para definir o Runtime Identifier (RID), onde o valor fornecido é combinado com o RID padrão. Por exemplo, em uma win-x64 máquina, especificar --arch x86 define o RID como win-x86. Se você usar essa opção, não use a -r|--runtime opção. Disponível desde .NET 6 Preview 7.

• --artifacts-path <ARTIFACTS_DIR>

  Todos os arquivos de saída de compilação do comando executado irão em subpastas sob o caminho especificado, separados por projeto. Para obter mais informações, consulte Layout de saída de artefatos. Esta opção e o valor fornecido devem ser explicitamente encadeados em qualquer dotnet comando que dependa da saída de outro dotnet comando, por exemplo, ao usar dotnet build --no-restore e dotnet publish --no-build. Disponível desde o SDK .NET 8.

• --configfile <FILE>

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

• --disable-build-servers

  Força o comando a ignorar quaisquer servidores de compilação persistentes. Essa opção fornece uma maneira consistente de desabilitar 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 .NET 7.

• --disable-parallel

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

• --force

  Força todas as dependências a serem resolvidas, mesmo que a última restauração tenha sido bem-sucedida. Especificar esse sinalizador é o mesmo que excluir o arquivo project.assets.json .

• --force-evaluate

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

• --ignore-failed-sources

  Só avise sobre fontes com falha se houver pacotes que atendam ao requisito de versão.

• --interactive

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

• --lock-file-path <LOCK_FILE_PATH>

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

• --locked-mode

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

• --no-dependencies

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

• --no-http-cache

  Desative o cache HTTP para pacotes.

• --os

  Especifica o sistema operacional (SO) de destino. Esta é uma sintaxe abreviada para definir o Runtime Identifier (RID), onde o valor fornecido é combinado com o RID padrão. Por exemplo, em uma win-x64 máquina, especificar --os linux define o RID como linux-x64.

  Introduzido no .NET SDK 10.0.100

• --packages <PACKAGES_DIRECTORY>

  Especifica o diretório para pacotes restaurados.

• -r|--runtime <RUNTIME_IDENTIFIER>

  Especifica um tempo de execução para a restauração do pacote. Isso é usado para restaurar pacotes para tempos de execução não listados explicitamente na <RuntimeIdentifiers> tag no arquivo .csproj . Para obter uma lista de identificadores de tempo de execução (RIDs), consulte o catálogo RID.

• -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 . Várias fontes podem ser fornecidas especificando essa opção várias vezes.

• --ucr|--use-current-runtime

  Use o tempo de execução atual como o tempo de execução de destino.

• --use-lock-file

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

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

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

  O Terminal Logger mostra a fase de restauração seguida pela fase de compilação. Durante cada fase, os projetos atualmente em construção aparecem na parte inferior do terminal. Cada projeto que está construindo produz tanto a meta do MSBuild que está sendo criada quanto a quantidade de tempo gasto nessa meta. Você pode pesquisar essas informações para saber mais sobre a compilação. Quando um projeto termina de construir, uma única seção "construção concluída" é escrita que captura:

  • O nome do projeto construído.
  • A estrutura de destino (se multidirecionada).
  • O status dessa compilação.
  • A saída primária dessa compilação (que é hiperligada).
  • Qualquer diagnóstico gerado para esse projeto.

  Esta opção está disponível a partir do .NET 8.

• -v|--verbosity <LEVEL>

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

• -?|-h|--help

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

Exemplos

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

  dotnet restore
  

• Restaure dependências e ferramentas para o app1 projeto encontradas no caminho determinado:

  dotnet restore ./projects/app1/app1.csproj
  

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

  dotnet restore -s c:\packages\mypackages
  

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

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

• Restaure dependências e ferramentas para o projeto no diretório atual mostrando saída detalhada:

  dotnet restore --verbosity detailed
  

Auditoria de vulnerabilidades de segurança

A partir de 8 de .NET, dotnet restore inclui auditoria de segurança 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 comunicado para obter mais detalhes.

Para desativar a auditoria de segurança, defina a <NuGetAudit> propriedade MSBuild como false no arquivo de projeto.

Para obter dados de vulnerabilidades, a partir de .NET 9, pode usar auditSources além de packageSources. Se não forem fornecidas fontes de auditoria, utilize-se dotnet restore fontes de pacote em vez disso. O NuGet audita qualquer fonte desde que esta forneça o VulnerabilityInfo recurso.

Para listar NuGet.org como fonte de auditoria, defina o seguinte no ficheironuget.config :

<configuration>
    <auditSources>
        <clear />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </auditSources>
</configuration>

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

Em .NET 8 e .NET 9, apenas as referências de pacotes direct são auditadas por defeito. A partir de .NET 10, o NuGet audita tanto as referências de pacotes direct como transitivo por defeito. Você pode alterar o modo definindo a <NuGetAuditMode> propriedade MSBuild como direct ou all.

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