Vue d’ensemble de global.json

Cet article s’applique au Kit de développement logiciel (SDK) ✔️ .NET Core 3.1 et versions ultérieures

Le fichier global.json vous permet de définir la version .NET SDK utilisée lorsque vous exécutez des commandes CLI .NET. La sélection de la version du KIT de développement logiciel (SDK) .NET est indépendante de la spécification de la version d’exécution cible d’un projet. La version .NET SDK indique quelle version de l’interface CLI .NET est utilisée. Cet article explique comment sélectionner la version du kit de développement logiciel (SDK) à l’aide de global.json.

Si vous souhaitez toujours utiliser la dernière version du kit de développement logiciel (SDK) installée sur votre ordinateur, aucun fichier global.json n’est nécessaire. Toutefois, dans les scénarios CI (intégration continue), vous souhaitez généralement spécifier une plage acceptable pour la version du kit de développement logiciel (SDK) utilisée. Le fichier global.json dispose d’une fonctionnalité qui fournit des moyens flexibles de spécifier une plage acceptable de versions. Par exemple, le fichier global.json suivant sélectionne 10.0.100 ou toute bande de fonctionnalités ou correctif ultérieur pour la version 10.0 installée sur l’ordinateur :

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  }
}

Vous vous appuyez sur deux composants du Kit de développement logiciel (SDK) .NET pour rechercher un fichier global.json. Chaque composant commence à partir d’un emplacement différent et effectue des recherches dans les répertoires ancêtres :

• .NET sdk muxer gère les commandes CLI dotnet. Il commence à partir du répertoire de travail actuel, ce qui n’est pas nécessairement le même que le répertoire du projet.
• Résolveur SDK de projet .NET MSBuild résout les kits SDK de projet pendant les compilations. Il commence à partir du répertoire qui contient un fichier de solution, s’il en existe un. Si aucun fichier solution n’existe, il commence à partir du répertoire qui contient le fichier projet actuel. Si aucun fichier n’existe, il utilise le répertoire de travail actuel.

Pour plus d’informations sur la spécification de la version du runtime au lieu de la version du kit de développement logiciel (SDK), consultez version cible de .Net Framework.

Schéma de global.json

sdk

Entrez :

Spécifie des informations sur le Kit de développement logiciel (SDK) .NET à sélectionner.

version

• Entrez :

Version du Kit de développement logiciel (SDK) .NET à utiliser.

Ce champ :

• Nécessite le numéro de version complet, tel que 10.0.100.
• Ne prend pas en charge les numéros de version tels que 10, 10.0 ou 10.0.x.
• Ne prend pas en charge les caractères génériques.
• Ne prend pas en charge les plages de versions.

allowPrerelease

• Entrez :
• Disponible depuis : .NET Kit de développement logiciel (SDK) Core 3.0.

Indique si le programme de résolution du kit de développement logiciel (SDK) doit prendre en compte les préversions lors de la sélection de la version du kit de développement logiciel (SDK) à utiliser.

Si vous ne définissez pas cette valeur explicitement, la valeur par défaut dépend de l'exécution de Visual Studio :

• Si vous êtes not dans Visual Studio, la valeur par défaut est true.
• Si vous êtes dans Visual Studio, il utilise le statut de préversion demandé. Autrement dit, si vous utilisez une préversion de Visual Studio ou si vous définissez l'option Utiliser les préversions du SDK .NET (sous Outils>Options>Environnement>Fonctionnalités en préversion), la valeur par défaut est true. Sinon, la valeur par défaut est .

rollForward

• Entrez :
• Disponible depuis : .NET Kit de développement logiciel (SDK) Core 3.0.

Stratégie de progression à utiliser lors de la sélection d’une version du kit de développement logiciel (SDK), en cas d'absence d'une version spécifique ou comme directive pour utiliser une version ultérieure. Une version doit être spécifiée avec une valeur, sauf si vous la définissez sur . Le comportement de progression par défaut est déterminé par les règles de correspondance.

Pour comprendre les stratégies disponibles et leur comportement, tenez compte des définitions suivantes pour une version du kit de développement logiciel (SDK) au format  :

• est la version principale.
• est la version secondaire.
• est la bande de caractéristiques.
• est la version du patch.

