Infrastructures cibles dans les projets de style SDK

  • Article
  • 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 de framework 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 s’exécutent Windows 10.

Pour certains frameworks cibles, tels 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 des packages (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 frameworks cibles les plus courants, la façon dont ils sont référencés et la version de .NET Standard qu’ils implémentent. Ces versions de framework cible sont les dernières versions stables. Les versions préliminaires ne sont pas affichées. Un moniker d’infrastructure cible (TFM) est un format de jeton standardisé permettant de spécifier l’infrastructure cible d’une bibliothèque ou d’une application .NET.

Version cible de .NET Framework Plus récent
version stable		 Moniker du 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

Frameworks cibles pris en charge

Un framework cible est généralement référencé par un TFM. Le tableau suivant présente les frameworks cibles pris en charge par le 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 modules tfms .NET 5 et ultérieur incluent certaines variantes spécifiques au système d’exploitation. Pour plus d’informations, consultez la section suivante, TVM 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, des liaisons Windows Forms ou iOS. Les TFM 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 inclut des liaisons spécifiques à Windows pour les API WinForms, WPF et UWP. .NET 6 et versions ultérieures ont des modules tfms supplémentaires spécifiques au système d’exploitation, par exemple . net6.0-ios

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 ultérieure 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 ultérieure de net5.0-windows)
net7.0 (version ultérieure de net6.0)
net7.0-android (version ultérieure de net6.0-android)
net7.0-ios (version ultérieure de net6.0-ios)
net7.0-maccatalyst (version ultérieure de net6.0-maccatalyst)
net7.0-macos (version ultérieure de net6.0-macos)
net7.0-tvos (version ultérieure de net6.0-tvos)
net7.0-windows (version ultérieure 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. Pour obtenir la liste des symboles disponibles, consultez Symboles de préprocesseur.

Cibles suggérées

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

  • Les applications 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 des versions spécifiques à la plateforme supplémentaires pour éclairer davantage d’API ou de fonctionnalités.

Version du système d’exploitation dans les machines virtuelles tfms

Vous pouvez également spécifier une version facultative du système d’exploitation à 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 que votre application ou bibliothèque prend en charge au moment de l’exécution. Il est utilisé pour sélectionner les assemblys de référence sur proviennent de votre projet et pour sélectionner des ressources à partir de packages NuGet. Considérez cette version comme la « version de plateforme » ou la « version de l’API du système d’exploitation » pour lever 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 que net6.0-ios est abrégé 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 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 nouvellement 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 SDK .NET 6.0.x, vous pouvez y accéder à l’aide du 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 les API 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 d’exécution dans le projet, elle utilise par défaut la version de plateforme 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 gardes autour des appels aux API plus récentes afin qu’ils soient appelés 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 de 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 les 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 les SupportedOSPlatformVersion processus d’empaquetage et de génération d’applications spécifiques à la plateforme, qui sont abordés dans la documentation de ces plateformes.

Voici un exemple d’extrait d’un fichier projet qui utilise les TargetFramework propriétés et SupportedOSPlatformVersion MSBuild 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 seule infrastructure cible 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 sur ces assemblys à l’aide de symboles de préprocesseur avec une 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 modules tfms .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>

Dans 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
    }
}

Symboles de préprocesseur

Le système de génération est conscient des symboles de préprocesseur représentant les frameworks cibles affichés dans le tableau Versions du framework cible prises en charge lorsque vous utilisez des projets de style SDK. Pour convertir un TFM .NET Standard, .NET Core ou .NET 5+ en symbole de préprocesseur, remplacez les points et les traits d’union par un trait de soulignement et remplacez les lettres minuscules en majuscules (par exemple, le symbole de 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
(disponible dans les kits SDK .NET 5+ )		 Symboles de plateforme (disponibles uniquement)
lorsque vous spécifiez un TFM spécifique au système d’exploitation)
.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 ANDROID, IOS, MACCATALYST, MACOS, TVOS, WINDOWS,
[OS][version] (par exemple IOS15_1),
[OS][version]_OR_GREATER (par exemple IOS15_1_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