Поделиться через

Как указать целевые платформы

  • Статья

При выборе целевой платформы для приложения или библиотеки вы указываете набор API-интерфейсов, которые вы хотите сделать доступными для приложения или библиотеки. Целевая платформа указывается в файле проекта с помощью моникеров целевой платформы (TFM).

Приложение или библиотека могут быть предназначены для версии .NET Standard. Версии .NET Standard представляют стандартные наборы API-интерфейсов во всех реализациях .NET. Например, библиотека может быть предназначена для .NET Standard 1.6 и получить доступ к API-интерфейсам, которые работают в .NET Core и .NET Framework с одной и той же базой кода.

Приложение или библиотека могут также работать в конкретной реализации .NET. В этом случае они получают доступ к API-интерфейсам конкретной реализации. Например, приложение, предназначенное для Xamarin.iOS (например, Xamarin.iOS10), получает доступ к предоставленным Xamarin iOS программам-оболочкам API для iOS 10 или приложение, ориентированное на универсальную платформу Windows (UWP, uap10.0) имеет доступ к API-интерфейсам, которые компилируются для устройств под управлением Windows 10.

Для некоторых целевых платформ (например, .NET Framework) API-интерфейсы определяются сборками, устанавливаемыми платформой в системе, в число которых могут входить API-интерфейсы платформы приложений (например, ASP.NET).

Для целевых платформ на основе пакетов (например, .NET 5+, .NET Core и .NET Standard) API-интерфейсы определяются пакетами NuGet в составе приложения или библиотеки.

Последние версии

В приведенной ниже таблице определены наиболее распространенные целевые платформы, способы их указания и реализованные в них версии .NET Standard. Эти версии целевой платформ являются последними стабильными версиями. Предварительные версии здесь не упоминаются. Моникер целевой платформы (TFM) — это стандартизированный формат маркера для указания целевой платформы приложения или библиотеки .NET.

Целевая платформа Самый поздний
Стабильная версия		 Моникер целевой платформы (TFM) Реализованы
Версия .NET Standard
.NET 8 8 net8.0 2.1
.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 Н/П
.NET Core 3.1 netcoreapp3.1 2.1
.NET Framework 4.8.1 net481 2.0

Неподдерживаемые целевые платформы

Целевая платформа обычно называется по TFM. В следующей таблице показаны целевые платформы, поддерживаемые пакетом SDK для .NET и клиентом NuGet. Эквивалентные обозначения отображаются в скобках. Например, win81 является эквивалентом TFM для netcore451.

Целевая платформа TFM
.NET 5+ (и .NET Core) netcoreapp1.0
netcoreapp1.1
netcoreapp2.0
netcoreapp2.1
netcoreapp2.2
netcoreapp3.0
netcoreapp3.1
net5.0*
net6.0*
net7.0*
net8.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
net481
Магазин Windows netcore [netcore45]
netcore45 [win] [win8]
netcore451 [win81]
.NET Micro Framework netmf
Silverlight sl4
sl5
Windows Phone wp [wp7]
wp7
wp75
wp8
wp81
wpa81
Универсальная платформа Windows uap [uap10.0]
uap10.0 [win10] [netcore50]

* .NET 5 и более поздних TFM включают некоторые варианты операционной системы. Дополнительные сведения см. в разделе TFM .NET 5+ для конкретной ОС.

TFM .NET 5+ для конкретной ОС

net5.0К ним net6.0net7.0net8.0 относятся технологии, работающие на разных платформах. Указание TFM для конкретной операционной системы делает API, которые относятся к определенной операционной системе, доступными для приложения, например привязки Windows Forms или iOS. TFM для конкретных ОС также наследуют каждый API, доступный соответствующему базовому TFM, например TFM net6.0.

В .NET 5 были представлены TFM net5.0-windows для конкретных операционных систем, в том числе привязки Windows для API WinForms, WPF и UWP. В .NET 6 и более поздних версиях есть дополнительные виртуальные машины, относящиеся к ОС, например net6.0-ios.

В следующей таблице приведены сведения о совместимости TFM .NET 5+.

