Windows wersje i zestaw SDK — omówienie

Podczas tworzenia aplikacji Windows zauważysz odwołania do kilku różnych numerów wersji — wersji systemu operacyjnego Windows, zestawu SDK Windows i Zestaw SDK do aplikacji systemu Windows. Nie martw się: w przypadku większości nowych projektów Visual Studio ustawia rozsądne wartości domyślne i w ogóle nie trzeba o tym myśleć. Jeśli jednak musisz określić określoną wersję systemu operacyjnego, zrozumieć, dlaczego interfejs API nie jest dostępny lub skonfigurować plik projektu, w tym artykule wyjaśniono, jak elementy pasują do siebie i jakie opcje należy wybrać.

Definitions

Nazewnictwo wersji systemu operacyjnego Windows

Windows 11 dostarcza główne aktualizacje funkcji przy użyciu wzorca nazewnictwa YYHX:

• YYY = dwucyfrowy rok kalendarzowy
• H1 = pierwsza połowa roku; H2 = druga połowa roku

Większość głównych wydań została historycznie dostarczona jesienią (H2), ale występują również wersje H1.

Zasada: Numer kompilacji systemu na urządzeniu użytkownika określa, które interfejsy API platformy są dostępne w czasie działania.

mapowanie wersji zestawu SDK Windows na system operacyjny

Każda rodzina wersji zestawu SDK Windows odpowiada wersji systemu operacyjnego Windows. Główny numer kompilacji zestawu SDK jest zwykle zgodny z numerem kompilacji systemu operacyjnego, choć niektóre aktualizacje funkcji systemu operacyjnego (dostarczane jako pakiety włączania) współużytkują tę samą rodzinę zestawów SDK co poprzednia wersja.

Reguły: Zainstalowanie danego zestawu SDK Windows zapewnia dostęp w czasie kompilacji do wszystkich interfejsów API z tej wersji systemu operacyjnego i wszystkich wcześniejszych wersji. Interfejsy API mają charakter kumulatywny.

Wersje zestawu SDK aplikacji systemu Windows

Zestaw SDK do aplikacji systemu Windows jest niezależny zarówno od systemu operacyjnego Windows, jak i zestawu WINDOWS SDK. Jest wydawany we własnym cyklu jako pakiet NuGet.

Reguły: Najnowsze Zestaw SDK do aplikacji systemu Windows można używać w starszych wersjach systemu operacyjnego (z powrotem do określonego minimum). Wersja Zestaw SDK do aplikacji systemu Windows nie musi być zgodna z wersją systemu operacyjnego Windows lub wersją zestawu WINDOWS SDK.

Aby uzyskać pełną macierz zgodności, zobacz Obsługiwane wersje systemu Windows dla pakietu Zestaw SDK do aplikacji systemu Windows.

Jak odnoszą się trzy składniki

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

Kluczowe relacje:

1. Zestaw SDK do aplikacji systemu Windows nie zastępuje zestawu SDK Windows — potrzebne są oba te elementy.
2. Wersja zestawu SDK Windows może być nowsza niż system operacyjny uruchamiany przez aplikację (użyj testów środowiska uruchomieniowego dla nowszych interfejsów API).
3. Wersja Zestaw SDK do aplikacji systemu Windows jest całkowicie niezależna — zaktualizuj ją bez zmiany niczego innego.
4. Nie można wywołać interfejsu API platformy w czasie wykonywania, jeśli kompilacja systemu użytkownika jest starsza niż kompilacja, w której ten interfejs API został wprowadzony, niezależnie od tego, względem którego zestawu SDK skompilowano aplikację.

Konfiguracja pliku projektu

Właściwości MSBuild w pliku projektu sterują wyborem platformy docelowej. Nazwy właściwości różnią się nieco między językami C# i C++:

Plik projektu C# (csproj)

