dotnet restore

Cet article s’applique à : ✔️ SDK .NET Core 3.1 et versions ultérieures

Nom

dotnet restore : Restaure les dépendances et les outils d’un projet.

Synopsis

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

Un projet .NET référence généralement les bibliothèques externes des packages NuGet qui fournissent des fonctionnalités supplémentaires. Ces dépendances externes sont référencées dans le fichier projet (.csproj ou .vbproj). Lorsque vous exécutez la commande dotnet restore, l’interface CLI .NET utilise NuGet pour rechercher ces dépendances et les télécharger si nécessaire. Elle garantit également que toutes les dépendances requises par le projet sont compatibles les unes avec les autres et qu’il n’existe aucun conflit entre elles. Une fois la commande terminée, toutes les dépendances requises par le projet sont disponibles dans un cache local et peuvent être utilisées par l’interface CLI .NET pour générer et exécuter l’application.

Dans la plupart des cas, vous n’avez pas besoin d’utiliser explicitement la commande dotnet restore, car si une restauration NuGet est nécessaire, les commandes suivantes l’exécutent implicitement :

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

Parfois, il peut être gênant d’exécuter la restauration NuGet implicite avec ces commandes. Par exemple, certains systèmes automatisés, comme les systèmes de génération, doivent appeler explicitement dotnet restore pour contrôler quand la restauration a lieu afin de pouvoir contrôler l’utilisation du réseau. Pour empêcher la restauration NuGet implicite, vous pouvez utiliser l’indicateur --no-restore avec l’une de ces commandes.

Notes

La vérification de package signé pendant les opérations de restauration nécessite un magasin de certificat racine valide pour la signature de code et le timestamp. Pour plus d’informations, consultez Vérification du package signé NuGet.

Spécifier des flux

Pour restaurer les dépendances, NuGet a besoin des flux où sont situés les packages. Les flux sont généralement fournis via le fichier de configuration nuget.config. Un fichier de configuration par défaut est fourni lorsque le Kit de développement logiciel (SDK) .NET est installé. Pour spécifier des flux supplémentaires, effectuez l’une des opérations suivantes :

• Créez votre propre fichier nuget.config dans le répertoire du projet. Pour plus d’informations, consultez Configurations NuGet courantes et Différences nuget.config plus loin dans cet article.
• Utilisez des commandes dotnet nuget telles que dotnet nuget add source.

Vous pouvez remplacer les flux nuget.config par l’option -s.

Pour plus d’informations sur l’utilisation des flux authentifiés, consultez Consommation de packages à partir de flux authentifiés.

Dossier packages globaux

Pour les dépendances, vous pouvez spécifier l’emplacement des packages restaurés pendant l’opération de restauration à l’aide de l’argument --packages. Si aucune valeur n’est spécifiée, le cache du package NuGet par défaut est utilisé. Il se trouve dans le répertoire .nuget/packages, situé dans le répertoire de base de l’utilisateur, sur tous les systèmes d’exploitation. Par exemple, /home/user1 sur Linux ou C:\Users\user1 sur Windows.

Outils spécifiques au projet

Pour les outils spécifiques au projet, dotnet restore commence par restaurer le package dans lequel l’outil est empaqueté, puis il restaure les dépendances de l’outil, comme spécifié dans son fichier projet.

Différences dans nuget.config

Le comportement de la commande dotnet restore est affecté par les paramètres du fichier nuget.config, s’il est présent. Par exemple, si vous définissez globalPackagesFolder dans nuget.config, les packages NuGet restaurés sont placés dans le dossier spécifié. Cette méthode permet également de spécifier l’option --packages sur la commande dotnet restore. Pour plus d’informations, consultez Informations de référence sur nuget.config.

Trois paramètres spécifiques sont ignorés par dotnet restore :

• bindingRedirects

  Les redirections de liaison ne fonctionnent pas avec les éléments <PackageReference> et .NET Core ne prend qu’en charge les éléments <PackageReference> pour les packages NuGet.