TFM Совместимость
net5.0 net1.4 (с предупреждением NU1701)
netcoreapp1.3.1 (предупреждение при ссылке на WinForms или WPF)
netstandard1.2.1
net5.0-windows netcoreapp1.3.1 (и все остальное, унаследованное от net5.0)
net6.0 (Последнюю версию net5.0)
net6.0-android xamarin.android (плюс все остальное наследуется от net6.0)
net6.0-ios Все наследуется от net6.0
net6.0-maccatalyst Все наследуется от net6.0
net6.0-macos Все наследуется от net6.0
net6.0-tvos Все наследуется от net6.0
net6.0-windows (Последнюю версию net5.0-windows)
net7.0 (Последнюю версию net6.0)
net7.0-android (Последнюю версию net6.0-android)
net7.0-ios (Последнюю версию net6.0-ios)
net7.0-maccatalyst (Последнюю версию net6.0-maccatalyst)
net7.0-macos (Последнюю версию net6.0-macos)
net7.0-tizen tizen40 (плюс все остальное наследуется от net7.0)
net7.0-tvos (Последнюю версию net6.0-tvos)
net7.0-windows (Последнюю версию net6.0-windows)
net8.0 (Последнюю версию net7.0)
net8.0-android (Последнюю версию net7.0-android)
net8.0-browser Все наследуется от net8.0
net8.0-ios (Последнюю версию net7.0-ios)
net8.0-maccatalyst (Последнюю версию net7.0-maccatalyst)
net8.0-macos (Последнюю версию net7.0-macos)
net8.0-tizen (Последнюю версию net7.0-tizen)
net8.0-tvos (Последнюю версию net7.0-tvos)
net8.0-windows (Последнюю версию net7.0-windows)

Чтобы сделать приложение кросс-платформенным, но при этом сохранить доступ к API определенных ОС, можно ориентироваться на несколько TFM для определенных операционных систем и добавить условия платформы для вызовов API, зависящих от операционной системы, с помощью директив препроцессора #if. Список доступных символов см. в разделе "Символы препроцессора".

Предлагаемые целевые объекты

Используйте эти рекомендации, чтобы определить, какие TFM использовать в приложении:

  • Приложения, переносимые на несколько платформ, должны быть ориентированы на базовый TFM, например для net8.0. Сюда входит большинство библиотек, а также ASP.NET Core и Entity Framework.

  • Библиотеки для конкретных платформ должны быть ориентированы на варианты приложения для определенных платформ. Например, в проектах WinForms и WPF следует ориентироваться net8.0-windows.

  • Модели кросс-платформенных приложений (Xamarin Forms, ASP.NET Core) и соединительные пакеты (Xamarin Essentials) должны быть ориентированы как минимум на базовый TFM, например net8.0, но также могут быть ориентированы на дополнительные варианты приложения для определенных платформ, чтобы обеспечить поддержку дополнительных API и функций.

Версия ОС в TFM

Вы также можете указать необязательную версию ОС в конце TFM для конкретной ОС, например net6.0-ios15.0. Версия указывает, какие API-интерфейсы доступны для приложения или библиотеки. Он не управляет версией ОС, которую поддерживает ваше приложение или библиотека во время выполнения. Она используется для выбора ссылочных сборок, с которыми компилируется проект, а также для выбора ресурсов из пакетов NuGet. Эту версию можно рассматривать как "версию платформы" или "версию API ОС", чтобы устранить неоднозначность в версии ОС во время выполнения.

Если TFM конкретной ОС явно не указывает версию платформы, она имеет подразумеваемое значение, которое можно получить из базового TFM и имени платформы. Например, значение платформы по умолчанию для Android в .NET 6— 31.0это означает, что net6.0-android это сокращено для канонического net6.0-android31.0 TFM. Неявная версия платформы для более нового базового TFM может быть выше, например, будущий TFM net8.0-android может сопоставляться с net8.0-android34.0. Сокращенная форма предназначена для использования только в файлах проекта и расширяется до канонической формы с помощью целевых объектов MSBuild пакета SDK для .NET перед передачей в другие средства, такие как NuGet.

В следующей таблице показаны значения целевой платформы по умолчанию (TPV) для каждого выпуска .NET.

Версия .NET Android iOS Mac Catalyst macOS tvOS Tizen Windows
.NET 6 31,0 15,0 15,0 12,0 15,1 - 7.0
.NET 7 33,0 16.1 16.1 13,0 16.1 7.0 7.0
.NET 8 34,0 17,2 17,2 14,2 17.1 8.0 7.0

Примечание.

