Windows 버전 및 SDK 개요

Windows 앱을 빌드하기 시작하면 Windows OS 버전, Windows SDK 및 Windows 앱 SDK 등 다양한 버전 번호에 대한 참조를 확인할 수 있습니다. 걱정하지 마세요. 대부분의 새 프로젝트의 경우 Visual Studio 합리적인 기본값을 설정하며 이에 대해 전혀 생각할 필요가 없습니다. 그러나 특정 OS 버전을 대상으로 지정하거나, API를 사용할 수 없는 이유를 이해하거나, 프로젝트 파일을 구성해야 하는 경우 이 문서에서는 조각이 어떻게 결합되는지, 어떤 선택을 해야 하는지 설명합니다.

Definitions

Component 그것이 무엇인지 버전 형식 업데이트 방법
Windows OS 버전 사용자의 디바이스에 설치된 운영 체제입니다. YYHX (예: 24H2, 25H2) Windows 업데이트(연간 기능 업데이트)
Windows SDK(플랫폼 SDK) Win32, WinRT 및 COM API에 대한 헤더, 라이브러리 및 메타데이터입니다. 10.0.BBBBB.x (예: 10.0.26100.0) Visual Studio 또는 독립 실행형 설치 관리자와 함께 설치됨
Windows 앱 SDK WinUI 3, 앱 수명 주기, 창 창 및 기타 최신 앱 기능을 제공하는 NuGet 분산 프레임워크입니다. Major.Minor.Patch (예: 1.8.1) 프로젝트의 NuGet 패키지 업데이트

WINDOWS OS 버전 이름 지정

Windows 11 명명 패턴 YYHX를 사용하여 주요 기능 업데이트를 제공합니다.

  • YY = 두 자리 달력 연도
  • H1 = 올해 상반기; H2 = 올해 하반기

대부분의 주요 릴리스는 지금까지 가을(H2)에 제공되었지만 H1 릴리스도 발생합니다.

Windows 운영 체제 버전 출시 연도 OS 빌드 번호
Windows 11 22H2 2022 22621
Windows 11 23H2 2023 22631
Windows 11 24H2 2024 26100

규칙: 사용자 디바이스의 OS 빌드 번호는 런타임에 사용할 수 있는 플랫폼 API를 결정합니다.

팁

Win + R을 누르고 입력하여 모든 디바이스에서 OS 빌드 번호를 확인합니다winver.

Windows SDK와 OS 버전 매핑

각 Windows SDK 릴리스 제품군은 Windows OS 버전에 해당합니다. SDK의 주요 빌드 번호는 일반적으로 OS 빌드 번호와 일치하지만 일부 OS 기능 업데이트(사용 패키지로 제공)는 이전 릴리스와 동일한 SDK 제품군을 공유합니다.

Windows SDK 제품군 OS 빌드 Windows 버전 일치
10.0.22621.x 22621 Windows 11 22H2/23H2
10.0.26100.x 26100 Windows 11 24H2

메모

SDK 제품군 내에서 마지막 구성 요소(예: 10.0.26100)2454) 버그 수정을 추가하지만 새 API는 추가하지 않는 월별 서비스 업데이트를 나타냅니다.

규칙: 지정된 Windows SDK를 설치하면 해당 OS 버전 및 모든 이전 버전의 모든 API에 대한 컴파일 시간 액세스 권한이 부여됩니다. API는 누적됩니다.

Windows 앱 SDK 버전

Windows 앱 SDK는 Windows OS 및 Windows SDK와 모두 독립적입니다. NuGet 패키지로 자체 릴리스 주기에 따라 배포됩니다.

Windows 앱 SDK 릴리스 날짜 지원되는 최소 OS 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

규칙: 이전 OS 버전에서 최신 Windows 앱 SDK 사용할 수 있습니다(명시된 최소 버전으로 돌아가기). Windows 앱 SDK 버전은 Windows OS 버전 또는 Windows SDK 버전과 일치할 필요가 없습니다.

전체 지원 매트릭스는 지원되는 Windows 릴리스 Windows 앱 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 앱 SDK Windows SDK를 대체하지 않습니다. 둘 다 필요합니다.
  2. Windows SDK 버전은 앱이 실행되는 OS보다 최신 버전일 수 있습니다(최신 API에 대한 런타임 검사 사용).
  3. Windows 앱 SDK 버전은 완전히 독립적입니다. 다른 항목을 변경하지 않고 업데이트합니다.
  4. 사용자의 OS 빌드가 컴파일한 SDK에 관계없이 도입된 빌드보다 오래된 경우 런타임에 플랫폼 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>

메모

SupportedOSPlatformVersion 는 TargetPlatformMinVersion SDK 스타일 프로젝트에서 동일합니다. .NET SDK 플랫폼 호환성 분석기는 최소 OS 버전에서 사용할 수 없는 API를 호출할 때 컴파일 시간 경고를 내보내는 데 사용합니다SupportedOSPlatformVersion.

C++ 프로젝트 파일(.vcxproj)

<PropertyGroup>
    <!-- Note: C++ uses "WindowsTargetPlatform" prefix -->
    <WindowsTargetPlatformVersion>10.0.26100.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17763.0</WindowsTargetPlatformMinVersion>
