Вызов API среда выполнения Windows в настольных приложениях

Настройка проекта .NET

.NET 6 и более поздних версий: используйте параметр Moniker целевой платформы

Укажите специфичный для версии Windows ОС Target Framework Moniker (TFM) в файле проекта. В процессе сборки добавляется ссылка на соответствующий целевой пакет SDK для Windows.

1. В Visual Studio выберите свойства Project > [ProjectName] Properties.

2. На странице свойств найдите "Общие приложения>", выбрав его в левой части навигации или прокрутив его.

3. Выберите параметры для:

   1. Target framework — изначально задана версия .NET, выбранная при создании проекта, но ее можно изменить здесь.
   2. Target OS — оставьте это значение Windows.
   3. Целевая версия ОС — выберите версию для набора API, который вы хотите использовать, как правило, последнюю версию.
   4. Поддерживаемая версия ОС (необязательно) — дополнительные сведения см. в следующем разделе.

В Moniker Целевой платформы эти значения преобразуют следующим образом:

• Целевая платформа - net10.0
• Целевая ОС - -windows
• Целевая версия ОС - 10.0.22621.0

<TargetFramework>net10.0-windows10.0.22621.0</TargetFramework>
<!-- If set... -->
<SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

Можно также задать значения, изменив файл проекта вручную.

1. В Visual Studio щелкните правой кнопкой мыши project в Обозреватель решений и выберите Edit Project File.

2. Замените значение TargetFramework на значение TFM, специфичное для версии Windows.

   Target	TFM
   Windows 11 версии 24H2	net10.0-windows10.0.26100.0
   Windows 11, версия 22H2	net10.0-windows10.0.22621.0
   Windows 11 (первоначальный выпуск)	net10.0-windows10.0.22000.0
   Windows 10 версии 2004	net10.0-windows10.0.19041.0
   Windows 10 версии 1903	net10.0-windows10.0.18362.0
   Windows 10, версия 1809	net10.0-windows10.0.17763.0

   Замечание

   Отображаемые значения предназначены для .NET 10. Обновление по мере необходимости для других версий .NET: net8.0, net9.0.

   Пример:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
     </PropertyGroup>
   </Project>
   

3. Сохраните и закройте файл проекта.

Поддержка минимальной версии Windows

Чтобы разрешить приложению работать в версии Windows старше целевого объекта TFM, задайте SupportedOSVersion (SupportedOSPlatformVersion), как показано в предыдущем разделе. Дополнительные сведения см. в разделе "Целевые платформы: поддержка старых версий ОС".

При выборе диапазона версий ОС, используйте проверки ApiInformation для защиты вызовов API, которые недоступны во всех версиях. Дополнительные сведения см. в статье Приложения с адаптивным к версии кодом.

Если задан параметр SupportedOSVersion Visual Studio даст предупреждение для API, которым требуется проверка среды выполнения. Например, если целевая версия — 19041, а минимальная версия — 17763, при вызове AppInfo.Current появится предупреждение.

CA1416	Using platform dependent API on a component makes the code no longer work across all platforms.

This call site is reachable on: 'Windows' 10.0.17763.0 and later. 'AppInfo.Current' is only supported on: 'Windows' 10.0.19041.0 and later.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <SupportedOSPlatformVersion>10.0.17763.0</SupportedOSPlatformVersion>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
  </PropertyGroup>
</Project>

API WinRT не поддерживаются в .NET 6 и более поздних версий.

В .NET 6 и последующих версиях несколько API интерфейсов WinRT в пространстве имен Windows.UI не поддерживаются. Используйте эквивалентные API в пространстве имен Microsoft.UI (предоставлены Windows App SDK) вместо этого.

.NET Core 3.x или .NET Framework: установите пакет NuGet

Если приложение предназначено для .NET Core 3.x или .NET Framework, установите пакет NuGet Microsoft.Windows.SDK.Contracts:

1. В Visual Studio щелкните правой кнопкой мыши на вашем проекте и выберите Управление пакетами NuGet.

2. Найдите Microsoft.Windows.SDK.Contracts.

3. Выберите версию пакета, соответствующую минимальной целевой версии Windows.

   Версия пакета	целевой объект Windows
   10.0.19041.xxxx	Windows 10 версии 2004
   10.0.18362.xxxx	Windows 10 версии 1903
   10.0.17763.xxxx	Windows 10, версия 1809
   10.0.17134.xxxx	Windows 10 версии 1803

4. Нажмите кнопку "Установить".

Мультитаргетинг на .NET 6+ и более ранние версии .NET

Настройте файл проекта для использования подхода TFM для .NET 6+ и пакета NuGet для более ранних версий:

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFrameworks>netcoreapp3.1;net8.0-windows10.0.19041.0</TargetFrameworks>
    <UseWPF>true</UseWPF>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                     Include="Microsoft.Windows.SDK.Contracts"
                     Version="10.0.19041.0"/>
  </ItemGroup>
</Project>

Условная компиляция

При использовании нескольких целевых приложений в .NET 6 и более ранних версий используйте условную компиляцию для записи кода для конкретной версии в одном проекте. Дополнительные сведения см. в разделе "Целевые платформы: символы препроцессора".

#if NET6_0_OR_GREATER
    // Code that uses .NET 6+ APIs or TFM-available WinRT APIs
#else
    // Fallback code for .NET Core 3.x / .NET Framework
#endif

Настройка проекта C++ (Win32)

Используйте C++/WinRT, чтобы задействовать API WinRT из настольных приложений C++.

• Установите Microsoft.Windows. CppWinRT пакет NuGet.
• Так как C++/WinRT использует функции из стандарта C++17, Убедитесь, что свойство проекта C/C++ > Language > C++ Language Standard имеет значение ISO C++17 Standard (/std:c++17) или более поздней версии в Visual Studio.

Дополнительные сведения см. в разделе поддержка Visual Studio для C++/WinRT.