Обучение
Модуль
Из этого модуля вы узнаете, в каких случаях, с какой целью и каким образом следует модернизировать приложение ASP.NET Framework до ASP.NET Core с помощью помощника по обновлению.
Этот браузер больше не поддерживается.
Выполните обновление до Microsoft Edge, чтобы воспользоваться новейшими функциями, обновлениями для системы безопасности и технической поддержкой.
При выборе целевой платформы для приложения или библиотеки вы указываете набор 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 9 | 9 | net9.0 | 2.1 |
.NET 8 | 8 | net8.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+ для конкретной ОС.
net5.0
TFM и net.0
, а также net6.0
net7.0
net8.0
технологии, работающие на разных платформах. Указание TFM для конкретной операционной системы делает API, которые относятся к определенной операционной системе, доступными для приложения, например привязки Windows Forms или iOS. TFM для конкретных ОС также наследуют каждый API, доступный соответствующему базовому TFM, например TFM net9.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 ) |
net9.0 |
(Последнюю версию net8.0 ) |
net9.0-android |
(Последнюю версию net8.0-android ) |
net9.0-browser |
(Последнюю версию net8.0-browser ) |
net9.0-ios |
(Последнюю версию net8.0-ios ) |
net9.0-maccatalyst |
(Последнюю версию net8.0-maccatalyst ) |
net9.0-macos |
(Последнюю версию net8.0-macos ) |
net9.0-tizen |
(Последнюю версию net8.0-tizen ) |
net9.0-tvos |
(Последнюю версию net8.0-tvos ) |
net9.0-windows |
(Последнюю версию net8.0-windows ) |
Чтобы сделать приложение кросс-платформенным, но при этом сохранить доступ к API определенных ОС, можно ориентироваться на несколько TFM для определенных операционных систем и добавить условия платформы для вызовов API, зависящих от операционной системы, с помощью директив препроцессора #if
. Список доступных символов см. в разделе "Символы препроцессора".
Используйте эти рекомендации, чтобы определить, какие TFM использовать в приложении:
net9.0
. Сюда входит большинство библиотек, а также ASP.NET Core и Entity Framework.net9.0-windows
.net9.0
, но также могут быть ориентированы на дополнительные варианты приложения для определенных платформ, чтобы обеспечить поддержку дополнительных API и функций.Вы также можете указать необязательную версию ОС в конце 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 8 | 34,0 | 17,2 | 17,2 | 14,2 | 17.1 | 7.0 | 10.0 |
.NET 9 | 35,0 | 18,0 | 18,0 | 15,0 | 7.0 | 10.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 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. Чтобы преобразовать .NET Standard, .NET Core или .NET 5+ TFM в символ препроцессора, замените точки и дефисы подчеркиванием и измените строчные буквы на верхний регистр (например, символ для netstandard1.4
этого).NETSTANDARD1_4
Вы можете отключить создание этих символов с помощью DisableImplicitFrameworkDefines
свойства. Дополнительные сведения об этом свойстве см. в разделе DisableImplicitFrameworkDefines.
Полный список символов препроцессора для целевой платформы .NET.
Требуемые версии .NET Framework | Символы | Дополнительные символы (доступно в пакетах SDK для .NET 5 и более поздних версий) |
Символы платформы (доступны только при указании TFM для конкретной ОС) |
---|---|---|---|
.NET Framework | NETFRAMEWORK NET48 , NET481 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+ (и .NET Core) | NET , NET9_0 NET8_0 NET7_0 NET6_0 NET5_0 NETCOREAPP NETCOREAPP3_1 NETCOREAPP3_0 NETCOREAPP2_2 NETCOREAPP2_1 NETCOREAPP2_0 NETCOREAPP1_1 NETCOREAPP1_0 |
NET8_0_OR_GREATER , 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 , BROWSER , IOS MACCATALYST MACOS TVOS WINDOWS [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.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 |
Отзыв о .NET
.NET — это проект с открытым исходным кодом. Выберите ссылку, чтобы оставить отзыв:
Обучение
Модуль
Из этого модуля вы узнаете, в каких случаях, с какой целью и каким образом следует модернизировать приложение ASP.NET Framework до ASP.NET Core с помощью помощника по обновлению.