</PropertyGroup>
속성(C#) Purpose 너무 높게 설정할 경우의 영향 너무 낮게 설정했을 때의 영향
TFM의 Windows 버전(TargetFramework) 컴파일 시 API 범위 플랫폼 분석기 경고 사용(문제가 아닌 이점) 최신 API는 표시되지 않으며, 이를 참조하면 컴파일러 오류가 발생합니다.
SupportedOSPlatformVersion / TargetPlatformMinVersion 설치를 위한 최소 OS 앱을 설치할 수 있는 사용자 수가 줄어듭니다. 최신 API를 호출하기 전에 런타임 검사를 추가해야 합니다.
Microsoft.WindowsAppSDK 버전 WinUI 3 및 프레임워크 기능 N/A(최신 안정화 버전 사용) 누락된 최신 WinUI 컨트롤 또는 프레임워크 기능

의사 결정 가이드: 버전 선택

다음 규칙을 사용하여 새 프로젝트의 버전을 선택합니다.

  1. TFM의 Windows 플랫폼 버전을 안정적인 최신 Windows SDK(예: net8.0-windows10.0.26100.0)로 설정합니다. 이렇게 하면 가장 광범위한 컴파일 시간 API 화면이 제공되고 최소 OS에서 사용할 수 없는 API에 대한 플랫폼 호환성 분석기 경고를 사용할 수 있습니다.
  2. 대상 사용자에 따라 SupportedOSPlatformVersion(또는 TargetPlatformMinVersion)을 설정하세요:
    • 관리되는 디바이스가 있는 엔터프라이즈 앱: 조직의 최소 지원 OS와 일치합니다.
    • 소비자 앱(가장 광범위한 범위): 10.0.19041.0 (2004년 Windows 10) 또는 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 유형에 따라 달라집니다. 일반적인 예외에는 플랫폼별 오류가 포함TypeLoadExceptionMissingMethodException됩니다.

자주 묻는 질문

"어떤 Windows SDK를 사용해야 하나요?"

사용 가능한 최신 Windows SDK를 사용합니다(현재 10.0.26100). 항상 대상 최소값보다 최신 SDK에 대해 컴파일할 수 있으며 컴파일 시간에 표시되는 항목에만 영향을 줍니다.

"Windows 앱 SDK 업데이트할 때 Windows SDK를 업데이트해야 하나요?"

아니요. 그들은 독립적입니다. Windows SDK 버전을 변경하지 않고 1.7에서 1.8로 업데이트 Microsoft.WindowsAppSDK 할 수 있습니다.

"내 앱이 Windows 10 대상으로 합니다. Windows 앱 SDK 사용할 수 있나요?"

Yes. Windows 앱 SDK Windows 10 버전 1809(빌드 17763) 이상을 지원합니다. SupportedOSPlatformVersion 그에 따라 설정하세요.

"SDK 10.0.26100에 대해 컴파일하지만 사용자가 Windows 11 22H2(빌드 22621)를 실행하면 어떻게 되나요?"

빌드 22621과 26100 사이에 도입된 API는 코드에 표시되지만 API 가용성 검사를 추가하지 않으면 런타임에 실패합니다. 22621 이하의 API는 정상적으로 작동합니다.

"특정 API를 도입한 빌드 번호를 어떻게 알 수 있나요?"

Microsoft Learn에서 API의 참조 페이지를 확인합니다. 요구 사항 섹션에는 최소 OS 빌드(API 계약 버전 또는 Windows 버전)가 나열됩니다.

"이러한 SDK가 내 앱과 함께 배포되었나요?"

아니요. 하지만 그중 하나의 일부는 그럴 수 있습니다. Windows SDK는 개발 시간 도구일 뿐입니다. 해당 헤더와 라이브러리는 컴파일러에서 사용되며 앱 패키지에는 아무것도 없습니다. Windows 앱 SDK 다릅니다. 기본적으로 해당 런타임 이진 파일은 앱 패키지에 포함됩니다(배포 모델에 따라 프레임워크 종속 또는 자체 포함). 프레임워크 종속 배포에서는 공유 Windows 앱 SDK 런타임이 디바이스에 한 번 설치되고 앱이 이를 참조합니다. 자체 포함 배포에서는 필요한 이진 파일이 MSIX 또는 출력 폴더에 직접 번들로 제공됩니다. 어느 쪽이든 플랫폼 API(Win32, WinRT, COM)는 항상 OS 자체에서 제공되며, 그런 API를 직접 포함해 배포하는 일은 없습니다. 배포 옵션에 대한 자세한 내용은 Windows 앱 SDK 배포 개요를 참조하세요.

규칙 요약

규칙 Description
OS 버전 = 런타임 지원 기능 사용자의 OS 빌드는 런타임에 실제로 작동하는 API를 결정합니다.
Windows SDK = 컴파일 시간 화면 설치하는 SDK는 코드에 표시되는 API를 결정합니다.
Windows 앱 SDK = 앱 프레임워크 OS 및 플랫폼 SDK 버전과 관계없이 NuGet을 통해 업데이트됩니다.
SDK ≥ OS가 안전합니다. 최소 OS 대상보다 최신 SDK에 대해 컴파일할 수 있습니다.
런타임 검사가 필요합니다. TFM이 보다 SupportedOSPlatformVersion높은 Windows 버전을 대상으로 하는 경우 런타임 검사를 사용하여 최신 API 호출을 보호합니다.
Windows 앱 SDK 하위 호환성 Windows 앱 SDK 릴리스 버전에 관계없이 Windows 10 1809로 다시 지원합니다.

관련 콘텐츠

  • 에 마지막으로 업데이트됨