Platformy docelowe w projektach w stylu zestawu SDK

W przypadku określania struktury jako docelowej w aplikacji lub bibliotece należy określić zestaw interfejsów API, które mają być dostępne dla aplikacji lub biblioteki. Platformę docelową można określić w pliku projektu przy użyciu monikera struktury docelowej (TFM).

Aplikacja lub biblioteka może być docelową wersją .NET Standard. .NET Standard reprezentują standardowe zestawy interfejsów API we wszystkich implementacjach .NET. Na przykład biblioteka może być ukierunkowana na platformę .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ż ukierunkować określoną implementację .NET, aby uzyskać dostęp do interfejsów API specyficznych dla implementacji. Na przykład aplikacja, która jest przeznaczony dla platformy Xamarin.iOS (na przykład ) ma dostęp do otok interfejsu API dla systemu iOS dostarczanych przez platformę Xamarin dla systemu iOS 10 lub aplikacja, która jest przeznaczony dla platformy uniwersalnej systemu Windows (UWP, ) ma dostęp do interfejsów API, które kompilują się dla urządzeń z systemem Xamarin.iOS10 uap10.0 Windows 10.

W przypadku niektórych platform docelowych, takich jak .NET Framework, interfejsy API są definiowane przez zestawy zainstalowane w systemie przez tę platformę i mogą zawierać interfejsy API struktury 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 struktury docelowe, sposób, w jaki się do nich odwoływano i która wersja .NET Standard implementowane. Te wersje platform docelowych to najnowsze stabilne wersje. Wersje wstępne nie są wyświetlane. Moniker struktury docelowej (TFM) to standardowy format tokenu do określania docelowej struktury aplikacji lub biblioteki .NET.

Docelowa framework Najnowsza
stabilna wersja
Moniker struktury docelowej (TFM) Zaimplementowana
.NET Standard wersji
.NET 5 5.0 net5.0 Nie dotyczy
.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 struktury docelowe

Do struktury docelowej zazwyczaj odwołuje się program TFM. W poniższej tabeli przedstawiono platformy docelowe obsługiwane przez zestaw .NET SDK i NuGet klienta. Odpowiedniki są wyświetlane w nawiasach kwadratowych. Na przykład jest win81 odpowiednikiem programu TFM dla 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
.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]

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

Program TFM specyficzny dla systemu operacyjnego .NET 5+

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

Na platformie .NET 5 wprowadzono program TFM specyficzny dla systemu operacyjnego, który Windows powiązania specyficzne dla net5.0-windows winForms, WPF i interfejsów API platformy UWP. W programie .NET 6 wprowadzono kolejne specyficzne dla systemu operacyjnego tfms.

W poniższej tabeli przedstawiono zgodność programu .NET 5+ TFM.

TFM Zgodny z
net5.0 net1.. 4 (z ostrzeżeniem NU1701)
netcoreapp1.. 3.1 (ostrzeżenie w przypadku odwołania do formularzy WinForms lub WPF)
netstandard1.. 2.1
net5.0-windows netcoreapp1.. 3.1 (plus wszystkie inne dziedziczone z net5.0 )
net6.0 (kolejna wersja net5.0 programu )
net6.0-android xamarin.android (+ wszystkie inne dziedziczone z net6.0 )
net6.0-ios xamarin.ios (+ wszystkie inne dziedziczone z net6.0 )
net6.0-macos xamarin.mac (+ wszystkie inne dziedziczone z net6.0 )
net6.0-maccatalyst xamarin.ios (+ wszystkie inne dziedziczone z net6.0 )
net6.0-tvos xamarin.tvos (+ wszystkie inne dziedziczone z net6.0 )
net6.0-windows (kolejna wersja net5.0-windows programu )

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

Sugerowane cele

Użyj tych wytycznych, aby określić, którego programu TFM użyć w aplikacji:

  • Aplikacje przenośne na wiele platform powinny być docelowe dla podstawowego programu TFM, na przykład net5.0 . Obejmuje to większość bibliotek, ale również ASP.NET Core i Entity Framework.

  • Biblioteki specyficzne dla platformy powinny być ukierunkowane na odmiany specyficzne dla platformy. Na przykład projekty WinForms i WPF powinny mieć element docelowy net5.0-windows lub net6.0-windows .

  • Międzyplatformowe modele aplikacji (Xamarin Forms, ASP.NET Core) i pakiety mostka (Xamarin Essentials) powinny być co najmniej ukierunkowane na podstawowy program TFM, na przykład , ale mogą również być ukierunkowane na dodatkowe odmiany specyficzne dla platformy, aby oświetlić więcej interfejsów net6.0 API lub funkcji.

Wersja systemu operacyjnego w programie TFM

Możesz również określić opcjonalną wersję systemu operacyjnego na końcu programu 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, która jest wspierana przez aplikację lub bibliotekę w czasie działania. Służy do wybierania zestawów odwoływać, z których kompiluje się projekt, oraz do wybierania zasobów z NuGet pakietów. Tę wersję należy myśleć jak o "wersji platformy" lub "wersji interfejsu API systemu operacyjnego", aby odszukać ją od wersji systemu operacyjnego w czasie rzeczywistym.

