Platformy docelowe w projektach w stylu zestawu SDK

  • Artykuł
  • Czas czytania: 9 min

W przypadku określania platformy docelowej w aplikacji lub bibliotece określasz zestaw interfejsów API, które mają być dostępne dla aplikacji lub biblioteki. Należy określić platformę docelową w pliku projektu przy użyciu nazwy docelowej platformy (TFM).

Aplikacja lub biblioteka może być wersją docelową platformy .NET Standard. Wersje platformy .NET Standard reprezentują standardowe zestawy interfejsów API we wszystkich implementacjach platformy .NET. Na przykład biblioteka może być docelowa dla platformy .NET Standard 1.6 i uzyskać dostęp do interfejsów API, które działają na platformie .NET Core i .NET Framework przy użyciu tej samej bazy kodu.

Aplikacja lub biblioteka może również kierować do określonej implementacji platformy .NET, aby uzyskać dostęp do interfejsów API specyficznych dla implementacji. Na przykład aplikacja przeznaczona dla platformy Xamarin.iOS (na przykład Xamarin.iOS10) ma dostęp do otoek interfejsów API systemu iOS udostępnianych przez platformę Xamarin dla systemu iOS 10 lub aplikacji przeznaczonej dla platforma uniwersalna systemu Windows (UWP, uap10.0) ma dostęp do interfejsów API kompilowanych dla urządzeń z systemem Windows 10.

W przypadku niektórych platform docelowych, takich jak .NET Framework, interfejsy API są definiowane przez zestawy instalowane przez platformę w systemie i mogą obejmować interfejsy API platformy aplikacji (na przykład ASP.NET).

W przypadku platform docelowych opartych na pakietach (na przykład .NET 5+, .NET Core i .NET Standard) interfejsy API są definiowane przez pakiety NuGet zawarte w aplikacji lub bibliotece.

Najnowsze wersje

W poniższej tabeli zdefiniowano najbardziej typowe platformy docelowe, sposób ich odwoływanie się oraz wersję implementowanego środowiska .NET Standard . Te wersje platformy docelowej to najnowsze stabilne wersje. Wersje wstępne nie są wyświetlane. Moniker platformy docelowej (TFM) to standardowy format tokenu do określania platformy docelowej aplikacji lub biblioteki platformy .NET.

Platforma docelowa Najnowsza
stabilna wersja		 Moniker platformy docelowej (TFM) Zaimplementowana
Wersja platformy .NET Standard
.NET 6 6 net6.0 2.1
.NET 5 5 net5.0 2.1
.NET Standard 2.1 netstandard2.1 Nie dotyczy
.NET Core 3,1 netcoreapp3.1 2.1
.NET Framework 4.8 net48 2.0

Obsługiwane platformy docelowe

Platforma docelowa zwykle odwołuje się do programu TFM. W poniższej tabeli przedstawiono platformy docelowe obsługiwane przez zestaw .NET SDK i klienta NuGet. Odpowiedniki są wyświetlane w nawiasach kwadratowych. Na przykład win81 jest odpowiednikiem serwera TFM do netcore451.