Le tableau suivant montre les valeurs possibles pour la clé  :

Value	Behavior
patch	Utilise la version spécifiée. S’il est introuvable, effectue la restauration vers le dernier niveau de patch. S’il est introuvable, échoue. Cette valeur est le comportement hérité des versions antérieures du kit de développement logiciel (SDK).
feature	Utilise le dernier niveau de correctif pour la bande principale, secondaire et de fonctionnalité spécifiée. S’il est introuvable, effectue une progression vers la bande de fonctionnalités supérieure suivante au sein de la même catégorie principale/secondaire et utilise le dernier niveau de patch pour cette bande de fonctionnalités. S’il est introuvable, échoue.
minor	Utilise le dernier niveau de correctif pour la bande principale, secondaire et de fonctionnalité spécifiée. S’il est introuvable, effectue une progression vers la bande de fonctionnalités supérieure suivante au sein de la même version principale/secondaire et utilise le dernier niveau de patch pour cette bande de fonctionnalités. S’il est introuvable, effectue une progression vers la bande supérieure, secondaire et de fonctionnalité suivantes au sein de la même catégorie majeure et utilise le dernier niveau de patch pour cette bande de fonctionnalités. S’il est introuvable, échoue.
major	Utilise le dernier niveau de correctif pour la bande principale, secondaire et de fonctionnalité spécifiée. S’il est introuvable, effectue une progression vers la bande de fonctionnalités supérieure suivante au sein de la même version principale/secondaire et utilise le dernier niveau de patch pour cette bande de fonctionnalités. S’il est introuvable, effectue une progression vers la bande supérieure, secondaire et de fonctionnalité suivantes au sein de la même catégorie majeure et utilise le dernier niveau de patch pour cette bande de fonctionnalités. S’il est introuvable, effectue une progression vers la bande principale, secondaire et de fonctionnalité suivantes et utilise le dernier niveau de patch pour cette bande de fonctionnalités. S’il est introuvable, échoue.
latestPatch	Utilise le dernier niveau de correctif installé qui correspond aux versions principale, secondaire et de bande de fonctionnalités demandées, avec un niveau de correctif supérieur ou égal à la valeur spécifiée. S’il est introuvable, échoue.
latestFeature	Utilise la bande de fonctionnalité et le niveau de correctif installés les plus élevés qui correspondent à la version majeure et mineure demandée, avec une bande de fonctionnalité et un niveau de correctif supérieurs ou égaux à la valeur spécifiée. S’il est introuvable, échoue.
latestMinor	Utilise la bande secondaire, la bande de fonctionnalités et le niveau de correctif installés les plus élevés qui correspondent aux principaux et secondaires demandés, avec un niveau de bande de fonctionnalité et un niveau de correctif supérieur ou égal à la valeur spécifiée. S’il est introuvable, échoue.
latestMajor	Utilise le sdk .NET installé le plus élevé avec une version supérieure ou égale à la valeur spécifiée. S’il est introuvable, échec.
disable	Ne se restaure pas par progression. Une correspondance exacte est requise.

paths

• Type : tableau de
• Disponible depuis : .NET 10 SDK.

Spécifie les emplacements à prendre en compte lors de la recherche d’une .NET SDK compatible. Les chemins d’accès peuvent être absolus ou relatifs à l’emplacement du fichier global.json . La valeur spéciale représente l’emplacement correspondant à l’exécutable en cours d’exécution .

Ces chemins d’accès sont recherchés dans l’ordre dans lequel ils sont définis et le premier sdk correspondant est utilisé.

Cette fonctionnalité permet d’utiliser des installations de SDK locales (par exemple, des kits sdk relatifs à une racine de référentiel ou placées dans un dossier personnalisé) qui ne sont pas installées globalement sur le système.

La fonctionnalité « chemins » fonctionne uniquement lors de l’utilisation de commandes qui impliquent le SDK .NET, comme dotnet run. Il n’affecte pas les scénarios tels que l’exécution du lanceur apphost natif (), l’exécution avec ou l’exécution avec . Pour utiliser la fonctionnalité « chemins d’accès », vous devez utiliser des commandes sdk telles que .

errorMessage

