Целевые фреймворки в проектах с использованием стиля SDK

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

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

Приложение или библиотека могут также работать в конкретной реализации .NET. В этом случае они получают доступ к API-интерфейсам конкретной реализации. Например, приложение, предназначенное для универсальной платформы 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. В следующей таблице показаны целевые платформы, поддерживаемые пакетом SDK для .NET и клиентом NuGet. Эквивалентные обозначения отображаются в скобках. Например, win81 является эквивалентом TFM для netcore451.

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

TFM .NET 5+ для конкретных операционных систем

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

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

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

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

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

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

• Приложения, переносимые на несколько платформ, должны быть ориентированы на базовый TFM, например, net9.0. Сюда входит большинство библиотек, а также ASP.NET Core и Entity Framework.
• Библиотеки для конкретных платформ должны быть ориентированы на варианты приложения для определенных платформ. Например, проекты WinForms и WPF должны быть нацелены на net9.0-windows.
• Кроссплатформенные модели приложений (например, ASP.NET Core) должны по крайней мере ориентироваться на базовый TFM, например, net9.0, но могут также нацеливаться на дополнительные платформенные варианты для активации дополнительных API или функций.

Версия ОС в TFM

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

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

Если TFM конкретной ОС явно не указывает версию платформы, она имеет подразумеваемое значение, которое можно получить из базового TFM и имени платформы. Например, версия платформы по умолчанию для Android в .NET 9 — 35.0, что означает, что net9.0-android является сокращением для канонического netp.0-android35.0 TFM. Сокращенная форма предназначена для использования только в файлах проекта и расширяется до канонической формы с помощью целевых объектов MSBuild пакета SDK для .NET перед передачей в другие средства, такие как NuGet.

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

Начиная с .NET 9, когда выпуски служб предоставляют поддержку более поздней версии TPV (которая всегда будет иметь тот же основной номер версии, что и при первоначальной выпуске версии .NET), самый ранний поддерживаемый TPV для этой версии .NET останется поддерживаемым. Например, для .NET 9 самая ранняя поддерживаемая версия iOS 18.0 будет поддерживаться, даже если выпуск службы добавляет поддержку последней версии iOS 18.x. Если вам нужно использовать самые ранние привязки для выпуска .NET, используйте определенный номер версии ОС в TFM.

Приоритет

Если приложение ссылается на пакет с несколькими ресурсами для разных 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 9:

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.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. Чтобы преобразовать TFM .NET Standard, .NET Core или .NET 5+ в символ препроцессора, замените точки и дефисы на подчеркивание и измените строчные буквы на заглавные (например, символ для netstandard1.4 — это NETSTANDARD1_4).

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

Полный список символов препроцессора для целевых платформ .NET заключается в следующем.

Устаревшие целевые фреймворки

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

См. также

• Имена целевых платформ в .NET 5
• .NET Standard
• Управление версиями .NET
• Сведения о выпуске Windows 11