Cél-keretrendszerek SDK-stílusú projektekben

  • Cikk
  • 8 perc alatt elolvasható

Amikor egy alkalmazás vagy tár keretrendszerét célozza meg, meg kell adnia azokat az API-kat, amelyeket elérhetővé szeretne tenni az alkalmazás vagy a tár számára. A cél keretrendszert a projektfájlban egy cél-keretrendszer moniker (TFM) használatával adhatja meg.

Egy alkalmazás vagy tár a .NET Standard egy verzióját célozhatja meg. A .NET Standard verziók az API-k szabványos készleteit képviselik az összes .NET-implementációban. Egy kódtár például megcélzhatja a .NET Standard 1.6-ot, és hozzáférhet azokhoz az API-khoz, amelyek a .NET Core-ban működnek, és .NET-keretrendszer ugyanazt a kódbázist használják.

Az alkalmazások vagy tárak egy adott .NET-implementációt is megcélozhatnak, hogy hozzáférjenek az implementációspecifikus API-khoz. Például egy Xamarin.iOS-t (például Xamarin.iOS10) megcélzó alkalmazás hozzáfér az iOS 10 Xamarin által biztosított iOS API-burkolóihoz, vagy egy Univerzális Windows-platform (UWP, uap10.0) célokat szolgáló alkalmazás hozzáféréssel rendelkezik az Windows 10 futtató eszközökhöz lefordított API-khoz.

Egyes cél-keretrendszerek, például a .NET-keretrendszer esetében az API-kat a keretrendszer által a rendszeren telepített szerelvények határozzák meg, és alkalmazás-keretrendszer API-kat (például ASP.NET) is tartalmazhatnak.

Csomagalapú cél-keretrendszerek (például .NET 5+, .NET Core és .NET Standard) esetén az API-kat az alkalmazás vagy a tár nuGet-csomagjai határozzák meg.

Legújabb verziók

Az alábbi táblázat a leggyakoribb cél-keretrendszereket, azok hivatkozási módját és a .NET Standard implementálásának módját határozza meg. Ezek a cél-keretrendszerverziók a legújabb stabil verziók. Az előzetes verziók nem jelennek meg. A cél-keretrendszer-moniker (TFM) egy szabványos jogkivonat-formátum egy .NET-alkalmazás vagy -tár cél keretrendszerének megadásához.

Cél-keretrendszer Legutóbbi
stabil verzió		 Cél-keretrendszer moniker (TFM) Végre
.NET Standard verzió
.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-keretrendszer 4.8 net48 2.0

Támogatott cél-keretrendszerek

A cél-keretrendszerre általában egy TFM hivatkozik. Az alábbi táblázat a .NET SDK és a NuGet-ügyfél által támogatott cél-keretrendszereket mutatja be. A megfelelők szögletes zárójelben jelennek meg. Például win81 egy egyenértékű TFM a következőhöz netcore451: .