• Entrez :
• Disponible depuis : .NET 10 SDK.

Spécifie un message d'erreur personnalisé affiché lorsque le programme de résolution du KIT de développement logiciel (SDK) ne trouve pas de kit de développement logiciel (SDK) compatible .NET.

msbuild-sdks

Entrez :

Vous permet de contrôler la version du kit de développement logiciel (SDK) du projet au lieu de chaque projet individuel. Pour plus d’informations, consultez Comment les kits de développement logiciel (SDK) de projet sont résolus.

test

• Entrez :

Spécifie des informations sur les tests.

runner

• Entrez :
• Disponible depuis : .NET SDK 10.0.

Exécuteur de test avec lequel découvrir/exécuter des tests.

Commentaires dans global.json

Les commentaires dans les fichiers global.json sont pris en charge à l’aide des commentaires de style JavaScript ou C#. Par exemple:

{
   // This is a comment.
  "sdk": {
    "version": "8.0.300" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Examples

L’exemple suivant montre comment ne pas utiliser les versions préliminaires :

{
  "sdk": {
    "allowPrerelease": false
  }
}

L’exemple suivant montre comment utiliser la version la plus élevée installée supérieure ou égale à la version spécifiée. Le JSON indiqué interdit toute version du kit de développement logiciel (SDK) antérieure à 7.0.200 et autorise la version 7.0.200 ou toute version ultérieure, y compris 8.0.xxx et 3.1.xxx.

{
  "sdk": {
    "version": "7.0.200",
    "rollForward": "latestMajor"
  }
}

L’exemple suivant montre comment utiliser la version spécifiée exactement :

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "disable"
  }
}

L’exemple suivant montre comment utiliser la dernière bande de fonctionnalités et la dernière version de patch installée d’une version principale et secondaire spécifique. Le JSON indiqué interdit toute version du kit de développement logiciel (SDK) antérieure à la version 8.0.302 et autorise la version 8.0.302 ou toute version ultérieure à la version 8.0.xxx, telle que 8.0.303 ou 8.0.402.

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "latestFeature"
  }
}

L’exemple suivant montre comment utiliser la version de patch la plus élevée installée d’une version spécifique. Le JSON indiqué interdit toute version du kit de développement logiciel (SDK) antérieure à la version 8.0.102 et autorise la version 8.0.102 ou toute version ultérieure à la version 8.0.1xx, telle que 8.0.103 ou 8.0.199.

{
  "sdk": {
    "version": "8.0.102",
    "rollForward": "latestPatch"
  }
}

L’exemple suivant montre comment spécifier d’autres chemins de recherche du SDK et un message d’erreur personnalisé :

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

L’exemple suivant montre une version non valide spécifiée. La sortie de la commande affiche le message d’erreur : « La version « 10.0 » n’est pas valide pour la valeur « sdk/version ».

{
  "sdk": {
    "version": "10.0",
    "rollForward": "latestFeature"
  }
}

L’exemple suivant montre comment spécifier comme exécuteur de test :

{
    "test": {
        "runner": "Microsoft.Testing.Platform"
    }
}

global.json et l’interface CLI .NET

Pour définir une version du kit de développement logiciel (SDK) dans le fichier global.json, il est utile de savoir quelles versions du kit de développement logiciel (SDK) sont installées sur votre ordinateur. Pour plus d’informations sur la façon de procéder, consultez How to check that .NET is already installed.

Pour installer d’autres versions .NET SDK sur votre ordinateur, consultez la page Download .NET.

Vous pouvez créer un fichier global.json dans le répertoire actif en exécutant la commande dotnet new, comme dans l’exemple suivant :

dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature

Règles de correspondance

Note

Les règles de correspondance sont régies par le point d’entrée dotnet.exe, commun à tous les runtimes installés .NET. Les règles de correspondance pour la dernière version installée du runtime .NET sont utilisées lorsque plusieurs runtimes sont installés côte à côte ou si vous utilisez un fichier global.json.

Voici les règles qui s’appliquent pour déterminer quelle version du kit de développement logiciel (SDK) utiliser :