Struktura docelowa TFM
.NET 5+ (i .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
Platforma uniwersalna systemu Windows uap [uap10.0]
uap10.0 [win10] [netcore50]

* .NET 5 i nowsze wersje TFM zawierają pewne odmiany specyficzne dla systemu operacyjnego. Aby uzyskać więcej informacji, zobacz następującą sekcję: .NET 5+ specyficzne dla systemu operacyjnego TFMs.

Programy TFM specyficzne dla systemu operacyjnego .NET 5+

Systemy net5.0, net6.0i net7.0 TFM obejmują technologie, które działają na różnych platformach. Określenie specyficznego dla systemu operacyjnego programu TFM powoduje, że interfejsy API specyficzne dla systemu operacyjnego są dostępne dla aplikacji, na przykład Windows Forms lub powiązania systemu iOS. Dyski TFM specyficzne dla systemu operacyjnego dziedziczą również każdy interfejs API dostępny dla podstawowego net6.0 serwera TFM, na przykład tfM.

Platforma .NET 5 wprowadziła net5.0-windows specyficzny dla systemu operacyjnego program TFM, który obejmuje powiązania specyficzne dla systemu Windows dla interfejsów API WinForms, WPF i UWP. Platforma .NET 6 wprowadza dalsze programy TFM specyficzne dla systemu operacyjnego.

W poniższej tabeli przedstawiono zgodność z programem .NET 5+ TFMs.

TFM Zgodne z
net5.0 net1.. 4 (z ostrzeżeniem NU1701)
netcoreapp1.. 3.1 (ostrzeżenie, gdy odwołuje się system WinForms lub WPF)
netstandard1.. 2.1
net5.0-windows netcoreapp1.. 3.1 (plus wszystko inne dziedziczone z net5.0)
net6.0 (kolejna wersja programu net5.0)
net6.0-android xamarin.android (+wszystko inne dziedziczone z net6.0)
net6.0-ios xamarin.ios (+wszystko inne dziedziczone z net6.0)
net6.0-maccatalyst xamarin.ios (+wszystko inne dziedziczone z net6.0)
net6.0-macos xamarin.mac (+wszystko inne dziedziczone z net6.0)
net6.0-tvos xamarin.tvos (+wszystko inne dziedziczone z net6.0)
net6.0-windows (kolejna wersja programu net5.0-windows)
net7.0 (kolejna wersja programu net6.0)
net7.0-android (kolejna wersja programu net6.0-android)
net7.0-ios (kolejna wersja programu net6.0-ios)
net7.0-maccatalyst (kolejna wersja programu net6.0-maccatalyst)
net7.0-macos (kolejna wersja programu net6.0-macos)
net7.0-tvos (kolejna wersja programu net6.0-tvos)
net7.0-windows (kolejna wersja programu net6.0-windows)

Aby aplikacja mogła być przenośna na różnych platformach, ale nadal ma dostęp do interfejsów API specyficznych dla systemu operacyjnego, możesz kierować wiele specyficznych dla systemu operacyjnego serwerów TFM i dodawać funkcje ochrony platformy wokół wywołań interfejsu API specyficznych dla systemu operacyjnego przy użyciu #if dyrektyw preprocesora.

Sugerowane elementy docelowe

Skorzystaj z poniższych wskazówek, aby określić, który program TFM ma być używany w aplikacji:

  • Aplikacje przenośne z wieloma platformami powinny być przeznaczone dla podstawowego serwera TFM, na przykład net6.0. Obejmuje to większość bibliotek, ale także ASP.NET Core i Entity Framework.

  • Biblioteki specyficzne dla platformy powinny dotyczyć odmian specyficznych dla platformy. Na przykład projekty WinForms i WPF powinny być przeznaczone dla net6.0-windowsprogramu .

  • Modele aplikacji międzyplatformowych (Xamarin Forms, ASP.NET Core) i pakiety mostkowe (Xamarin Essentials) powinny być przynajmniej przeznaczone dla podstawowego serwera TFM, net6.0ale mogą również dotyczyć dodatkowych smaków specyficznych dla platformy, aby rozjaśnić więcej interfejsów API lub funkcji.

Wersja systemu operacyjnego w programie TFMs

Możesz również określić opcjonalną wersję systemu operacyjnego na końcu serwera TFM specyficznego dla systemu operacyjnego, na przykład net6.0-ios15.0. Wersja wskazuje, które interfejsy API są dostępne dla aplikacji lub biblioteki. Nie kontroluje wersji systemu operacyjnego obsługiwanej przez aplikację lub bibliotekę w czasie wykonywania. Służy do wybierania zestawów referencyjnych kompilowanych przez projekt i wybierania zasobów z pakietów NuGet. Należy traktować tę wersję jako "wersję platformy" lub "wersję interfejsu API systemu operacyjnego", aby uściślić ją z wersji systemu operacyjnego w czasie wykonywania.

Jeśli specyficzny dla systemu operacyjnego program TFM nie określa jawnie wersji platformy, ma dorozumianą wartość, która może zostać wywnioskowana z podstawowej nazwy serwera TFM i platformy. Na przykład domyślna wartość platformy dla systemu iOS na platformie .NET 6 to 15.0, co oznacza, że net6.0-ios jest to skrót dla kanonicznego net6.0-ios15.0 serwera TFM. Implikowane wersje platformy dla nowszego podstawowego programu TFM mogą być wyższe, na przykład przyszły net8.0-ios program TFM może mapować na net8.0-ios16.0. Formularz skrócony jest przeznaczony tylko do użycia w plikach projektu i jest rozszerzany do formularza kanonicznego przez obiekty docelowe MSBuild zestawu SDK platformy .NET przed przekazaniem do innych narzędzi, takich jak NuGet.

Zestaw SDK platformy .NET jest przeznaczony do obsługi nowo wydanych interfejsów API dla pojedynczej platformy bez nowej wersji podstawowego programu TFM. Umożliwia to dostęp do funkcji specyficznych dla platformy bez oczekiwania na główną wersję platformy .NET. Dostęp do tych nowo wydanych interfejsów API można uzyskać, zwiększając wersję platformy w programie TFM. Jeśli na przykład platforma systemu iOS dodała interfejsy API systemu iOS 15.1 w aktualizacji zestawu SDK platformy .NET 6.0.x, możesz uzyskać do nich dostęp przy użyciu programu TFM net6.0-ios15.1.

Obsługa starszych wersji systemu operacyjnego

Mimo że aplikacja lub biblioteka specyficzna dla platformy jest kompilowana względem interfejsów API z określonej wersji tego systemu operacyjnego, można ją zapewnić zgodność z wcześniejszymi wersjami systemu operacyjnego, dodając SupportedOSPlatformVersion właściwość do pliku projektu. Właściwość SupportedOSPlatformVersion wskazuje minimalną wersję systemu operacyjnego wymaganą do uruchomienia aplikacji lub biblioteki. Jeśli nie określisz jawnie tej minimalnej wersji systemu operacyjnego w czasie wykonywania w projekcie, domyślnie jest to wersja platformy z programu TFM.

Aby aplikacja była poprawnie uruchamiana w starszej wersji systemu operacyjnego, nie może wywoływać interfejsów API, które nie istnieją w tej wersji systemu operacyjnego. Można jednak dodać osłony wokół wywołań do nowszych interfejsów API, aby były wywoływane tylko w przypadku uruchamiania w wersji systemu operacyjnego, która je obsługuje. Ten wzorzec umożliwia zaprojektowanie aplikacji lub biblioteki do obsługi uruchamiania w starszych wersjach systemu operacyjnego przy jednoczesnym wykorzystaniu nowszych funkcji systemu operacyjnego podczas uruchamiania w nowszych wersjach systemu operacyjnego.

Wartość SupportedOSPlatformVersion (czy jawna czy domyślna) jest używana przez analizator zgodności platformy, który wykrywa i ostrzega o niestrzeżonych wywołaniach nowszych interfejsów API. Jest ona spalona w skompilowanym zestawie projektu jako UnsupportedOSPlatformAttribute atrybutu zestawu, dzięki czemu analizator zgodności platformy może wykrywać niestrzeżone wywołania do interfejsów API tego zestawu z projektami o niższej SupportedOSPlatformVersion wartości. Na niektórych platformach SupportedOSPlatformVersion wartość ma wpływ na tworzenie i pakowanie aplikacji specyficznych dla platformy, które zostały omówione w dokumentacji dla tych platform.

Oto przykładowy fragment pliku projektu, który używa TargetFramework właściwości i SupportedOSPlatformVersion MSBuild do określenia, że aplikacja lub biblioteka ma dostęp do interfejsów API systemu iOS 15.0, ale obsługuje uruchamianie w systemie iOS 13.0 i nowszych:

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

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

  ...

</Project>

Jak określić strukturę docelową

Struktury docelowe są określone w pliku projektu. Po określeniu pojedynczej platformy docelowej użyj elementu TargetFramework. Poniższy plik projektu aplikacji konsolowej pokazuje, jak kierować platformę .NET 6:

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

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

</Project>

Podczas określania wielu platform docelowych można warunkowo odwoływać się do zestawów dla każdej platformy docelowej. W kodzie można warunkowo skompilować je przy użyciu symboli preprocesora z logiką if-then-else .

Poniższy projekt biblioteki dotyczy interfejsów API platformy .NET Standard (netstandard1.4) i .NET Framework (net40 i net45). Użyj elementu TargetFrameworks w liczbie mnogiej z wieloma platformami docelowymi. Atrybuty Condition obejmują pakiety specyficzne dla implementacji, gdy biblioteka jest kompilowana dla dwóch .NET Framework serwera TFM:

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

W bibliotece lub aplikacji pisać kod warunkowy przy użyciu dyrektyw preprocesora do kompilowania dla każdej platformy docelowej:

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

System kompilacji jest świadomy symboli preprocesora reprezentujących platformy docelowe wyświetlane w tabeli Obsługiwane wersje platform docelowych podczas korzystania z projektów w stylu zestawu SDK. W przypadku używania symbolu reprezentującego platformę .NET Standard, .NET Core lub .NET 5+ TFM zastąp kropki i łączniki znakiem podkreślenia, a następnie zmień małe litery na wielkie litery (na przykład symbol dla netstandard1.4 elementu to NETSTANDARD1_4). Możesz wyłączyć generowanie tych symboli za pomocą DisableImplicitFrameworkDefines właściwości . Aby uzyskać więcej informacji na temat tej właściwości, zobacz DisableImplicitFrameworkDefines.

Pełna lista symboli preprocesora dla platform docelowych platformy .NET to:

Platformy docelowe Symbole Dodatkowe symbole dostępne w zestawie SDK platformy .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+ (i .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

Uwaga

  • Symbole bez wersji są definiowane niezależnie od docelowej wersji.
  • Symbole specyficzne dla wersji są definiowane tylko dla docelowej wersji.
  • Symbole <framework>_OR_GREATER są definiowane dla docelowej wersji i wszystkich wcześniejszych wersji. Jeśli na przykład celujesz .NET Framework 2.0, zdefiniowane są następujące symbole: NET20, , NET20_OR_GREATERNET11_OR_GREATERi NET10_OR_GREATER.
  • Różnią się one od elementów monikers platform docelowych (TFM) używanych przez właściwość MSBuild TargetFramework i nuGet.

Przestarzałe platformy docelowe

Następujące platformy docelowe są przestarzałe. Pakiety przeznaczone dla tych platform docelowych powinny zostać poddane migracji do wskazanych zastąpień.

Przestarzałe program TFM Funkcja zastępująca
aspnet50
aspnetcore50
dnxcore50
Dnx
dnx45
dnx451
dnx452		 netcoreapp
dotnet
dotnet50
dotnet51
dotnet52
dotnet53
dotnet54
dotnet55
dotnet56		 netstandard
netcore50 uap10.0
wygrać netcore45
win8 netcore45
win81 netcore451
win10 uap10.0
winrt netcore45

Zobacz też