Frameworks cibles dans les projets de style SDK

Article
11/28/2022
11 minutes de lecture

Quand vous ciblez un framework dans une application ou une bibliothèque, vous spécifiez l’ensemble d’API que vous souhaitez rendre accessibles à l’application ou à la bibliothèque. Vous spécifiez l’infrastructure cible dans votre fichier projet à l’aide d’un moniker d’infrastructure cible (TFM).

Une application ou une bibliothèque peut cibler une version de .NET Standard. Les versions .NET Standard représentent des ensembles d’API standard sur toutes les implémentations de .NET. Par exemple, une bibliothèque peut cibler .NET Standard 1.6 et accéder aux API qui fonctionnent sur .NET Core et .NET Framework en utilisant la même base de code.

Une application ou une bibliothèque peut également cibler une implémentation spécifique de .NET pour accéder aux API spécifiques à l’implémentation. Par exemple, une application qui cible Xamarin.iOS (par exemple, Xamarin.iOS10) a accès aux wrappers d’API iOS fournis par Xamarin pour iOS 10, ou une application qui cible plateforme Windows universelle (UWP, uap10.0) a accès aux API qui se compilent pour les appareils qui exécutent Windows 10.

Pour certaines infrastructures cibles, telles que .NET Framework, les API sont définies par les assemblys que le framework installe sur un système et peuvent inclure des API d’infrastructure d’application (par exemple, ASP.NET).

Pour les frameworks cibles basés sur un package (par exemple, .NET 5+, .NET Core et .NET Standard), les API sont définies par les packages NuGet inclus dans l’application ou la bibliothèque.

Dernières versions

Le tableau suivant définit les infrastructures cibles les plus courantes, la façon dont elles sont référencées et la version de .NET Standard qu’elles implémentent . Ces versions de framework cible sont les dernières versions stables. Les versions préliminaires ne s’affichent pas. Un moniker d’infrastructure cible (TFM) est un format de jeton standardisé permettant de spécifier l’infrastructure cible d’une application ou d’une bibliothèque .NET.

Version cible de .NET Framework	Latest version stable	Moniker de framework cible (TFM)	Implémenté Version .NET Standard
.NET 7	7	net7.0	2.1
.NET 6	6	net6.0	2.1
.NET 5	5	net5.0	2.1
.NET Standard	2.1	netstandard2.1	N/A
.NET Core	3.1	netcoreapp3.1	2.1
.NET Framework	4.8	net48	2.0

Infrastructures cibles prises en charge

Un framework cible est généralement référencé par un TFM. Le tableau suivant montre les frameworks cibles pris en charge par le KIT de développement logiciel (SDK) .NET et le client NuGet. Les équivalents sont indiqués entre crochets. Par exemple, win81 est un TFM équivalent de netcore451.

Framework cible	TFM
.NET 5+ (et .NET Core)	netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1 net5.0* net6.0* net7.0*
.NET Standard	netstandard1.0 netstandard1.1 netstandard1.2 netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netstandard2.1
.NET Framework	net11 net20 net35 net40 net403 net45 net451 net452 net46 net461 net462 net47 net471 net472 net48
Windows Store	netcore [netcore45] netcore45 [win] [win8] netcore451 [win81]
.NET Micro Framework	netmf
Silverlight	sl4 sl5
Windows Phone	wp [wp7] wp7 wp75 wp8 wp81 wpa81
Plateforme Windows universelle	uap [uap10.0] uap10.0 [win10] [netcore50]

* Les TPM .NET 5 et versions ultérieures incluent certaines variantes spécifiques au système d’exploitation. Pour plus d’informations, consultez la section suivante, tfms spécifiques au système d’exploitation .NET 5+.

TPM spécifiques au système d’exploitation .NET 5+

Les net5.0tfms , net6.0et net7.0 incluent des technologies qui fonctionnent sur différentes plateformes. La spécification d’un TFM spécifique au système d’exploitation rend les API spécifiques à un système d’exploitation disponibles pour votre application, par exemple, les liaisons Windows Forms ou iOS. Les tfms spécifiques au système d’exploitation héritent également de chaque API disponible pour leur TFM de base, par exemple, le net6.0 TFM.

.NET 5 a introduit le TFM spécifique au net5.0-windows système d’exploitation, qui comprend des liaisons spécifiques à Windows pour les API WinForms, WPF et UWP. .NET 6 et versions ultérieures ont des TPM supplémentaires spécifiques au système d’exploitation.

Le tableau suivant montre la compatibilité des TPM .NET 5+.

