обзор версий Windows и пакета SDK

Когда вы начнёте создавать приложения для Windows, вы заметите упоминания о нескольких разных версиях — версии ОС Windows, версии Windows SDK и версии Windows App SDK. Не беспокойтесь: для большинства новых проектов Visual Studio задает разумные значения по умолчанию, и вам не нужно думать об этом вообще. Но если вам всё же нужно ориентироваться на конкретную версию ОС, понять, почему тот или иной API недоступен, или настроить файл проекта, в этой статье объясняется, как всё это связано между собой и какой вариант выбрать.

Definitions

Component Что это такое Формат версии Как оно обновляется
версия ОС Windows Операционная система, установленная на устройстве пользователя. YYHX (например, 24H2, 25H2) клиентский компонент Центра обновления Windows (ежегодные обновления компонентов)
пакет SDK Windows (пакет SDK для платформы) Заголовки, библиотеки и метаданные для API Win32, WinRT и COM. 10.0.BBBBB.x (например, 10.0.26100.0) Установлен с помощью Visual Studio или автономного установщика
Пакет SDK для приложений Windows Распределенная платформа NuGet предоставляет WinUI 3, жизненный цикл приложений, окно и другие современные функции приложений. Major.Minor.Patch (например, 1.8.1) Обновление пакета NuGet в проекте

именование версий ОС Windows

Windows 11 поставляет основные обновления компонентов с помощью шаблона именования YHX:

  • Y = двухзначный календарный год
  • H1 = первая половина года; H2 = вторая половина года

Исторически большинство крупных релизов выходили осенью (H2), но релизы в первой половине года (H1) тоже бывают.

Версия ОС Windows Год выпуска Номер сборки ОС
Windows 11 22H2 2022 22621
Windows 11 23H2 2023 22631
Windows 11 24H2 2024 26100

Правило: Номер сборки ОС на устройстве пользователя определяет, какие API платформы доступны во время выполнения.

Подсказка

Проверьте номер сборки ОС на любом устройстве, нажав клавиши Win+ R и введя текст winver.

Сопоставление версий Windows SDK и ОС

Каждое семейство выпусков пакета SDK Windows соответствует Windows версии ОС. Старший номер сборки SDK обычно соответствует номеру сборки ОС, хотя некоторые функциональные обновления ОС (поставляемые в виде пакетов включения) используют то же семейство SDK, что и предыдущий выпуск.

семейство пакетов SDK Windows Сборка ОС Соответствует версии Windows
10.0.22621.x 22621 Windows 11 22H2 / 23H2
10.0.26100.x 26100 Windows 11 24H2

Note

В семействе SDK последний компонент (например, 10.0.26100.2454) представляют ежемесячные обновления обслуживания, которые добавляют исправления ошибок, но не новые API.

Правило: Установка заданного пакета SDK Windows предоставляет доступ во время компиляции ко всем API из этой версии ОС и всех предыдущих версий. API являются накопительными.

Версии Windows App SDK

Windows App SDK не зависит от ос Windows и пакета SDK Windows. Он распространяется по собственному графику в виде пакета NuGet.

Пакет SDK для приложений Windows Дата выпуска Минимальная поддерживаемая версия ОС Пакет NuGet
2,2 2026-06-09 Windows 10 1809 (сборка 17763) Microsoft.WindowsAppSDK 2.2.x
2.1 2026-05-21 Windows 10 1809 (сборка 17763) Microsoft.WindowsAppSDK 2.1.x
2.0 2026-04-29 Windows 10 1809 (сборка 17763) Microsoft.WindowsAppSDK 2.0.x
1.8 2025-09-09 Windows 10 1809 (сборка 17763) Microsoft.WindowsAppSDK 1.8.x
1.7 2025-03-18 Windows 10 1809 (сборка 17763) Microsoft.WindowsAppSDK 1.7.x

Правило: Последние Windows App SDK можно использовать в старых версиях ОС (назад к указанному минимуму). Версия Windows App SDK не должна соответствовать версии Windows ОС или версии пакета SDK Windows.

Полную матрицу поддержки см. в поддерживаемых выпусках Windows для Windows App SDK.

Как связаны три компонента