Jeśli program TFM specyficzny dla systemu operacyjnego nie określa jawnie wersji platformy, ma dorozumianą wartość, która może zostać wywnioskowana na podstawie podstawowej nazwy serwera TFM i platformy. Na przykład domyślna wartość platformy dla systemu iOS na platformie .NET 6 to , co oznacza, że jest skrótem dla kanonicznej wersji 15.0 net6.0-ios serwera net6.0-ios15.0 TFM. Implikowana wersja platformy dla nowszego podstawowego programu TFM może być wyższa, na przykład przyszła wersja net7.0-ios tfm może być mapowana na net7.0-ios16.0 . Skrócony formularz jest przeznaczony tylko do użycia w plikach projektu i jest rozszerzany do postaci kanonicznej przez obiekty docelowe zestawu .NET SDK MSBuild przed ich przekazem do innych narzędzi, takich jak NuGet.

Zestaw SDK platformy .NET zaprojektowano tak, aby mógł obsługiwać nowo wydane interfejsy API dla poszczególnych platform bez nowej wersji podstawowego programu TFM. Dzięki temu można uzyskać 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ć, inkrementując wersję platformy w programie TFM. Jeśli na przykład platforma iOS dodała interfejsy API systemu iOS 15.1 w aktualizacji zestawu SDK platformy .NET 6.0.x, można 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ą ustawić jako zgodną z wcześniejszymi wersjami systemu operacyjnego, dodając właściwość do SupportedOSPlatformVersion 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 uruchamiania w projekcie, zostanie ona domyślnie określona jako wersja platformy z programu TFM.

Aby aplikacja działała poprawnie w starszej wersji systemu operacyjnego, nie może wywołać interfejsów API, które nie istnieją w tej wersji systemu operacyjnego. Można jednak dodać funkcje ochrony wokół wywołań do nowszej wersji 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 skorzystaniu z nowszej funkcjonalności systemu operacyjnego w przypadku uruchamiania w nowszej wersji systemu operacyjnego.

Wartość (jawna lub domyślna) jest używana przez analizator zgodności platformy , który wykrywa niestrzeżone wywołania do nowszej interfejsów API i ostrzega o SupportedOSPlatformVersion nich. Jest on spalony w zestawie skompilowanym w projekcie jako atrybut zestawu, dzięki czemu analizator zgodności platformy może wykrywać niestrzeżone wywołania do interfejsów API tego zestawu z projektów o mniejszej UnsupportedOSPlatformAttribute SupportedOSPlatformVersion wartości. Na niektórych platformach ta wartość ma wpływ na procesy tworzenia i tworzenia pakietów aplikacji specyficzne dla platformy, które zostały uwzględnione w SupportedOSPlatformVersion dokumentacji dla tych platform.

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

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

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

  ...

</Project>

Jak określić platformę docelową

Struktury docelowe są określone w pliku projektu. Jeśli określono pojedynczą platformę docelową, użyj elementu TargetFramework. Poniższy plik projektu aplikacji konsolowej przedstawia sposób kierowania do programu .NET 5.0:

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

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

</Project>

W przypadku określenia wielu platform docelowych można warunkowo odwoływać się do zestawów dla każdej struktury docelowej. W kodzie można warunkowo skompilować względem tych zestawów przy użyciu symboli preprocesora z logiką if-then-else.

Poniższy projekt biblioteki jest przeznaczony dla interfejsów API .NET Standard ( netstandard1.4 ) i .NET Framework ( i net40 net45 ). Użyj elementu TargetFrameworks w liczbie mnogiej z wieloma platformami docelowymi. Atrybuty obejmują pakiety specyficzne dla implementacji, gdy biblioteka jest kompilowana dla dwóch .NET Framework Condition 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 piszesz kod warunkowy przy użyciu dyrektyw preprocesora, aby skompilować dla każdej struktury 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 wie o symbolach preprocesora reprezentujących platformy docelowe przedstawione w tabeli Obsługiwane wersje platformy docelowej, gdy używasz projektów w stylu zestawu SDK. W przypadku używania symbolu reprezentującego .NET Standard, .NET Core lub .NET 5 TFM zastąp kropki i łączniki podkreśleniem, a małe litery na wielkie (na przykład symbol to netstandard1.4 NETSTANDARD1_4 ).

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

Platformy docelowe Symbole
.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, NET6_0, NET6_0_ANDROID, NET6_0_IOS, NET6_0_MACOS, NET6_0_MACCATALYST, NET6_0_TVOS, NET6_0_WINDOWS, NET5_0, NETCOREAPP, NETCOREAPP3_1, NETCOREAPP3_0, NETCOREAPP2_2, NETCOREAPP2_1, NETCOREAPP2_0, NETCOREAPP1_1, NETCOREAPP1_0, NET6_0_OR_GREATER, NET6_0_ANDROID_OR_GREATER, NET6_0_IOS_OR_GREATER, NET6_0_MACOS_OR_GREATER, NET6_0_MACCATALYST_OR_GREATER, NET6_0_TVOS_OR_GREATER, NET6_0_WINDOWS_OR_GREATER, NET5_0_OR_GREATER, NETCOREAPP_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

Uwagi:

  • Symbole bez wersji są definiowane niezależnie od docelowej wersji.
  • Symbole specyficzne dla wersji są definiowane tylko dla docelowej wersji.
  • Symbole są zdefiniowane dla docelowej wersji i XXX_OR_GREATER wszystkich wcześniejszych wersji.

Przestarzałe struktury docelowe

Następujące struktury docelowe są przestarzałe. Pakiety, które są docelowe dla tych platform docelowych, powinny zostać zmigrowane do wskazanych zamian.

Przestarzały 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ż