restauração dotnet

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

Nome

dotnet restore - Restaura as dependências e 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

Description

Um projeto .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 dotnet restore comando, 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. Quando 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 criar e executar o aplicativo.

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.

Nota

A verificação de pacotes assinados durante as operações de restauração requer um armazenamento 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 NuGet.

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 arquivo de configuração padrão é fornecido quando o SDK do .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 do projeto

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 --packages dotnet 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 vinculação não funcionam com <PackageReference> elementos e o .NET só suporta <PackageReference> elementos para 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 packages.config arquivo e, em vez disso, usa <PackageReference> elementos para pacotes NuGet.

• trustedSigners

  O suporte para verificação de assinatura de pacote entre plataformas foi adicionado no 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 este comando terminar, o download será interrompido. Para obter mais informações, consulte 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. 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 o .NET 6 Preview 7.

• --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 .NET 7 SDK.

• --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.

• -?|-h|--help

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

• --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-cache

  Especifica para não armazenar em cache solicitações HTTP.

• --no-dependencies

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

• --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.

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

  Especifica se o registrador de terminal deve ser usado para a saída da 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 registrador de terminal 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.

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

  Define o RuntimeIdentifier para uma plataforma portátil RuntimeIdentifier com base na da sua máquina. Isso acontece implicitamente com propriedades que exigem um RuntimeIdentifier, como SelfContained, PublishAot, PublishSelfContained, PublishSingleFilee PublishReadyToRun. Se a propriedade estiver 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 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.

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 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 comunicado para obter mais detalhes.

Para desativar a auditoria de segurança, defina a <NuGetAudit> propriedade MSBuild como false no 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 <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.

A partir do .NET 9, o NuGet audita referências de pacotes diretos e transitivos, por padrão. No .NET 8, apenas referências diretas de pacotes 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 pacotes para vulnerabilidades de segurança.