• Solution

  Ce paramètre est spécifique à Visual Studio et ne s’applique pas à .NET. .NET Core n’utilise pas de fichier packages.config et utilise à la place des éléments <PackageReference> pour les packages NuGet.

• trustedSigners

  La prise en charge de la vérification de signature de package multiplateforme a été ajoutée dans le Kit de développement logiciel (SDK) .NET 5.0.100.

Téléchargement de manifestes de charge de travail

Lorsque vous exécutez cette commande, elle lance en arrière-plan un téléchargement asynchrone des manifestes publicitaires des charges de travail. Si le téléchargement est toujours en cours lorsque cette commande se termine, celui-ci est arrêté. Pour plus d’informations, consultez Manifestes publicitaires.

Arguments

• ROOT

  Chemin facultatif du fichier projet à restaurer.

Options

• -a|--arch <ARCHITECTURE>

  Spécifie l’architecture cible. Il s’agit d’une syntaxe abrégée pour définir l’identificateur d’exécution (RID), où la valeur fournie est combinée avec le RID par défaut. Par exemple, sur une machine win-x64, la spécification de --arch x86 définit le RID sur win-x86. Si vous utilisez cette option, n’utilisez pas l’option -r|--runtime. Disponible depuis .NET 6 Preview 7.

• --configfile <FILE>

  Fichier de configuration NuGet (nuget.config) à utiliser. S’ils sont spécifiés, seuls les paramètres de ce fichier seront utilisés. Si elle n’est pas spécifiée, la hiérarchie des fichiers de configuration du répertoire actuel sera utilisée. Pour plus d’informations, consultez Configuration NuGet courantes.

• --disable-build-servers

  Force la commande à ignorer tous les serveurs de build persistants. Cette option offre un moyen cohérent de désactiver toute utilisation de la mise en cache de build, ce qui force une build à partir de zéro. Une build qui ne repose pas sur des caches est utile quand les caches peuvent être endommagés ou incorrects pour une raison quelconque. Disponible depuis le SDK .NET 7.

• --disable-parallel

  Désactive la restauration de plusieurs projets en parallèle.

• --force

  Force la résolution de toutes les dépendances même si la dernière restauration a réussi. Définir cet indicateur revient à supprimer le fichier project.assets.json.

• --force-evaluate

  Force la restauration à réévaluer toutes les dépendances, même s'il existe déjà un fichier de verrouillage.

• -?|-h|--help

  Affiche une description de l’utilisation de la commande.

• --ignore-failed-sources

  N’avertit en cas d’échec des sources que si des packages répondent aux exigences de versions.

• --interactive

  Permet à la commande de s’arrêter et d’attendre une action ou une entrée utilisateur. Par exemple, pour effectuer une authentification.

• --lock-file-path <LOCK_FILE_PATH>

  Emplacement de sortie où le fichier de verrouillage du projet est écrit. Par défaut, il s’agit de PROJECT_ROOT\packages.lock.json.

• --locked-mode

  Ne pas autoriser la mise à jour du fichier de verrouillage du projet.

• --no-cache

  Spécifie de ne pas mettre en cache les requêtes HTTP.

• --no-dependencies

  En cas de restauration d’un projet avec des références entre projets (P2P), restaure le projet racine et non les références.

• --packages <PACKAGES_DIRECTORY>

  Spécifie le répertoire des packages restaurés.

• -r|--runtime <RUNTIME_IDENTIFIER>

  Spécifie un runtime pour la restauration du package. Cela permet de restaurer les packages des runtimes qui ne sont pas explicitement listés dans la balise <RuntimeIdentifiers> du fichier .csproj. Pour connaître les identificateurs de runtime, consultez le catalogue des identificateurs de runtime.

