Přehled verzí Windows a sady SDK

Když začnete vytvářet Windows aplikace, uvidíte odkazy na několik různých čísel verzí – Windows verze operačního systému, Windows SDK a Windows App SDK. Nemějte obavy: u většiny nových projektů Visual Studio nastaví rozumné výchozí hodnoty a nebudete o tom vůbec muset přemýšlet. Pokud ale potřebujete cílit na konkrétní verzi operačního systému, zjistěte, proč rozhraní API není k dispozici, nebo nakonfigurujte soubor projektu, tento článek vysvětluje, jak jednotlivé části odpovídají a jaké volby se mají provést.

Definitions

pojmenování verze operačního systému Windows

Windows 11 dodává hlavní aktualizace funkcí pomocí vzoru pojmenování YYHX:

• YY = dvouciferný kalendářní rok
• H1 = první polovina roku; H2 = druhá polovina roku

Většina hlavních verzí byla historicky dodána na podzim (H2), ale dochází také k vydání H1.

Pravidlo: Číslo buildu operačního systému na zařízení uživatele určuje, která rozhraní API platformy jsou k dispozici za běhu.

Mapování verzí sady Windows SDK na verze systému Windows

Každá řada verzí sady Windows SDK odpovídá Windows verzi operačního systému. Hlavní číslo sestavení sady SDK obvykle odpovídá číslu buildu operačního systému, i když některé aktualizace funkcí operačního systému (doručované jako balíčky povolení) sdílejí stejnou řadu sad SDK jako předchozí verze.

Pravidlo: Instalace dané sady Windows SDK uděluje přístup kompilátoru ke všem rozhraním API z této verze operačního systému a všem předchozím verzím. API se vrství.

Windows App SDK verze

Windows App SDK je nezávislý na operačním systému Windows i sadě Windows SDK. Vydává se samostatně jako balíček NuGet.

Pravidlo: Nejnovější Windows App SDK můžete použít ve starších verzích operačního systému (zpět na uvedené minimum). Verze Windows App SDK nemusí odpovídat verzi Windows operačního systému nebo Windows SDK.

Úplnou matici podpory najdete v Windows App SDK podporovaných verzích Windows.

Jak tyto tři komponenty souvisejí

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

Klíčové relace:

1. Windows App SDK nenahrazuje sadu Windows SDK – potřebujete obojí.
2. Verze sady Windows SDK může být novější než operační systém, na kterém běží vaše aplikace (použijte kontroly za běhu pro novější rozhraní API).
3. Verze Windows App SDK je zcela nezávislá – aktualizujte ji beze změny čehokoli jiného.
4. Rozhraní API platformy nelze volat za běhu, pokud je sestavení operačního systému uživatele starší než sestavení, ve kterém bylo toto API zavedeno, bez ohledu na to, proti které sadě SDK jste aplikaci zkompilovali.

Konfigurace souboru projektu

Vlastnosti NÁSTROJE MSBuild v cílení na platformu řízení souborů projektu Názvy vlastností se mírně liší mezi C# a C++:

Soubor projektu C# (.csproj)

V projektech .NET ve stylu sady SDK (používané šablony WinUI 3 a Windows App SDK) se verze platformy Windows vloží do monikeru cílové architektury (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>

Soubor projektu C++ (.vcxproj)

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

Průvodce rozhodováním: volba verzí

K výběru verzí pro nový projekt použijte následující pravidla:

1. Nastavte verzi Windows platformy v TFM na nejnovější stabilní Windows SDK (napřnet8.0-windows10.0.26100.0. ). Tím získáte nejširší rozsah rozhraní API dostupný při kompilaci a povolíte varování analyzátoru kompatibility platformy pro rozhraní API, která nejsou k dispozici v minimální podporované verzi operačního systému.
2. Nastavte SupportedOSPlatformVersion (nebo TargetPlatformMinVersion) na základě cílové skupiny:
   • Podnikové aplikace se spravovanými zařízeními: odpovídají minimálnímu podporovanému operačnímu systému vaší organizace.
   • Spotřebitelské aplikace (nejširší dosah): 10.0.19041.0 (Windows 10 2004) nebo 10.0.17763.0 (Windows 10 1809).
   • Aplikace využívající funkce z konkrétní verze operačního systému: nastavte na číslo buildu této verze.
3. Vždy používejte nejnovější stabilní Windows App SDK. Neexistuje žádná sankce za kompatibilitu; podporuje zpět na Windows 10 1809.
4. Nikdy nepoužívejte verze Preview/experimentální sady SDK v produkčním prostředí.

Kontroly dostupnosti rozhraní API za běhu

Pokud je verze Windows platformy v TFM vyšší než SupportedOSPlatformVersion, některá rozhraní API viditelná v době kompilace nemusí na zařízení uživatele existovat. Analyzátor kompatibility platformy .NET vás upozorní na tyto informace v době kompilace, ale před jejich voláním musíte také zkontrolovat dostupnost za běhu.

Vzor: Kontrola kontraktu rozhraní API (rozhraní 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
}

Vzorec: Zkontrolovat konkrétní typ

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

Model: Kontrola konkrétní metody

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

Pravidlo: Pokud tyto kontroly přeskočíte a zavoláte nedostupné rozhraní API, aplikace selže za běhu. Přesné selhání závisí na typu rozhraní API – mezi běžné výjimky patří TypeLoadException, MissingMethodExceptionnebo chyba specifická pro platformu.

Časté dotazy

Jakou sadu WINDOWS SDK mám použít?

Použijte nejnovější dostupnou sadu WINDOWS SDK (aktuálně 10.0.26100). Vždy můžete zkompilovat s novější sadou SDK, než je vaše cílové minimum – ovlivňuje jenom to, co je viditelné v době kompilace.

Potřebuji aktualizovat sadu Windows SDK, když aktualizuji Windows App SDK?

No. Jsou nezávislé. Můžete aktualizovat Microsoft.WindowsAppSDK z verze 1.7 na 1.8 beze změny verze sady Windows SDK.

Moje aplikace cílí na Windows 10. Můžu použít Windows App SDK?"

Yes. Windows App SDK podporuje Windows 10 verze 1809 (build 17763) a novější. SupportedOSPlatformVersion Nastavte ho odpovídajícím způsobem.

Co se stane, když zkompiluji aplikaci pro SDK 10.0.26100, ale uživatel používá Windows 11 22H2 (sestavení 22621)?

Rozhraní API zavedená mezi buildem 22621 a 26100 budou ve vašem kódu viditelná, ale za běhu selžou, pokud nepřidáte kontroly dostupnosti rozhraní API. Rozhraní API z verze 22621 a starší budou normálně fungovat.

Jak poznám, které číslo buildu zavedlo konkrétní rozhraní API?

Podívejte se na referenční stránku rozhraní API na Microsoft Learn. V části Požadavky je uveden minimální build operačního systému (jako verze kontraktu rozhraní API nebo verze Windows).

Souhrn pravidel

Související obsah

• Windows App SDK podporované verze Windows
• Poznámky k verzi Windows App SDK
• Archiv Windows SDK
• Aplikace adaptivní podle verze
• Nastavení vývojového prostředí