На платформах Apple (iOS, macOS, tvOS и Mac Catalyst) в .NET 8 и более ранних версиях TPV по умолчанию является последней поддерживаемой версией в текущей установленной рабочей нагрузке. Это означает, что обновление рабочей нагрузки iOS в .NET 8 может привести к более высокому TPV по умолчанию, если добавлена поддержка новой версии iOS в этой рабочей нагрузке. В предыдущей таблице TPV по умолчанию — это тот, который находится в первоначальном выпуске для указанной версии .NET.

Начиная с .NET 9, это специальное поведение применяется только к исполняемым проектам. TPV по умолчанию для проектов библиотеки теперь остается неизменным для всего основного выпуска .NET, как и для всех остальных платформ.

Пакет SDK для .NET предназначен для поддержки недавно выпущенных API-интерфейсов для отдельной платформы без новой версии базового TFM. Это позволяет получить доступ к функциональным возможностям для конкретной платформы, не дожидаясь основного выпуска .NET. Вы можете получить доступ к этим недавно выпущенным API-интерфейсам, увеличив версию платформы в TFM. Например, если платформа Android добавила API уровня 32 в обновление пакета SDK для .NET 6.0.x, вы можете получить к ним доступ с помощью TFM net6.0-android32.0.

Приоритет

Если приложение ссылается на пакет с несколькими ресурсами для разных TFM, предпочтительнее использовать ресурсы, которые ближе к номеру версии. Например, если целевые объекты net6.0-ios приложения и пакет предлагают ресурсы для net6.0 и net5.0-iosиспользуются net6.0 ресурсы. Дополнительные сведения см. в разделе "Приоритеты".

Поддержка старых версий ОС

Несмотря на то что приложение или библиотека для конкретной платформы компилируются для API-интерфейсов из определенной версии этой ОС, вы можете сделать их совместимыми с более ранними версиями ОС, добавив свойство SupportedOSPlatformVersion в файл проекта. Свойство SupportedOSPlatformVersion указывает минимальную версию ОС, необходимую для запуска приложения или библиотеки. Если вы явно не укажете эту минимальную версию ОС времени выполнения в проекте, по умолчанию используется версия платформы из TFM.

Чтобы приложение правильно выполнялось в более старой версии ОС, оно не может вызывать API-интерфейсы, которых нет в этой версии ОС. Однако можно добавить условия для вызовов к более новым API-интерфейсам, чтобы они вызывались только при работе в той версии ОС, которая их поддерживает. Этот шаблон позволяет проектировать приложение или библиотеку для поддержки работы в более старых версиях ОС, используя преимущества новых функций ОС при работе в более новых версиях ОС.

Значение SupportedOSPlatformVersion (явное или по умолчанию) используется анализатором совместимости платформ, который обнаруживает и предупреждает о незащищенных вызовах к более новым API-интерфейсам. Оно записывается в скомпилированную сборку проекта как атрибут сборки UnsupportedOSPlatformAttribute, чтобы анализатор совместимости платформ мог обнаруживать незащищенные вызовы к API-интерфейсам сборки из проектов с меньшим значением SupportedOSPlatformVersion. На некоторых платформах значение SupportedOSPlatformVersion влияет на процессы упаковки и сборки приложений для конкретных платформ, которые рассматриваются в документации по этим платформам.

Ниже приведен пример фрагмента файла проекта, который использует свойства MSBuild TargetFramework и SupportedOSPlatformVersion, чтобы указать, что приложение или библиотека имеет доступ к API-интерфейсам iOS 15.0, но поддерживает выполнение в iOS 13.0 и более поздних версиях:

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

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

</Project>

Как указать целевую платформу

Целевые платформы указываются в файле проекта. Если указана одна целевая платформа, используйте элемент TargetFramework. В следующем файле проекта консольного приложения показано, как нацелиться на .NET 8:

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

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

</Project>

При указании нескольких целевых платформ можно условно ссылаться на сборки для каждой целевой платформы. В коде можно условно скомпилировать эти сборки с помощью символов препроцессора с логикой if-then-else .

Следующий файл проекта библиотеки предназначен для AP .NET Standard (netstandard1.4) и .NET Framework (net40 и net45). Используйте множественный элемент TargetFrameworks с несколькими целевыми платформами. Атрибуты Condition включают пакеты, связанные с конкретной реализацией, при компиляции библиотеки для двух TFM .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>

В библиотеке или приложении следует написать условный код компиляции с помощью директив препроцессора для каждой целевой платформы.

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

Символы препроцессора

