Sélectionner la version .NET à utiliser

  • Article

Cet article explique les stratégies utilisées par les outils .NET, le kit SDK et le runtime pour sélectionner les versions. Ces stratégies concilient l’exécution des applications avec les versions spécifiées et la facilité de mise à niveau des machines des développeurs et des utilisateurs finaux. Ces stratégies permettent :

  • Déploiement facile et efficace de .NET, notamment des mises à jour de sécurité et de fiabilité.
  • Utilisation des outils et des commandes les plus récents, indépendamment du runtime cible.

La sélection de version s’opère dans les cas suivants :

Le reste de ce document examine ces quatre scénarios.

Le kit SDK utilise la dernière version installée

Les commandes du kit SDK incluent dotnet new et dotnet run. L’interface CLI .NET doit choisir une version du Kit SDK pour chaque commande dotnet. Par défaut, elle utilise le dernier Kit SDK installé sur la machine, même si :

  • Le projet cible une version antérieure du runtime .NET.
  • La dernière version du Kit SDK .NET est une préversion.

Vous pouvez tirer parti des fonctionnalités et des améliorations du dernier kit SDK tout en ciblant des versions antérieures du runtime .NET. Vous pouvez cibler différentes versions du runtime de .NET à l’aide des mêmes outils du SDK.

À de rares occasions, vous pouvez être amené à utiliser une version antérieure du kit SDK. Vous devez dans ce cas spécifier cette version dans un fichier global.json. La stratégie « utiliser la dernière version » signifie que vous utilisez uniquement global.json pour spécifier une version du kit SDK .NET antérieure à la dernière version installée.

global.json peut être placé n’importe où dans la hiérarchie des fichiers. L’interface CLI effectue une recherche vers le haut dans le répertoire du projet et s’arrête au premier fichier global.json trouvé. Vous pouvez contrôler les projets auxquels un fichier global.json donné s’applique par son emplacement dans le système de fichiers. L’interface CLI .NET recherche un fichier global.json de manière itérative en parcourant le chemin de bas en haut dans le répertoire de travail actif. Le premier fichier global.json trouvé spécifie la version utilisée. Si cette version du SDK est installée, elle est utilisée. Si le SDK spécifié dans le fichier global.json est introuvable, l’interface CLI .NET utilise des règles correspondantes pour sélectionner un SDK compatible ou échoue si aucun n’est trouvé.

L’exemple suivant présente la syntaxe du fichier global.json :

{
  "sdk": {
    "version": "5.0.0"
  }
}

Le processus de sélection d’une version du kit SDK est le suivant :

  1. dotnet recherche un fichier global.json en remontant de manière itérative le chemin dans le répertoire de travail actif.
  2. dotnet utilise le kit SDK spécifié dans le premier fichier global.json trouvé.
  3. dotnet utilise la dernière version du kit SDK installé si aucun fichier global.json n’est trouvé.

Pour plus d’informations sur la sélection de la version du SDK, consultez les sections Règles de correspondance et rollForward de l’article vue d’ensemble de global.json.

Les monikers de framework cible définissent les API au moment de la génération

Vous générez votre projet par rapport aux API définies dans un moniker de framework cible (TFM). Vous devez spécifier la version cible de .Net Framework dans le fichier projet. Définissez l’élément TargetFramework dans votre fichier projet comme indiqué dans l’exemple suivant :

<TargetFramework>net5.0</TargetFramework>

Vous pouvez générer votre projet par rapport à plusieurs TFM. S’il est plus courant de définir plusieurs versions cibles de .Net Framework pour les bibliothèques, cela est également possible dans le cas des applications. Pour cela, vous devez spécifier une propriété TargetFrameworks (pluriel de TargetFramework). Les versions cibles de .Net Framework sont séparées par un point-virgule, comme le montre l’exemple suivant :

<TargetFrameworks>net5.0;netcoreapp3.1;net47</TargetFrameworks>