TFM	Compatible avec
net5.0	net1.. 4 (avec avertissement NU1701) netcoreapp1.. 3.1 (avertissement quand WinForms ou WPF est référencé) netstandard1.. 2.1
net5.0-windows	netcoreapp1.. 3.1 (plus tout le reste hérité de `net5.0`)
net6.0	(version suivante de `net5.0`)
net6.0-android	`xamarin.android` (+tout le reste hérité de `net6.0`)
net6.0-ios	`xamarin.ios` (+tout le reste hérité de `net6.0`)
net6.0-maccatalyst	`xamarin.ios` (+tout le reste hérité de `net6.0`)
net6.0-macos	`xamarin.mac` (+tout le reste hérité de `net6.0`)
net6.0-tvos	`xamarin.tvos` (+tout le reste hérité de `net6.0`)
net6.0-windows	(version suivante de `net5.0-windows`)
net7.0	(version suivante de `net6.0`)
net7.0-android	(version suivante de `net6.0-android`)
net7.0-ios	(version suivante de `net6.0-ios`)
net7.0-maccatalyst	(version suivante de `net6.0-maccatalyst`)
net7.0-macos	(version suivante de `net6.0-macos`)
net7.0-tvos	(version suivante de `net6.0-tvos`)
net7.0-windows	(version suivante de `net6.0-windows`)

Pour rendre votre application portable sur différentes plateformes tout en ayant accès à des API spécifiques au système d’exploitation, vous pouvez cibler plusieurs TPM spécifiques au système d’exploitation et ajouter des protections de plateforme autour des appels d’API spécifiques au système d’exploitation à l’aide #if de directives de préprocesseur.

Cibles suggérées

Utilisez ces instructions pour déterminer le TFM à utiliser dans votre application :

Les applications qui sont portables sur plusieurs plateformes doivent cibler un TFM de base, par exemple . net6.0 Cela inclut la plupart des bibliothèques, mais également ASP.NET Core et Entity Framework.
Les bibliothèques spécifiques à la plateforme doivent cibler des versions spécifiques à la plateforme. Par exemple, les projets WinForms et WPF doivent cibler net6.0-windows.
Les modèles d’application multiplateforme (Xamarin Forms, ASP.NET Core) et les packs de pont (Xamarin Essentials) doivent au moins cibler le TFM de base, par exemple , net6.0mais peuvent également cibler d’autres saveurs spécifiques à la plateforme pour éclairer davantage d’API ou de fonctionnalités.

Version du système d’exploitation dans les tfms

Vous pouvez également spécifier une version de système d’exploitation facultative à la fin d’un TFM spécifique au système d’exploitation, par exemple. net6.0-ios15.0 La version indique les API disponibles pour votre application ou bibliothèque. Il ne contrôle pas la version du système d’exploitation prise en charge par votre application ou votre bibliothèque au moment de l’exécution. Il est utilisé pour sélectionner les assemblys de référence sur antés par votre projet et pour sélectionner des ressources à partir de packages NuGet. Considérez cette version comme la « version de la plateforme » ou la « version de l’API du système d’exploitation » pour la lever de l’ambiguïté de la version du système d’exploitation au moment de l’exécution.

Lorsqu’un TFM spécifique au système d’exploitation ne spécifie pas explicitement la version de la plateforme, il a une valeur implicite qui peut être déduite à partir du TFM de base et du nom de la plateforme. Par exemple, la valeur de plateforme par défaut pour iOS dans .NET 6 est 15.0, ce qui signifie qu’il net6.0-ios s’agit d’un raccourci pour le TFM canonique net6.0-ios15.0 . La version de plateforme implicite d’un TFM de base plus récent peut être plus élevée, par exemple, un futur net8.0-ios TFM pourrait mapper à net8.0-ios16.0. Le formulaire abrégé est destiné à être utilisé uniquement dans les fichiers projet et est développé au format canonique par les cibles MSBuild du KIT de développement logiciel (SDK) .NET avant d’être transmis à d’autres outils, tels que NuGet.

Le Kit de développement logiciel (SDK) .NET est conçu pour prendre en charge les API récemment publiées pour une plateforme individuelle sans nouvelle version du TFM de base. Cela vous permet d’accéder à des fonctionnalités spécifiques à la plateforme sans attendre une version majeure de .NET. Vous pouvez accéder à ces API nouvellement publiées en incrémentant la version de la plateforme dans le TFM. Par exemple, si la plateforme iOS a ajouté des API iOS 15.1 dans une mise à jour du Kit de développement logiciel (SDK) .NET 6.0.x, vous pouvez y accéder à l’aide de TFM net6.0-ios15.1.