W projektach .NET w stylu zestawu SDK (używanych przez szablony WinUI 3 i Zestaw SDK do aplikacji systemu Windows) wersja platformy Windows jest osadzona w programie Target Framework Moniker (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>

Plik projektu C++ (.vcxproj)

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

Przewodnik po decyzjach: wybieranie wersji

Użyj następujących reguł, aby wybrać wersje nowego projektu:

1. Ustaw wersję platformy Windows w programie TFM na najnowszą stabilną Windows SDK (np. net8.0-windows10.0.26100.0). Zapewnia to najszerszą powierzchnię interfejsu API w czasie kompilacji i umożliwia wyświetlanie ostrzeżeń analizatora zgodności platformy dla interfejsów API niedostępnych w minimalnym systemie operacyjnym.
2. Ustaw SupportedOSPlatformVersion (lub TargetPlatformMinVersion) w zależności od odbiorców:
   • Aplikacje dla przedsiębiorstw z urządzeniami zarządzanymi: są zgodne z minimalnym obsługiwanym systemem operacyjnym organizacji.
   • Aplikacje konsumenckie (najszerszy zasięg): 10.0.19041.0 (Windows 10 2004) lub 10.0.17763.0 (Windows 10 1809).
   • Aplikacje korzystające z funkcji z określonej wersji systemu operacyjnego: ustaw na numer kompilacji tej wersji.
3. Zawsze używaj najnowszej stabilnej Zestaw SDK do aplikacji systemu Windows. Nie ma żadnych negatywnych skutków dla zgodności; obsługuje system Windows 10 od wersji 1809.
4. Nigdy nie używaj wersji zapoznawczych/eksperymentalnych zestawów SDK w środowisku produkcyjnym.

Sprawdzanie dostępności API środowiska uruchomieniowego

Jeśli wersja platformy Windows w programie TFM jest wyższa niż SupportedOSPlatformVersion, niektóre interfejsy API widoczne w czasie kompilacji mogą nie istnieć na urządzeniu użytkownika. Analizator zgodności platformy .NET ostrzega o nich podczas kompilacji, ale przed ich wywołaniem należy również sprawdzić dostępność w czasie wykonywania.

Wzorzec: Sprawdź kontrakt API (kontrakty API WinRT)

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
}

Wzorzec: Sprawdź określony typ

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

Wzorzec: Sprawdzanie określonej metody

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

Reguła: Jeśli pominiesz te kontrole i wywołasz niedostępny interfejs API, aplikacja zakończy się niepowodzeniem w czasie wykonywania. Dokładna awaria zależy od typu interfejsu API — typowe wyjątki to TypeLoadException, MissingMethodExceptionlub błąd specyficzny dla platformy.

Często zadawane pytania

"Którego zestawu SDK Windows używać?"

Użyj najnowszego dostępnego zestawu SDK Windows (obecnie 10.0.26100). Zawsze można kompilować z użyciem nowszego SDK niż minimalna wersja docelowa — wpływa to tylko na to, co jest dostępne podczas kompilacji.

"Czy muszę zaktualizować zestaw SDK Windows podczas aktualizowania Zestaw SDK do aplikacji systemu Windows?"

No. Są niezależne. Możesz zaktualizować Microsoft.WindowsAppSDK z wersji 1.7 do 1.8 bez zmiany wersji zestawu WINDOWS SDK.

"Moja aplikacja jest przeznaczona Windows 10. Czy mogę użyć Zestaw SDK do aplikacji systemu Windows?"

Yes. Zestaw SDK do aplikacji systemu Windows obsługuje Windows 10 w wersji 1809 (kompilacja 17763) i nowsze. Ustaw odpowiednio SupportedOSPlatformVersion.

Co się stanie, jeśli skompiluję przy użyciu zestawu SDK 10.0.26100, ale użytkownik uruchomi Windows 11 22H2 (kompilacja 22621)?

Interfejsy API wprowadzone między kompilacją 22621 i 26100 będą widoczne w kodzie, ale nie będą działać w czasie wykonywania, chyba że dodano kontrole dostępności interfejsu API. Interfejsy API z wersji 22621 i starszych będą działać normalnie.

"Jak sprawdzić, który numer kompilacji wprowadził określony interfejs API?"

Sprawdź stronę referencyjną interfejsu API w witrynie Microsoft Learn. Sekcja Wymagania zawiera minimalną kompilację systemu operacyjnego (jako wersję kontraktu interfejsu API lub wersję Windows).

Podsumowanie reguł

Treści powiązane

• Obsługiwane przez Zestaw SDK do aplikacji systemu Windows wersje Windows
• Informacje o wydaniu Zestaw SDK do aplikacji systemu Windows
• Archiwum zestawu SDK Windows
• Aplikacje dostosowujące się do wersji
• Konfigurowanie środowiska projektowego