Vue d’ensemble de global.json

Article
06/03/2023

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

Le fichier global.json vous permet de définir la version du kit de développement logiciel (SDK) .NET utilisée pendant l’exécution des commandes de l’interface 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 du runtime ciblé par votre projet. La version du kit de développement logiciel (SDK) .NET indique la version de l’interface de commande .NET à utiliser. 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 rollForward fonctionnalité qui fournit des moyens flexibles de spécifier une plage acceptable de versions. Par exemple, le fichier global.json suivant sélectionne 6.0.300 ou toute bande de fonctionnalités ou patch ultérieur pour la version 6.0 installée sur l’ordinateur :

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

Le kit de développement logiciel (SDK) .NET recherche un fichier global.json dans le répertoire de travail actif (qui n’est pas nécessairement le même que le répertoire du projet) ou dans l’un de ses répertoires parents.

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 : object

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

version

Entrez : string

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

Ce champ :

N’a pas de prise en charge de caractères génériques ; autrement dit, vous devez spécifier le numéro de version complet.
Ne prend pas en charge les plages de versions.

allowPrerelease

Entrez : boolean
Disponible depuis : le kit de développement logiciel (SDK) .NET 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 à partir de Visual Studio :

Si vous n’êtes pas dans Visual Studio, la valeur par défaut est true.
Si vous êtes dans Visual Studio, il utilise l’état de préversion demandé. Autrement dit, si vous utilisez une version d’évaluation de Visual Studio ou si vous définissez l’option Utiliser les préversions du kit de développement logiciel (SDK) .NET (sous Outils>Options>Environnement>Fonctionnalités d'évaluation), la valeur par défaut est true. Sinon, la valeur par défaut est false.

rollForward

Entrez : string
Disponible depuis : le kit de développement logiciel (SDK) .NET Core 3.0.

Stratégie de restauration par progression à utiliser lors de la sélection d’une version du kit de développement logiciel (SDK), soit comme secours lorsqu’une version spécifique du kit de développement logiciel (SDK) est manquante, soit en tant que directive pour utiliser une version ultérieure. Une version doit être spécifiée avec une rollForward valeur, sauf si vous la définissez sur latestMajor. Le comportement de la restauration 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 x.y.znn :

x est la version principale.
y est la version secondaire.
z est la bande de caractéristiques.
nn est la version du patch.

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

Valeur	Comportement
`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 à la bande principale, secondaire et de fonctionnalité demandée avec un niveau de patch et supérieur ou égal à la valeur spécifiée. S’il est introuvable, échoue.
`latestFeature`	Utilise la bande de fonctionnalités et le niveau de patch 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.
`latestMinor`	Utilise 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 kit de développement logiciel (SDK) .NET 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.

msbuild-sdks

Entrez : object

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.

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": "7.0.100" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Exemples

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 à 2.2.200 et autorise la version 2.2.200 ou toute version ultérieure, y compris 3.0.xxx et 3.1.xxx.

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

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

{
  "sdk": {
    "version": "3.1.100",
    "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 3.1.102 et autorise la version 3.1.102 ou toute version ultérieure à la version 3.1.xxx, telle que 3.1.103 ou 3.1.200.

{
  "sdk": {
    "version": "3.1.102",
    "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 3.1.102 et autorise la version 3.1.102 ou toute version ultérieure à la version 3.1.1xx, telle que 3.1.103 ou 3.1.199.

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

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 procédure à suivre, consultez Comment vérifier que .NET est déjà installé.

Pour installer des versions supplémentaires du kit de développement logiciel (SDK) .NET sur votre ordinateur, accédez à la page Télécharger .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 6.0.100

Règles de correspondance

Notes

Les règles de correspondance sont régies par le dotnet.exe point d’entrée, qui est commun à tous les runtimes .NET installés. Les règles correspondantes pour la dernière version installée du runtime .NET sont utilisées lorsque vous avez plusieurs runtimes installés côte à côte ou si 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 allowPrerelease valeur, la version la plus élevée du kit de développement logiciel (SDK) installée est utilisée (équivalent à la définition rollForward de latestMajor). La prise en compte des versions préliminaires du kit de développement logiciel (SDK) dépend de la façon dont dotnet est appelée :
- Si vous n’êtes pas dans Visual Studio, les versions préliminaires sont prises en compte.
- Si vous êtes dans Visual Studio, il utilise l’état de préversion demandé. En d’autres termes, si vous utilisez une préversion de Visual Studio ou si vous définissez l’option Utiliser les préversions du kit de développement logiciel (SDK) .NET (sous Outils>Options>Environnement>Fonctionnalités d'évaluation), les versions préliminaires sont prises en compte ; sinon, seules les versions de mise en production 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 allowPrerelease, la version la plus élevée du kit de développement logiciel (SDK) installée est utilisée (équivalent à la définition de rollForward sur latestMajor). 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 allowPrerelease. true indique que les versions préliminaires sont prises en compte ; false 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 rollForward définie, elle utilise latestPatch comme stratégie par défaut rollForward. 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 allowPrerelease 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 du kit SDK .NET Core. Vous pouvez définir la version du kit SDK via un fichier global.json dans le projet actif. Pour plus d’informations, consultez https://go.microsoft.com/fwlink/?linkid=869452.

Vous utilisez une préversion de .NET. Consultez : https://aka.ms/dotnet-core-preview

Les versions du kit de développement logiciel (SDK) .NET jouissent d’un historique et d’un engagement de 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 été installés avec un runtime ou un kit de développement logiciel (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.
Cet avertissement indique que votre projet cible EF Core 1.0 ou 1.1, qui n’est pas compatible avec le kit de développement logiciel (SDK) .NET Core 2.1 et les 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 supérieure. Pour plus d’informations sur l’utilisation d’anciennes versions des outils, consultez https://go.microsoft.com/fwlink/?linkid=871254.

À partir du kit SDK .NET Core 2.1 (version 2.1.300), la commande dotnet ef est incluse dans le kit SDK. Pour compiler votre projet, installez le kit de développement logiciel (SDK) .NET Core 2.0 (version 2.1.201) ou une version antérieure sur votre ordinateur et définissez la version du kit de développement logiciel (SDK) à utiliser dans le fichier global.json. Pour plus d’informations sur la commande dotnet ef, consultez Outils en ligne de commande EF Core .NET.
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 jamais qu’une seule copie du SDK .NET. Par conséquent, si vous mettez à niveau votre version de Visual Studio, il supprime la version précédente du Kit de développement logiciel (SDK) .NET qu’il utilisait pour installer la nouvelle version. Il supprime l’ancienne version même si c’est une autre version majeure de .NET.

Pour éviter que Visual Studio supprime les versions du Kit de développement logiciel (SDK) .NET, vous devez installer le SDK .NET autonome depuis la page de téléchargement. Notez que si vous faites cela, vous ne recevrez plus les mises à jour automatiques vers cette version du Kit de développement logiciel (SDK) .NET via Visual Studio et vous risquez de rencontrer des problèmes de sécurité.

Voir aussi

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