Prise en charge des versions antérieures du système d’exploitation

Bien qu’une application ou une bibliothèque spécifique à la plateforme soit compilée sur des API à partir d’une version spécifique de ce système d’exploitation, vous pouvez la rendre compatible avec les versions antérieures du système d’exploitation en ajoutant la SupportedOSPlatformVersion propriété à votre fichier projet. La SupportedOSPlatformVersion propriété indique la version minimale du système d’exploitation requise pour exécuter votre application ou bibliothèque. Si vous ne spécifiez pas explicitement cette version minimale du système d’exploitation au moment de l’exécution dans le projet, elle utilise par défaut la version de la plateforme à partir du TFM.

Pour que votre application s’exécute correctement sur une version antérieure du système d’exploitation, elle ne peut pas appeler des API qui n’existent pas sur cette version du système d’exploitation. Toutefois, vous pouvez ajouter des protections autour des appels à des API plus récentes afin qu’elles soient appelées uniquement lors de l’exécution sur une version du système d’exploitation qui les prend en charge. Ce modèle vous permet de concevoir votre application ou bibliothèque pour prendre en charge l’exécution sur des versions antérieures du système d’exploitation tout en tirant parti des fonctionnalités du système d’exploitation plus récentes lors de l’exécution sur des versions plus récentes du système d’exploitation.

La SupportedOSPlatformVersion valeur (explicite ou par défaut) est utilisée par l’analyseur de compatibilité de la plateforme, qui détecte et avertit des appels non surveillés vers des API plus récentes. Il est gravé dans l’assembly compilé du projet en tant qu’attribut d’assembly UnsupportedOSPlatformAttribute , afin que l’analyseur de compatibilité de la plateforme puisse détecter les appels non surveillés aux API de cet assembly à partir de projets avec une valeur inférieure SupportedOSPlatformVersion . Sur certaines plateformes, la valeur affecte l’empaquetage SupportedOSPlatformVersion et les processus de génération d’applications spécifiques à la plateforme, qui sont décrits dans la documentation de ces plateformes.

Voici un exemple d’extrait d’un fichier projet qui utilise les TargetFramework propriétés msBuild et SupportedOSPlatformVersion pour spécifier que l’application ou la bibliothèque a accès aux API iOS 15.0, mais prend en charge l’exécution sur iOS 13.0 et versions ultérieures :

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0-ios15.0</TargetFramework>
    <SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
  </PropertyGroup>

  ...

</Project>

Comment spécifier une infrastructure cible

Les frameworks cibles sont spécifiés dans un fichier projet. Lorsqu’une infrastructure cible unique est spécifiée, utilisez l’élément TargetFramework. Le fichier projet d’application console suivant montre comment cibler .NET 6 :

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

</Project>

Quand vous spécifiez plusieurs frameworks cibles, vous pouvez référencer conditionnellement des assemblys pour chaque framework cible. Dans votre code, vous pouvez effectuer une compilation conditionnelle par rapport à ces assemblys en utilisant des symboles de préprocesseur avec la structure logique if-then-else.

Le projet de bibliothèque suivant cible les API de .NET Standard (netstandard1.4) et .NET Framework (net40 et net45). Utilisez l’élément TargetFrameworks au pluriel avec plusieurs frameworks cibles. Les Condition attributs incluent des packages spécifiques à l’implémentation lorsque la bibliothèque est compilée pour les deux TPM .NET Framework :

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>netstandard1.4;net40;net45</TargetFrameworks>
  </PropertyGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.0 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net40' ">
    <Reference Include="System.Net" />
  </ItemGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.5 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net45' ">
    <Reference Include="System.Net.Http" />
    <Reference Include="System.Threading.Tasks" />
  </ItemGroup>

</Project>

Au sein de votre bibliothèque ou application, vous écrivez du code conditionnel à l’aide de directives de préprocesseur à compiler pour chaque infrastructure cible :

public class MyClass
{
    static void Main()
    {
#if NET40
        Console.WriteLine("Target framework: .NET Framework 4.0");
#elif NET45
        Console.WriteLine("Target framework: .NET Framework 4.5");
#else
        Console.WriteLine("Target framework: .NET Standard 1.4");
#endif
    }
}

Le système de génération est conscient des symboles de préprocesseur représentant les frameworks cibles indiqués dans le tableau Versions de l’infrastructure cible prises en charge lorsque vous utilisez des projets de style SDK. Lorsque vous utilisez un symbole qui représente un TFM .NET Standard, .NET Core ou .NET 5+, remplacez les points et les traits d’union par un trait de soulignement et remplacez les lettres minuscules en majuscules (par exemple, le symbole pour netstandard1.4 est NETSTANDARD1_4). Vous pouvez désactiver la génération de ces symboles via la DisableImplicitFrameworkDefines propriété . Pour plus d’informations sur cette propriété, consultez DisableImplicitFrameworkDefines.

