Vue d’ensemble de global.json

Cet article s’applique à : ✔️ 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 du Kit de développement logiciel (SDK) .NET qui est utilisée lorsque vous exécutez des commandes CLI .NET. La sélection de la version du KIT de développement logiciel (SDK) .NET n’est pas indépendante de la spécification de la version d’exécution cible d’un projet. La version du Kit de développement logiciel (SDK) .NET 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 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 correctif 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 actuel (qui n’est pas nécessairement identique au 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 SDK, consultez Infrastructures cibles.

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 : 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 tenir compte des versions préliminaires 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 si vous exécutez à 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 Options d’outils>Fonctionnalités>d’évaluation del’environnement>), la valeur par défaut est true. Sinon, la valeur par défaut est false.

rollForward

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

Stratégie de substitution à 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 est manquante, soit comme directive pour utiliser une version supé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 correspondantes.

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 mineure.
  • z est la bande de caractéristiques.
  • nn est la version du correctif.

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

Valeur Comportement
patch Utilise la version spécifiée.
S’il est introuvable, effectue la restauration vers le dernier niveau de correctif.
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, mineure 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 majeure/mineure et utilise le dernier niveau de correctif pour cette bande de fonctionnalités.
S’il est introuvable, échoue.
minor Utilise le dernier niveau de correctif pour la bande principale, mineure et de fonctionnalité spécifiée.
S’il est introuvable, effectue la progression vers la bande de fonctionnalités supérieure suivante au sein de la même version majeure/mineure et utilise le dernier niveau de correctif pour cette bande de fonctionnalités.
S’il n’est pas trouvé, effectue une progression vers la catégorie mineure et la bande de caractéristiques supérieures suivantes au sein de la même major et utilise le dernier niveau de correctif pour cette bande de fonctionnalités.
S’il est introuvable, échoue.
major Utilise le dernier niveau de correctif pour la bande principale, mineure et de fonctionnalité spécifiée.
S’il est introuvable, effectue la progression vers la bande de fonctionnalités supérieure suivante au sein de la même version majeure/mineure et utilise le dernier niveau de correctif pour cette bande de fonctionnalités.
S’il n’est pas trouvé, effectue une progression vers la catégorie mineure et la bande de caractéristiques supérieures suivantes au sein de la même major et utilise le dernier niveau de correctif pour cette bande de fonctionnalités.
Si ce n’est pas trouvé, effectue une progression vers la bande de caractéristiques majeure, mineure et supérieure suivante, et utilise le dernier niveau de correctif pour cette bande de fonctionnalités.
S’il est introuvable, échoue.
latestPatch Utilise le dernier niveau de correctif installé qui correspond à la plage principale, mineure et de caractéristiques demandée avec un niveau de correctif et qui est supérieur ou égal à la valeur spécifiée.
S’il est introuvable, échoue.
latestFeature Utilise la bande de fonctionnalités installée et le niveau de correctif le plus élevé qui correspond au niveau principal et mineur demandé avec une bande de fonctionnalités et un niveau de correctif supérieur ou égal à la valeur spécifiée.
S’il est introuvable, échoue.
latestMinor Utilise le niveau secondaire, la bande de fonctionnalités et le niveau de correctif le plus élevé installé qui correspond au niveau majeur demandé avec un niveau mineur, une bande de caractéristiques et un niveau de correctif supérieur ou égal à la valeur spécifiée.
S’il est introuvable, échoue.
latestMajor Utilise le sdk .NET le plus élevé installé avec une version supérieure ou égale à la valeur spécifiée.
S’il est introuvable, échoue.
disable Ne avance pas. Correspondance exacte 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 SDK de projet sont résolus.

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 code 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 correctif installée d’une version majeure et secondaire spécifique. Le json indiqué interdit toute version du KIT de développement logiciel (SDK) antérieure à 3.1.102 et autorise la version 3.1.102 ou toute version ultérieure 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 correctif la plus élevée installée d’une version spécifique. Le code JSON indiqué interdit toute version du SDK antérieure à 3.1.102 et autorise la version 3.1.102 ou toute version ultérieure 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 d’autres versions du Kit de développement logiciel (SDK) .NET sur votre ordinateur, visitez 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 .

Les règles suivantes s’appliquent lors de la détermination de la 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 Fonctionnalités> d’aperçudel’environnement>), les versions préliminaires sont prises en compte ; sinon, seules les versions release sont prises en compte.
  • Si un fichier global.json est trouvé qui ne spécifie pas de version du Kit de développement logiciel (SDK), mais qu’il spécifie une allowPrerelease valeur, la version installée la plus élevée du KIT de développement logiciel (SDK) est utilisée (ce qui équivaut à définir 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. Voir: https://aka.ms/dotnet-core-preview

    Les versions du Kit de développement logiciel (SDK) .NET ont un historique et un engagement 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 machines qui n’ont jamais été installées 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.

  • L’avertissement suivant indique que votre projet cible EF Core 1.0 ou 1.1, qui n’est pas compatible avec le 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 souhaitée du SDK à l’aide du fichier global.json . Pour plus d’informations sur la commande dotnet ef, consultez Outils en ligne de commande EF Core .NET.

Voir aussi