Cél-keretrendszerek SDK-stílusú projektekben
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.0
pé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.1
haszná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 SupportedOSPlatformVersion
platformkompatibilitá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
ésNET10_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 |