Система сборки учитывает символы препроцессора, представляющие целевые платформы, которые приведены в таблице Поддерживаемые версии целевой платформы, при использовании проектов в стиле SDK. Чтобы преобразовать .NET Standard, .NET Core или .NET 5+ TFM в символ препроцессора, замените точки и дефисы подчеркиванием и измените строчные буквы на верхний регистр (например, символ для netstandard1.4 этого).NETSTANDARD1_4

Вы можете отключить создание этих символов с помощью DisableImplicitFrameworkDefines свойства. Дополнительные сведения об этом свойстве см. в разделе DisableImplicitFrameworkDefines.

Полный список символов препроцессора для целевой платформы .NET.

Требуемые версии .NET Framework Символы Дополнительные символы
(доступно в пакетах SDK для .NET 5 и более поздних версий)		 Символы платформы (доступны только
при указании TFM для конкретной ОС)
.NET Framework NETFRAMEWORK, NET48NET472NET471NET47NET462NET461NET46NET452NET451NET45NET40NET35NET20 NET48_OR_GREATER, NET472_OR_GREATER, NET471_OR_GREATERNET47_OR_GREATERNET462_OR_GREATERNET461_OR_GREATERNET46_OR_GREATERNET452_OR_GREATERNET451_OR_GREATERNET45_OR_GREATERNET40_OR_GREATERNET35_OR_GREATERNET20_OR_GREATER
.NET Standard NETSTANDARD, NETSTANDARD2_1, NETSTANDARD2_0NETSTANDARD1_6NETSTANDARD1_5NETSTANDARD1_4NETSTANDARD1_3NETSTANDARD1_2NETSTANDARD1_1NETSTANDARD1_0 NETSTANDARD2_1_OR_GREATER, NETSTANDARD2_0_OR_GREATERNETSTANDARD1_6_OR_GREATERNETSTANDARD1_5_OR_GREATERNETSTANDARD1_4_OR_GREATERNETSTANDARD1_3_OR_GREATERNETSTANDARD1_2_OR_GREATERNETSTANDARD1_1_OR_GREATERNETSTANDARD1_0_OR_GREATER
.NET 5+ (и .NET Core) NET, NET8_0, NET7_0NET6_0NET5_0NETCOREAPPNETCOREAPP3_1NETCOREAPP3_0NETCOREAPP2_2NETCOREAPP2_1NETCOREAPP2_0NETCOREAPP1_1NETCOREAPP1_0 NET8_0_OR_GREATER, NET7_0_OR_GREATER, NET6_0_OR_GREATERNET5_0_OR_GREATERNETCOREAPP3_1_OR_GREATERNETCOREAPP3_0_OR_GREATERNETCOREAPP2_2_OR_GREATERNETCOREAPP2_1_OR_GREATERNETCOREAPP2_0_OR_GREATERNETCOREAPP1_1_OR_GREATERNETCOREAPP1_0_OR_GREATER ANDROID, BROWSER, IOSMACCATALYSTMACOSTVOSWINDOWS
[OS][version] (например IOS15_1),
[OS][version]_OR_GREATER (например IOS15_1_OR_GREATER)

Примечание.

  • Символы без привязки к версии определены независимо от версии, которую вы хотите использовать в качестве целевой.
  • Символы для определенных версий определены только для тех версий, которые вы хотите использовать в качестве целевых.
  • Символы <framework>_OR_GREATER определены для версии, которую вы хотите использовать в качестве целевой, и всех более ранних версий. Например, если вы выбрали .NET Framework 2.0, определяются следующие символы: NET20, NET20_OR_GREATER, NET11_OR_GREATER и NET10_OR_GREATER.
  • NETSTANDARD<x>_<y>_OR_GREATER Символы определяются только для целевых объектов .NET Standard, а не для целевых объектов, реализующих .NET Standard, таких как .NET Core и платформа .NET Framework.
  • Они отличаются от моникеров целевой платформы (TFM), используемых свойством MSBuild TargetFramework и NuGet.

Неподдерживаемые целевые платформы

Следующие целевые платформы являются устаревшими. Пакеты, предназначенные для этих целевых платформ, следует перевести на предлагаемые для замены.

Нерекомендуемый TFM Замена
aspnet50
aspnetcore50
dnxcore50
dnx
dnx45
dnx451
dnx452		 netcoreapp
dotnet
dotnet50
dotnet51
dotnet52
dotnet53
dotnet54
dotnet55
dotnet56		 netstandard
netcore50 uap10.0
победа netcore45
win8 netcore45
win81 netcore451
win10 uap10.0
winrt netcore45

См. также