• Si aucun fichier global.json n’est trouvé, ou si global.json ne spécifie pas de version du kit de développement logiciel (SDK) ni de valeur, la version la plus élevée du kit de développement logiciel (SDK) installée est utilisée (équivalent à la définition de ). La prise en compte des versions préliminaires du kit de développement logiciel (SDK) dépend de la façon dont est appelée :

  • Si vous n'êtes pas dans Visual Studio, les versions préliminaires sont prises en compte.
  • Si vous utilisez Visual Studio, il utilise le statut de prerelease demandé. Autrement dit, si vous utilisez une préversion de Visual Studio ou si vous définissez l'option Utiliser les préversions du SDK .NET (sous Outils>Options>Environnement>Fonctionnalités en préversion), les versions préliminaires sont prises en compte ; sinon, seules les versions finales sont prises en compte.

• Si un fichier global.json est trouvé et qu’il ne spécifie pas de version du kit de développement logiciel (SDK), mais qu’il spécifie une valeur , la version la plus élevée du kit de développement logiciel (SDK) installée est utilisée (équivalent à la définition de sur ). La mise en production ou la préversion de la dernière version du kit de développement logiciel (SDK) dépend de la valeur de . indique que les versions préliminaires sont prises en compte ; indique que seules les versions de mise en production sont prises en compte.

• Si un fichier global.json est trouvé et qu’il spécifie une version du kit de développement logiciel (SDK) :

  • Si aucune valeur n'est définie, elle utilise comme politique par défaut. Sinon, vérifiez chaque valeur et leur comportement dans la section rollForward.
  • Si les versions préliminaires sont prises en compte et quel est le comportement par défaut quand n’est pas défini est décrit dans la section allowPrerelease.

Résoudre les problèmes liés aux avertissements de build

• Les avertissements suivants indiquent que votre projet a été compilé à l’aide d’une version préliminaire du Kit de développement logiciel (SDK) .NET :

  Vous utilisez une préversion de .NET. Consultez :

  .NET versions du Kit de développement logiciel (SDK) ont un historique et un engagement d’être de haute qualité. Toutefois, si vous ne souhaitez pas utiliser une version préliminaire, vérifiez les différentes stratégies que vous pouvez utiliser dans la section allowPrerelease. Pour les ordinateurs qui n’ont jamais eu de runtime ou sdk .NET Core 3.0 ou version ultérieure, vous devez créer un fichier global.json et spécifier la version exacte que vous souhaitez utiliser.

• L'avertissement suivant indique que votre projet cible EF Core 1.0 ou 1.1, qui n'est pas compatible avec .NET Kit de développement logiciel (SDK) Core 2.1 et versions ultérieures :

  Le projet de démarrage '{startupProject}' cible le framework '.NETCoreApp' version '{targetFrameworkVersion}'. Cette version des outils en ligne de commande Entity Framework Core .NET prend uniquement en charge la version 2.0 ou ultérieure. Pour plus d’informations sur l’utilisation d’anciennes versions des outils, consultez .

  À compter de .NET KIT SDK Core 2.1 (version 2.1.300), la commande dotnet ef est incluse dans le Kit de développement logiciel (SDK). Pour compiler votre projet, installez .NET Kit de développement logiciel (SDK) Core 2.0 (version 2.1.201) ou une version antérieure sur votre ordinateur et définissez la version souhaitée du SDK à l’aide du fichier global.json. Pour plus d’informations sur la commande dotnet ef, consultez EF Core .NET Outils en ligne de commande.

• Si vous utilisez global.json pour rester sur une version spécifique du Kit de développement logiciel (SDK) .NET, notez que Visual Studio n'installe qu'une seule copie du SDK .NET. Par conséquent, si vous mettez à niveau votre version de Visual Studio, elle supprime la version précédente du SDK .NET qu’elle avait utilisée pour installer la nouvelle version. Il supprime l'ancienne version même s'il s'agit d'une autre version majeure .NET.

Pour éviter que Visual Studio ne supprime les versions du SDK .NET, installez le SDK .NET autonome à partir de la page téléchargement. Toutefois, si vous le faites, vous n'obtiendrez plus de mises à jour automatiques vers cette version du KIT de développement logiciel (SDK) .NET via Visual Studio et risquez de rencontrer des problèmes de sécurité.

Voir aussi

• Méthode de résolution des kits SDK de projet