La liste complète des symboles de préprocesseur pour les frameworks cibles .NET est la suivante :

Versions cibles de .NET Framework	symboles	Symboles supplémentaires disponibles dans le Kit de développement logiciel (SDK) .NET 5+
.NET Framework	`NETFRAMEWORK`, `NET48`, `NET472`, `NET471`, `NET47`, `NET462`, `NET461`, `NET46`, `NET452`, `NET451`, `NET45`, `NET40`, `NET35`, `NET20`	`NET48_OR_GREATER`, `NET472_OR_GREATER`, `NET471_OR_GREATER`, `NET47_OR_GREATER`, `NET462_OR_GREATER`, `NET461_OR_GREATER`, `NET46_OR_GREATER`, `NET452_OR_GREATER`, `NET451_OR_GREATER`, `NET45_OR_GREATER`, `NET40_OR_GREATER`, `NET35_OR_GREATER`, `NET20_OR_GREATER`
.NET Standard	`NETSTANDARD`, `NETSTANDARD2_1`, `NETSTANDARD2_0`, `NETSTANDARD1_6`, `NETSTANDARD1_5`, `NETSTANDARD1_4`, `NETSTANDARD1_3`, `NETSTANDARD1_2`, `NETSTANDARD1_1`, `NETSTANDARD1_0`	`NETSTANDARD2_1_OR_GREATER`, `NETSTANDARD2_0_OR_GREATER`, `NETSTANDARD1_6_OR_GREATER`, `NETSTANDARD1_5_OR_GREATER`, `NETSTANDARD1_4_OR_GREATER`, `NETSTANDARD1_3_OR_GREATER`, `NETSTANDARD1_2_OR_GREATER`, `NETSTANDARD1_1_OR_GREATER`, `NETSTANDARD1_0_OR_GREATER`
.NET 5+ (et .NET Core)	`NET`, `NET7_0`, `NET6_0`, `NET5_0`, `NETCOREAPP`, `NETCOREAPP3_1`, `NETCOREAPP3_0`, `NETCOREAPP2_2`, `NETCOREAPP2_1`, `NETCOREAPP2_0`, `NETCOREAPP1_1`, `NETCOREAPP1_0`	`NET7_0_OR_GREATER`, `NET6_0_OR_GREATER`, `NET5_0_OR_GREATER`, `NETCOREAPP3_1_OR_GREATER`, `NETCOREAPP3_0_OR_GREATER`, `NETCOREAPP2_2_OR_GREATER`, `NETCOREAPP2_1_OR_GREATER`, `NETCOREAPP2_0_OR_GREATER`, `NETCOREAPP1_1_OR_GREATER`, `NETCOREAPP1_0_OR_GREATER`

Notes

Les symboles sans version sont définis quelle que soit la version que vous ciblez.
Les symboles spécifiques à la version sont définis uniquement pour la version que vous ciblez.
Les <framework>_OR_GREATER symboles sont définis pour la version que vous ciblez et toutes les versions antérieures. Par exemple, si vous ciblez .NET Framework 2.0, les symboles suivants sont définis : NET20, NET20_OR_GREATER, NET11_OR_GREATERet NET10_OR_GREATER.
Ceux-ci sont différents des monikers d’infrastructure cible (TFM) utilisés par la propriété MSBuild TargetFramework et NuGet.

Frameworks cibles dépréciés

Les frameworks cibles suivants sont dépréciés. Les packages qui ciblent ces infrastructures cibles doivent migrer vers les remplacements indiqués.

TFM déprécié	Remplacement
aspnet50 aspnetcore50 dnxcore50 dnx dnx45 dnx451 dnx452	netcoreapp
dotnet dotnet50 dotnet51 dotnet52 dotnet53 dotnet54 dotnet55 dotnet56	netstandard
netcore50	uap10.0
win	netcore45
win8	netcore45
win81	netcore451
win10	uap10.0
winrt	netcore45

Voir aussi

Noms de framework cibles dans .NET 5
Appeler des API Windows Runtime dans les applications de bureau
Développer des bibliothèques avec des outils multiplateformes
.NET Standard
Gestion des versions de .NET Core
NuGet Tools GitHub Repository (Dépôt GitHub des outils NuGet)
Framework Profiles in .NET (Profils de framework dans .NET)
Analyseur de compatibilité de plateforme