Un kit SDK donné prend en charge un ensemble fixe de versions de .Net Framework, plafonné à la version cible de .Net Framework du runtime qu’il intègre. Par exemple, le kit SDK .NET 5 comprend le runtime .NET 5, qui est une implémentation de la version cible de .Net Framework net5.0. Le kit SDK .NET 5 prend en charge netcoreapp2.0, netcoreapp2.1, netcoreapp3.0, etc., mais pas net6.0 (ou version ultérieure). L’installation du kit SDK .NET 6 vise à générer pour net6.0.

.NET Standard

.NET Standard était un moyen de cibler une surface d’API partagée par différentes implémentations de .NET. À compter de la version de .NET 5, qui est une norme d’API elle-même, .NET Standard a peu de pertinence, à l’exception d’un scénario : .NET Standard est utile lorsque vous souhaitez cibler à la fois .NET et .NET Framework. .NET 5 implémente toutes les versions de .NET Standard.

Pour plus d'informations, consultez NET 5 et .NET Standard.

Les applications dépendantes du framework font l’objet d’une restauration par progression

Lorsque vous exécutez une application à partir d’une source avec dotnet run, à partir d’un déploiement dépendant du framework avec dotnet myapp.dll, ou à partir d’un exécutable dépendant du framework avec myapp.exe, l’exécutable dotnet est l’hôte de l’application.

L’hôte choisit la dernière version de correctif installée sur la machine. Par exemple, si vous avez spécifié net5.0 dans votre fichier projet et que 5.0.2 est le dernier runtime .NET installé, le runtime 5.0.2 est utilisé.

Si aucune version acceptable de 5.0.* n’est trouvée, une nouvelle version 5.* est utilisée. Par exemple, si vous avez spécifié net5.0 et que seule la version 5.1.0 est installée, l’application s’exécute en utilisant le runtime 5.1.0. Ce comportement est appelé « restauration par progression de version mineure ». Les versions inférieures ne seront pas non plus prises en compte. Quand aucun runtime acceptable n’est installé, l’application ne s’exécute pas.

Voici quelques exemples d’utilisation pour illustrer le comportement, si vous ciblez la version 5.0 :

  • ✔️ 5.0 est spécifié. La version 5.0.3 est la version de correctif installée la plus élevée. La version 5.0.3 est utilisée.
  • ❌ 5.0 est spécifié. Aucune version 5.0.* n’est installée. La version 3.1.1 correspond à la version de runtime installée la plus élevée. Un message d’erreur s’affiche.
  • ✔️ 5.0 est spécifié. Aucune version 5.0.* n’est installée. La version 5.1.0 correspond à la version de runtime installée la plus élevée. La version 5.1.0 est utilisée.
  • ❌ 3.0 est spécifié. Aucune version 3.x n’est installée. La version 5.0.0 correspond à la version de runtime installée la plus élevée. Un message d’erreur s’affiche.

La restauration par progression de la version mineure présente un effet secondaire qui peut toucher les utilisateurs finaux. Examinez le cas suivant :

  1. L’application spécifie que 5.0 est obligatoire.
  2. En cas d’exécution, la version 5.0.* n’est pas installée, mais la version 5.1.0 l’est. La version 5.1.0 sera utilisée.
  3. Plus tard, l’utilisateur installe la version 5.0.3 et réexécute l’application. La version 5.0.3 sera maintenant utilisée.

Il est possible que les versions 5.0.3 et 5.1.0 se comportent différemment, en particulier dans certains scénarios comme la sérialisation de données binaires.

Contrôler le comportement de la restauration par progression

Avant de remplacer le comportement de restauration par progression par défaut, familiarisez-vous avec le niveau de compatibilité du runtime .NET.