Cél-keretrendszer TFM
.NET 5+ (és .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-keretrendszer net11
net20
net35
net40
net403
net45
net451
net452
net46
net461
net462
net47
net471
net472
net48
Windows Áruház netcore [netcore45]
netcore45 [win] [win8]
netcore451 [win81]
.NET Micro Framework netmf
Silverlight sl4
sl5
Windows Phone wp [wp7]
wp7
wp75
wp8
wp81
wpa81
Univerzális Windows-platform uap [uap10.0]
uap10.0 [win10] [netcore50]

* A .NET 5-ös és újabb TFM-jei operációs rendszerspecifikus változatokat tartalmaznak. További információt a következő, .NET 5+ operációsrendszer-specifikus TFM-ekről szóló szakaszban talál.

.NET 5+ operációsrendszer-specifikus TFM-ek

A net5.0, net6.0és net7.0 TFM különböző platformokon működő technológiákat tartalmaznak. Egy operációsrendszer-specifikus TFM megadásával az alkalmazás számára elérhetővé válnak az adott operációs rendszerre jellemző API-k, például Windows Forms vagy iOS-kötések. Az operációsrendszer-specifikus TFM-ek az alapszintű TFM-hez elérhető összes API-t is öröklik, például a net6.0 TFM-et.

A .NET 5 bevezette az net5.0-windows operációsrendszer-specifikus TFM-et, amely Windows-specifikus kötéseket tartalmaz a WinForms, a WPF és az UWP API-khoz. A .NET 6-os és újabb verziói további operációsrendszer-specifikus TFM-ekkel rendelkeznek, például net6.0-ios: .

Az alábbi táblázat a .NET 5+ TFM-ekkel való kompatibilitást mutatja be.

TFM Kompatibilis a
net5.0 net1.. 4 (NU1701 figyelmeztetéssel)
netcoreapp1.. 3.1 (figyelmeztetés WinForms vagy WPF használata esetén)
netstandard1.. 2.1
net5.0-windows netcoreapp1.. 3.1 (plusz minden más örökölt net5.0)
net6.0 (a következő verziója net5.0)
net6.0-android xamarin.android (+minden más öröklődik innen net6.0: )
net6.0-ios xamarin.ios (+minden más öröklődik innen net6.0: )
net6.0-maccatalyst xamarin.ios (+minden más öröklődik innen net6.0: )
net6.0-macos xamarin.mac (+minden más öröklődik innen net6.0: )
net6.0-tvos xamarin.tvos (+minden más öröklődik innen net6.0: )
net6.0-windows (a következő verziója net5.0-windows)
net7.0 (a következő verziója net6.0)
net7.0-android (a következő verziója net6.0-android)
net7.0-ios (a következő verziója net6.0-ios)
net7.0-maccatalyst (a következő verziója net6.0-maccatalyst)
net7.0-macos (a következő verziója net6.0-macos)
net7.0-tvos (a következő verziója net6.0-tvos)
net7.0-windows (a következő verziója net6.0-windows)

Ha azt szeretné, hogy az alkalmazás hordozható legyen a különböző platformokon, de továbbra is hozzáférhessen az operációsrendszer-specifikus API-khoz, több operációsrendszer-specifikus TFM-et célozhat meg, és platformőröket adhat hozzá az operációs rendszerspecifikus API-hívásokhoz az előfeldolgozó irányelvek használatával #if . Az elérhető szimbólumok listáját az Előfeldolgozó szimbólumok című témakörben találja.

Javasolt célok

Ezekkel az irányelvekkel határozhatja meg, hogy melyik TFM-et használja az alkalmazásban:

  • A több platformra hordozható alkalmazásoknak egy alapszintű TFM-et kell céloznia, például net6.0: . Ebbe beletartozik a legtöbb kódtár, de a ASP.NET Core és az Entity Framework is.

  • A platformspecifikus kódtáraknak platformspecifikus ízeket kell céloznia. A WinForms- és WPF-projekteknek például a célnak kell lennie net6.0-windows.

  • A platformfüggetlen alkalmazásmodelleknek (Xamarin Forms, ASP.NET Core) és hídcsomagoknak (Xamarin Essentials) legalább az alap TFM-et kell céloznia, net6.0például , de további platformspecifikus ízeket is megcélozhatnak, hogy több API-t vagy funkciót világítson meg.

Operációs rendszer verziója TFM-ekben

Megadhat egy választható operációsrendszer-verziót is egy operációsrendszer-specifikus TFM végén, például net6.0-ios15.0: . A verzió azt jelzi, hogy mely API-k érhetők el az alkalmazás vagy a tár számára. Nem szabályozza az alkalmazás vagy a kódtár által futásidőben támogatott operációsrendszer-verziót. A projekt által lefordított referenciaszerelvények kiválasztására, valamint a NuGet-csomagokból származó objektumok kiválasztására szolgál. Ezt a verziót "platformverziónak" vagy "OS API-verziónak" tekintheti, hogy egyértelműsítse azt a futásidejű operációs rendszer verziójától.

Ha egy operációsrendszer-specifikus TFM nem adja meg explicit módon a platformverziót, akkor egy vélelmezett értékkel rendelkezik, amely az alap TFM-ből és a platform nevéből következtethető ki. A .NET 6-ban például az iOS alapértelmezett platformértéke a 15.0, ami azt jelenti, hogy net6.0-ios ez a canonical net6.0-ios15.0 TFM rövidített értéke. Az újabb alapszintű TFM vélelmezett platformverziója magasabb lehet, például egy jövőbeli net8.0-ios TFM leképezhető a következőre net8.0-ios16.0: . A rövidített űrlap csak projektfájlokban használható, és a .NET SDK MSBuild-példányai kibővítik a canonikus űrlapra, mielőtt más eszközöknek, például a NuGetnek átadnák.

A .NET SDK úgy lett kialakítva, hogy képes legyen támogatni az újonnan kiadott API-kat egy egyéni platformhoz az alap TFM új verziója nélkül. Ez lehetővé teszi a platformspecifikus funkciók elérését anélkül, hogy megvárja a .NET egyik fő kiadását. Ezekhez az újonnan kiadott API-khoz a platformverzió növelésével férhet hozzá a TFM-ben. Ha például az iOS platform iOS 15.1 API-kat adott hozzá egy .NET 6.0.x SDK-frissítéshez, a TFM net6.0-ios15.1használatával érheti el őket.

Régebbi operációsrendszer-verziók támogatása

Bár egy platformspecifikus alkalmazást vagy tárat az operációs rendszer egy adott verziójából származó API-k alapján fordítunk le, a tulajdonság projektfájlhoz való hozzáadásával kompatibilissé teheti a SupportedOSPlatformVersion korábbi operációsrendszer-verziókkal. A SupportedOSPlatformVersion tulajdonság az alkalmazás vagy tár futtatásához szükséges minimális operációsrendszer-verziót jelzi. Ha nem explicit módon adja meg ezt a minimális futásidejű operációsrendszer-verziót a projektben, az alapértelmezés szerint a TFM platformverziójára érvényes.

Ahhoz, hogy az alkalmazás megfelelően fusson egy régebbi operációsrendszer-verzión, nem tud meghívni olyan API-kat, amelyek nem léteznek az operációs rendszer azon verzióján. Az újabb API-khoz azonban hozzáadhat őröket a hívások körül, így azok csak akkor lesznek meghívva, ha az operációs rendszer olyan verzióján futnak, amely támogatja őket. Ezzel a mintával úgy tervezheti meg az alkalmazást vagy a tárat, hogy támogassa a régebbi operációsrendszer-verziókon való futtatásokat, miközben kihasználja az újabb operációsrendszer-funkciók előnyeit az újabb operációs rendszereken való futtatáskor.

A SupportedOSPlatformVersionplatformkompatibilitás-elemző (akár explicit, akár alapértelmezett) értéket használja, amely észleli és figyelmezteti az újabb API-k nem őrzött hívásait. A rendszer a projekt lefordított szerelvényébe szerelvényattribútumként UnsupportedOSPlatformAttribute van beégve, így a platformkompatibilitás-elemző képes észlelni a szerelvény API-jainak nem őrzött hívásait alacsonyabb SupportedOSPlatformVersion értékű projektekből. Egyes platformokon ez az érték hatással van a SupportedOSPlatformVersion platformspecifikus alkalmazáscsomagolási és -buildelési folyamatokra, amelyekről az adott platformok dokumentációja foglalkozik.

Íme egy példa egy projektfájlra, amely a és SupportedOSPlatformVersion az TargetFramework MSBuild tulajdonsággal határozza meg, hogy az alkalmazás vagy a kódtár hozzáfér-e az iOS 15.0 API-khoz, de támogatja az iOS 13.0-s és újabb verzióin való futtatásokat:

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

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

  ...

</Project>

Cél-keretrendszer megadása

A cél-keretrendszerek egy projektfájlban vannak megadva. Ha egyetlen célkeret van megadva, használja a TargetFramework elemet. A konzolalkalmazás következő projektfájlja bemutatja, hogyan célozhatja meg a .NET 6-ot:

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

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

</Project>

Ha több cél-keretrendszert ad meg, feltételesen hivatkozhat szerelvényekre az egyes cél-keretrendszerekhez. A kódban feltételesen fordíthatja le ezeket a szerelvényeket előfeldolgozó szimbólumok és if-then-else logika használatával.

Az alábbi kódtárprojekt a .NET Standard (netstandard1.4) és .NET-keretrendszer (net40 és net45) API-jait célozza meg. Használja a többes számú TargetFrameworks elemet több cél-keretrendszerrel. Az Condition attribútumok implementációspecifikus csomagokat tartalmaznak, amikor a kódtár a két .NET-keretrendszer TFM-hez van lefordítva:

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

A kódtárban vagy az alkalmazásban feltételes kódot írhat előfeldolgozási irányelvek használatával az egyes cél-keretrendszerek fordításához:

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

Előfeldolgozó szimbólumok

A buildrendszer tisztában van az SDK-stílusú projektek használata esetén a Támogatott célrendszerverziók táblázatban látható célkereteket jelképező előfeldolgozó szimbólumokkal. Ha a .NET Standard, a .NET Core vagy a .NET 5+ TFM-et előfeldolgozó szimbólummá szeretné konvertálni, cserélje le a pontokat és kötőjeleket aláhúzásjelre, és módosítsa a kisbetűket nagybetűsre (például a szimbólumanetstandard1.4).NETSTANDARD1_4

Ezeknek a szimbólumoknak a létrehozását a DisableImplicitFrameworkDefines tulajdonságon keresztül tilthatja le. További információ erről a tulajdonságról: DisableImplicitFrameworkDefines.

A .NET-célkeretekhez tartozó előfeldolgozó szimbólumok teljes listája a következő:

Cél-keretrendszerek Szimbólumok További szimbólumok
(.NET 5+ SDK-kban érhető el)		 Platformszimbólumok (csak
operációsrendszer-specifikus TFM megadásakor)
.NET-keretrendszer 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+ (és .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] (például IOS15_1),
[OS][version]_OR_GREATER (például IOS15_1_OR_GREATER)

Megjegyzés

  • A verzió nélküli szimbólumok a megcélzott verziótól függetlenül vannak definiálva.
  • A verzióspecifikus szimbólumok csak a megcélzott verzióhoz vannak definiálva.
  • A <framework>_OR_GREATER szimbólumok a megcélzott verzióhoz és az összes korábbi verzióhoz vannak definiálva. Ha például a 2.0-s .NET-keretrendszer céloz meg, a következő szimbólumok vannak definiálva: NET20, NET20_OR_GREATER, NET11_OR_GREATERés NET10_OR_GREATER.
  • Ezek eltérnek az MSBuild TargetFramework tulajdonság és aNuGet által használt célkeret-monikerektől (TFM-ek).

Elavult cél-keretrendszerek

A következő cél-keretrendszerek elavultak. Az ezeket a cél-keretrendszereket célzó csomagokat át kell telepíteni a jelzett cserékre.

Elavult TFM Csere
aspnet50
aspnetcore50
dnxcore50
dnx
dnx45
dnx451
dnx452		 netcoreapp
dotnet
dotnet50
dotnet51
dotnet52
dotnet53
dotnet54
dotnet55
dotnet56		 netstandard
netcore50 uap10.0
Nyer netcore45
win8 netcore45
win81 netcore451
win10 uap10.0
winrt netcore45

Lásd még