Sélectionner la version .NET à utiliser

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 :

• Quand vous exécutez une commande du Kit SDK, celui-ci utilise la dernière version installée.
• Quand vous générez un assembly, les monikers de framework cible définissent les API au moment de la génération.
• Quand vous exécutez une application .NET, les applications dépendantes de la version cible de .Net Framework font l’objet d’une restauration par progression.
• Quand vous publiez une application autonome, les déploiements autonomes incluent le runtime sélectionné.

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. 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 en parcourant de manière itérative le chemin vers le haut à partir du répertoire de travail actuel (ce qui n’est pas nécessairement le même que le répertoire du projet). 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 du 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>net8.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>net8.0;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 de développement logiciel (SDK) .NET 8 comprend le runtime .NET 8 qui est une implémentation de la version cible de .Net Framework net8.0. Le kit de développement logiciel (SDK) .NET 8 prend en charge net7.0, net6.0 et net5.0, mais pas net9.0 (ou une version ultérieure). L’installation du kit de développement logiciel (SDK) .NET 9 vise à générer pour net9.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 :

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

• Téléchargez et installez .NET.
• Procédure de suppression du runtime et du SDK .NET.