• -s|--source <SOURCE>

  Spécifie l’URI de la source du package NuGet à utiliser pendant l’opération de restauration. Ce paramètre remplace toutes les sources spécifiées dans les fichiers nuget.config. Vous pouvez spécifier plusieurs sources en spécifiant cette option plusieurs fois.

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

  Spécifie si l’enregistreur d’événements de terminal doit être utilisé pour la sortie de build. La valeur par défaut est auto, qui vérifie d’abord l’environnement avant d’activer la journalisation du terminal. La vérification de l’environnement vérifie que le terminal est capable d’utiliser des fonctionnalités de sortie modernes et n’utilise pas une sortie standard redirigée avant d’activer le nouvel enregistreur d’événements. on ignore la vérification de l’environnement et active la journalisation du terminal. off ignore la vérification de l’environnement et utilise l’enregistreur d’événements de console par défaut.

  L’enregistreur d’événements de terminal affiche la phase de restauration suivie par la phase de génération. Au cours de chaque phase, les projets en cours de génération apparaissent en bas du terminal. Chaque projet en cours de génération génère à la fois la cible MSBuild en cours de génération et le temps consacré à cette cible. Vous pouvez rechercher ces informations pour en savoir plus sur la génération. Lorsque la génération d’un projet est terminée, une unique section « build terminée » est écrite et capture :

  • Le nom du projet généré.
  • Le framework cible (si plusieurs cibles).
  • L’état de cette build.
  • La sortie principale de cette génération (qui est un lien hypertexte).
  • Les diagnostics générés pour ce projet.

  Cette option est disponible à partir de .NET 8.

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

  Définit RuntimeIdentifier sur un RuntimeIdentifier portable sur plateforme basée sur l’un de vos ordinateurs. Cela se produit implicitement avec les propriétés qui nécessitent un RuntimeIdentifier, comme SelfContained, PublishAot, PublishSelfContained, PublishSingleFile et PublishReadyToRun. Si la propriété a la valeur false, cette résolution implicite ne se produit plus.

• --use-lock-file

  Permet au fichier de verrouillage du projet d'être généré et utilisé avec la restauration.

• -v|--verbosity <LEVEL>

  Définit le niveau de détail de la commande. Les valeurs autorisées sont q[uiet], m[inimal], n[ormal], d[etailed] et diag[nostic]. La valeur par défaut est minimal. Pour plus d'informations, consultez LoggerVerbosity.

Exemples

• Restaurez des dépendances et des outils pour le projet se trouvant dans le répertoire actif :

  dotnet restore
  

• Restaurez des dépendances et des outils pour le projet app1 se trouvant à l’emplacement donné :

  dotnet restore ./projects/app1/app1.csproj
  

• Restaurer les dépendances et les outils du projet se trouvant dans le répertoire actif en utilisant le chemin d’accès de fichier fourni comme source :

  dotnet restore -s c:\packages\mypackages
  

• Restaurer les dépendances et les outils du projet se trouvant dans le répertoire actif en utilisant les deux chemins d’accès de fichiers fournis comme sources :

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

• Restaurer les dépendances et les outils du projet dans le répertoire actif affichant une sortie détaillée :

  dotnet restore --verbosity detailed
  

Audit des vulnérabilités de sécurité

À compter de .NET 8, vous pouvez opter pour l’audit de sécurité NuGet pour dotnet restore. Cet audit produit un rapport sur les vulnérabilités de sécurité avec le nom du package affecté, la gravité de la vulnérabilité et un lien vers l’avis pour plus de détails.

Pour choisir l’audit de sécurité, définissez la propriété MSBuild <NuGetAudit> sur true dans votre Fichier projet. En outre, pour récupérer le jeu de données de vulnérabilité connu, vérifiez que le registre central NuGet.org est défini comme l’une de vos sources de package :

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

Vous pouvez configurer le niveau auquel l’audit échouera en définissant la propriété MSBuild <NuGetAuditLevel>. Les valeurs possibles sont low, moderate, high et critical. Par exemple, si vous souhaitez voir uniquement les avis modérés, élevés et critiques, vous pouvez définir la propriété sur moderate.