Le comportement de restauration par progression pour une application peut être configuré de quatre façons différentes :

  1. Paramètre au niveau du projet en définissant la propriété <RollForward> :

    <PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

  2. Le fichier *.runtimeconfig.json.

    Ce fichier est généré lorsque vous compilez votre application. Si la propriété <RollForward> a été définie dans le projet, elle est reproduite dans le fichier *.runtimeconfig.json en tant que paramètre rollForward. Les utilisateurs peuvent modifier ce fichier, afin de changer le comportement de votre application.

    {
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}

  3. Propriété dotnet de la --roll-forward <value> commande.

    Lorsque vous exécutez une application, vous pouvez contrôler le comportement de la restauration par progression par le biais de la ligne de commande :

    dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor

  4. La variable d'environnement DOTNET_ROLL_FORWARD.

Priorité

Le comportement de progression par définition est défini dans l’ordre suivant lors de l’exécution de votre application, les éléments numérotés plus élevés étant prioritaires sur les éléments numérotés inférieurs :

  1. Tout d’abord, le fichier de configuration *.runtimeconfig.json est évalué.
  2. Ensuite, la variable d’environnement DOTNET_ROLL_FORWARD est prise en compte, en remplaçant la vérification précédente.
  3. Enfin, tout paramètre --roll-forward passé à l’application en cours d’exécution remplace tout le reste.

Valeurs

Toutefois, lorsque vous définissez le paramètre de restauration par progression, utilisez l’une des valeurs suivantes pour définir le comportement :

Valeur Description
Minor Par défaut si non spécifiée.
Restauration par progression vers la version mineure supérieure la plus basse, si la version mineure demandée est manquante. Si la version mineure demandée est présente, la stratégie LatestPatch est utilisée.
Major Restauration par progression vers la version majeure supérieure suivante disponible, et la version mineure la plus basse, si la version majeure demandée est manquante. Si la version majeure demandée est présente, la stratégie Minor est utilisée.
LatestPatch Restauration par progression vers la version de correctif la plus élevée. Cette valeur désactive la restauration par progression d’une version mineure.
LatestMinor Restauration par progression vers la version mineure la plus élevée, si la version mineure demandée est présente.
LatestMajor Restauration par progression vers la version majeure la plus élevée et la version mineure la plus élevée, si la version majeure demandée est présente.
Disable N’effectuez pas de restauration par progression, mais uniquement à la version spécifiée. Cette stratégie n’est pas recommandée pour une utilisation générale, car elle désactive la possibilité d’effectuer une restauration par progression vers les derniers correctifs. Cette valeur est recommandée uniquement à des fins de test.

Les déploiements autonomes incluent le runtime sélectionné

Vous pouvez publier une application en tant que distribution autonome. Cette approche regroupe le runtime et les bibliothèques .NET avec votre application. Les déploiements autonomes ne dépendent pas des environnements d’exécution. La sélection de la version du runtime se produit au moment de la publication, et non au moment de l’exécution.

L’événement de restaurationqui se produit lors de la publication, sélectionne la dernière version de correctif de la famille de runtime donnée. Par exemple, dotnet publish sélectionne .NET 5.0.3 s’il s’agit de la dernière version de correctif de la famille du runtime .NET 5. La version cible de .Net Framework (y compris les derniers correctifs de sécurité installés) est empaquetée avec l’application.

Une erreur se produit si la version minimale spécifiée pour une application n’est pas satisfaite. dotnet publish se lie à la dernière version de correctif de runtime (au sein d’une famille de version principale.secondaire donnée). dotnet publish ne prend pas en charge la sémantique de restauration par progression de dotnet run. Pour plus d’informations sur les correctifs et les déploiements autonomes, consultez l’article relatif à la sélection de correctif de runtime dans le déploiement d’applications .NET.

Les déploiements autonomes peuvent nécessiter une version de correctif spécifique. Vous pouvez remplacer la version de correctif de runtime minimale (par une version supérieure ou inférieure) dans le fichier projet, comme indiqué dans l’exemple suivant :

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

L’élément RuntimeFrameworkVersion remplace la stratégie de version par défaut. Pour les déploiements autonomes, RuntimeFrameworkVersion spécifie la version exacte du framework du runtime. Pour les applications dépendantes du framework, RuntimeFrameworkVersion spécifie la version minimale requise pour le framework du runtime.

Voir aussi