Your App (.exe / .msix)
  │
  ├── References: Windows App SDK (NuGet package, e.g., 2.2)
  │     • Provides: WinUI 3, app lifecycle, windowing, push notifications
  │     • Updated: independently via NuGet
  │     • Constraint: has a minimum supported OS version
  │
  ├── Compiled against: Windows SDK (e.g., 10.0.26100)
  │     • Provides: Win32, WinRT, COM API declarations
  │     • Updated: with Visual Studio or standalone installer
  │     • Constraint: determines which APIs are visible at compile time
  │
  └── Runs on: Windows OS (e.g., Windows 11 24H2, build 26100)
        • Provides: actual API implementations at runtime
        • Updated: Windows Update
        • Constraint: determines which APIs are callable at runtime

Ключевые связи:

  1. Windows App SDK не заменяет пакет SDK для Windows — вам нужно и то, и другое.
  2. Версия пакета SDK Windows может быть более новой, чем операционная система, в которой работает ваше приложение (используйте проверки среды выполнения для более новых API).
  3. Версия Windows App SDK полностью независима — обновите ее, не изменяя ничего другого.
  4. Вы не можете вызвать API платформы во время выполнения, если сборка ОС пользователя старее той сборки, в которой этот API впервые появился, независимо от того, для какого SDK было скомпилировано приложение.

Конфигурация файла проекта

Свойства MSBuild в файле проекта управляют выбором целевой платформы. Имена свойств немного отличаются между C# и C++:

Файл проекта C# (CSPROJ)

В проектах .NET в стиле SDK (используемых в шаблонах WinUI 3 и Windows App SDK) версия платформы Windows встроена в идентификатор целевой платформы (TFM):

<PropertyGroup>
    <!-- The TFM includes the Windows SDK version you compile against -->
    <TargetFramework>net8.0-windows10.0.26100.0</TargetFramework>

    <!-- The minimum OS version your app supports -->
    <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

    <!-- Or equivalently: -->
    <!-- <TargetPlatformMinVersion>10.0.19041.0</TargetPlatformMinVersion> -->
</PropertyGroup>

<ItemGroup>
    <!-- Windows App SDK (independent of the above) -->
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="2.2.0" />
</ItemGroup>

Note

SupportedOSPlatformVersion и TargetPlatformMinVersion эквивалентны в проектах в стиле SDK. Анализатор совместимости платформы SDK .NET используется SupportedOSPlatformVersion для выдачи предупреждений во время компиляции при вызове API, которые могут быть недоступны в минимальной версии ОС.

Файл проекта C++ (.vcxproj)

<PropertyGroup>
    <!-- Note: C++ uses "WindowsTargetPlatform" prefix -->
    <WindowsTargetPlatformVersion>10.0.26100.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17763.0</WindowsTargetPlatformMinVersion>
</PropertyGroup>
Свойство (C#) Purpose Эффект, если задано слишком большое значение Эффект, если задано слишком низкое значение
Версия Windows в TFM (TargetFramework) Область API во время компиляции Включает предупреждения анализатора платформы (преимущество, а не проблема) Более новые API невидимы; компилятор выдаёт ошибки, если вы ссылаетесь на них
SupportedOSPlatformVersion / TargetPlatformMinVersion Минимальная ОС для установки Меньше пользователей могут установить приложение Перед вызовом новых API необходимо добавить проверки среды выполнения.
Microsoft.WindowsAppSDK версия Функции WinUI 3 и платформы N/A (используйте последнюю стабильную версию) Отсутствуют новые элементы управления WinUI или функции платформы

Руководство по принятию решений: выбор версий

Используйте следующие правила для выбора версий для нового проекта:

  1. Установите версию платформы Windows в вашем TFM на последнюю стабильную версию Windows SDK (например, net8.0-windows10.0.26100.0). Это предоставляет вам наиболее широкий набор API, доступный на этапе компиляции, и включает предупреждения анализатора совместимости платформ для API, недоступных в вашей минимально поддерживаемой ОС.
  2. Задайте SupportedOSPlatformVersion (или TargetPlatformMinVersion) на основе аудитории:
    • Корпоративные приложения с управляемыми устройствами: соответствуют минимально поддерживаемой ОС вашей организации.
    • Потребительские приложения (самый широкий охват): 10.0.19041.0 (Windows 10 2004) или 10.0.17763.0 (Windows 10 1809).
    • Приложения, использующие функции из определенной версии ОС: задайте номер сборки этой версии.
  3. Всегда используйте последнюю стабильную Windows App SDK. Снижения совместимости нет; поддерживается Windows 10 версии 1809 и более поздние.
  4. Никогда не используйте выпуски предварительного и экспериментального пакета SDK в рабочей среде.

Проверки доступности API среды выполнения

Если версия платформы Windows в TFM выше, чемSupportedOSPlatformVersion, некоторые API, видимые во время компиляции, могут не существовать на устройстве пользователя. Анализатор совместимости платформы .NET предупреждает вас об этих возможностях во время компиляции, но перед их вызовом необходимо также проверить доступность во время выполнения.

Шаблон: Проверка контракта API (WinRT API)

using Windows.Foundation.Metadata;

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 15))
{
    // Safe to call APIs introduced in this contract version.
    // For example, use a newer composition API:
}
else
{
    // Fallback for older OS versions
}

