Windowsバージョンと SDK の概要

Windows アプリのビルドを開始すると、Windows OS のバージョン、Windows SDK、Windows アプリ SDKなど、いくつかの異なるバージョン番号への参照が表示されます。 心配しないでください。ほとんどの新しいプロジェクトでは、Visual Studioは適切な既定値を設定します。これについてはまったく考慮する必要はありません。 ただし、特定の OS バージョンをターゲットにする必要がある場合、API を使用できない理由を理解する必要がある場合、またはプロジェクト ファイルを構成する必要がある場合は、この記事では、要素がどのように一緒に収まるか、どのような選択肢を行うかについて説明します。

Definitions

Windows OS のバージョン命名

Windows 11は、名前付けパターン YYHX を使用して主要な機能更新プログラムを提供します。

• YY = 2 桁の暦年
• H1 = 年の前半; H2 = 年の後半

ほとんどのメジャー リリースは、過去に秋 (H2) に出荷されていますが、H1 リリースも発生します。

ルール: ユーザーのデバイス上の OS ビルド番号によって、実行時に使用できるプラットフォーム API が決まります。

Windows SDK から OS バージョンへの対応表

各Windows SDK リリース ファミリは、Windows OS バージョンに対応します。 SDK のメジャー ビルド番号は通常、OS ビルド番号と一致しますが、一部の OS 機能更新プログラム (有効化パッケージとして提供) では、以前のリリースと同じ SDK ファミリが共有されます。

ルール:特定のWindows SDK をインストールすると、その OS バージョンと以前のすべてのバージョンのすべての API へのコンパイル時アクセスが許可されます。 API は累積的です。

Windows アプリ SDK バージョン

Windows アプリ SDKは、Windows OS と Windows SDK の両方から独立しています。 NuGet パッケージとして独自の周期で出荷されます。

ルール：古い OS バージョンで最新のWindows アプリ SDKを使用できます (記載されている最小値に戻ります)。 Windows アプリ SDKのバージョンは、Windows OS のバージョンまたは WINDOWS SDK のバージョンと一致する必要はありません。

完全なサポート マトリックスについては、サポートされているWindows リリースWindows アプリ SDK参照してください。

3 つのコンポーネントの関係

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 アプリ SDKはWindows SDK を置き換えるのではなく、両方が必要です。
2. Windows SDK のバージョンは、アプリが実行されている OS よりも新しい場合があります (新しい API にはランタイム チェックを使用します)。
3. Windows アプリ SDK のバージョンは 完全に独立しています。他のものを何も変更せずに更新できます。
4. コンパイル対象の SDK に関係なく、ユーザーの OS ビルドが導入されたビルドよりも古い場合、実行時にプラットフォーム API を呼び出すことはできません。

プロジェクト ファイルの構成

プロジェクト ファイル内の MSBuild プロパティは、プラットフォーム ターゲットを制御します。 プロパティ名は、C# と C++ の間で若干異なります。

C# プロジェクト ファイル (.csproj)

SDK スタイルの.NET プロジェクト (WinUI 3 および Windows アプリ 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>

C++ プロジェクト ファイル (.vcxproj)

<PropertyGroup>
    <!-- Note: C++ uses "WindowsTargetPlatform" prefix -->
    <WindowsTargetPlatformVersion>10.0.26100.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17763.0</WindowsTargetPlatformMinVersion>
</PropertyGroup>

意思決定ガイド: バージョンの選択

新しいプロジェクトのバージョンを選択するには、次の規則を使用します。

1. TFM の Windows プラットフォーム バージョンを、最新の安定した Windows SDK (net8.0-windows10.0.26100.0 など) に設定します。 これにより、最も広範なコンパイル時 API サーフェスが提供され、最小 OS で使用できない API に対するプラットフォーム互換性アナライザーの警告が可能になります。
2. 対象ユーザーに基づいて SupportedOSPlatformVersion (または TargetPlatformMinVersion) を設定します。
   • マネージド デバイスを使用するエンタープライズ アプリ: 組織でサポートされている最小 OS と一致します。
   • コンシューマー アプリ (最も広い範囲): 10.0.19041.0 (Windows 10 2004) または10.0.17763.0 (Windows 10 1809)。
   • 特定の OS バージョンの機能を使用するアプリ: そのバージョンのビルド番号に設定します。
3. 常に最新の安定したWindows アプリ SDKを使用します。 互換性のペナルティはありません。Windows 10 1809 に戻ります。
4. 運用環境ではプレビュー/試験段階の SDK リリースを使用しないでください。

ランタイム API の可用性チェック

TFM のWindows プラットフォームバージョンが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、またはプラットフォーム固有のエラーが含まれます。

一般的な質問

"どのWindows SDK を使用する必要がありますか?

利用可能な最新のWindows SDK (現在 10.0.26100) を使用します。 ターゲットの最小値よりも新しい SDK に対していつでもコンパイルできます。コンパイル時に表示される内容にのみ影響します。

"Windows アプリ SDKを更新するときに、Windows SDK を更新する必要がありますか?

No. これらは独立しています。 Windows SDK のバージョンを変更することなく、Microsoft.WindowsAppSDKを 1.7 から 1.8 に更新できます。

"アプリはWindows 10をターゲットにしています。 Windows アプリ SDKを使用できますか?

Yes. Windows アプリ SDKでは、バージョン 1809 (ビルド 17763) 以降Windows 10サポートされています。 それに応じて SupportedOSPlatformVersion を設定します。

"SDK 10.0.26100 に対してコンパイルしても、ユーザーが 22H2 (ビルド 22621) Windows 11実行した場合はどうなりますか?

ビルド 22621 から 26100 の間で導入された API はコードに表示されますが、API の可用性チェックを追加しない限り、実行時に失敗します。 22621 以前の API は正常に動作します。

"特定の API を導入したビルド番号を確認するにはどうすればよいですか?

Microsoft Learn の API のリファレンス ページを確認します。 [要件] セクションには、最小 OS ビルド (API コントラクト バージョンまたは Windows バージョン) が一覧表示されます。

ルールの概要

関連するコンテンツ

• Windows アプリ SDKサポートされているWindows リリース
• Windows アプリ SDK リリース ノート
• Windows SDK アーカイブ
• バージョンアダプティブ アプリ
• 開発環境のセットアップ