Шаблон: проверка конкретного типа

if (ApiInformation.IsTypePresent("Windows.UI.Composition.SceneVisual"))
{
    // Safe to use SceneVisual
}

Шаблон: Проверка наличия конкретного метода

if (ApiInformation.IsMethodPresent("Windows.Storage.StorageFile", "GetFileFromPathForUserAsync"))
{
    // Safe to call this method
}

Правило: Если пропустить эти проверки и вызвать недоступный API, приложение завершится ошибкой во время выполнения. Точный характер сбоя зависит от типа API — к распространённым исключениям относятся TypeLoadException, MissingMethodException или специфичная для платформы ошибка.

Распространенные вопросы

"Какой пакет SDK Windows следует использовать?"

Используйте последнюю версию пакета SDK для Windows (в настоящее время — 10.0.26100). Вы всегда можете компилировать с использованием более новой версии SDK, чем ваша минимальная целевая версия, — это влияет только на то, что доступно на этапе компиляции.

"Необходимо ли обновить пакет SDK Windows при обновлении Windows App SDK?"

No. Они независимы. Вы можете обновить Microsoft.WindowsAppSDK с версии 1.7 до версии 1.8, не меняя версию Windows SDK.

"Мое приложение предназначено для Windows 10. Можно ли использовать Windows App SDK?"

Yes. Windows App SDK поддерживает Windows 10 версии 1809 (сборка 17763) и более поздних версий. Настройте SupportedOSPlatformVersion соответствующим образом.

"Что произойдет, если выполнить компиляцию по пакету SDK 10.0.26100, но пользователь запускает Windows 11 22H2 (сборка 22621)?"

API, появившиеся в сборках с 22621 по 26100, будут видны в вашем коде, но не будут работать во время выполнения, если вы не добавите проверки доступности API. API 22621 и более ранних версий будут работать нормально.

"Как узнать, какой номер сборки представил конкретный API?"

Проверьте справочную страницу API на Microsoft Learn. В разделе "Требования" перечислены минимальная сборка ОС (версия контракта API или версия Windows).

"Распределяются ли эти пакеты SDK с моим приложением?"

Нет — но части одного из них могут быть. Пакет SDK для Windows — это только средство времени разработки. Его заголовки и библиотеки используются компилятором, и ничего из него не поставляется в пакете приложения. Windows App SDK отличается: по умолчанию двоичные файлы среды выполнения включаются в пакет приложения (зависящие от платформы или автономные в зависимости от модели развертывания). При развертывании с зависимостью от платформы общая среда выполнения Windows App SDK устанавливается на устройстве один раз, и приложение ссылается на неё; при автономном развертывании необходимые двоичные файлы включаются непосредственно в пакет MSIX или выходную папку. В любом случае API платформы (Win32, WinRT, COM) всегда предоставляются самой ОС — вы никогда не отправляете их. Дополнительные сведения о вариантах развертывания см. в Windows App SDK обзоре развертывания.

Сводка правил

Правило Description
Версия ОС = возможность среды выполнения Сборка ОС пользователя определяет, какие API фактически работают во время выполнения.
пакет SDK Windows = область времени компиляции Установленный пакет SDK определяет, какие API отображаются в коде.
Windows App SDK = платформа приложений Обновляется с помощью NuGet, независимо от версий ПАКЕТА SDK для ОС и платформы.
SDK ≥ ОС — безопасно Вы можете компилировать с использованием более нового SDK, чем ваша минимальная целевая версия ОС.
Требуются проверки среды выполнения Если TFM нацелен на более высокую версию Windows, чемSupportedOSPlatformVersion, защитите более новые вызовы API с помощью проверок среды выполнения.
Обратная совместимость Windows App SDK Windows App SDK поддерживает Windows 10, начиная с версии 1809, независимо от версии выпуска.

Связанный контент

  • Last updated on