Vue d’ensemble des versions et sdk Windows

Lorsque vous commencez à créer des applications Windows, vous remarquerez des références à plusieurs numéros de version différents : la version du système d'exploitation Windows, le sdk Windows et le SDK d'application Windows. Ne vous inquiétez pas : pour la plupart des nouveaux projets, Visual Studio définit des valeurs par défaut sensibles et vous n'aurez pas besoin de réfléchir à cela du tout. Toutefois, quand vous devez cibler une version spécifique du système d’exploitation, comprendre pourquoi une API n’est pas disponible ou configurer votre fichier projet, cet article explique comment les éléments s’adaptent ensemble et quels choix faire.

Definitions

nommage de version du système d’exploitation Windows

Windows 11 est livré avec des mises à jour de fonctionnalités majeures selon le modèle de dénomination YYHX :

• AAAA = année civile à deux chiffres
• H1 = première moitié de l’année ; H2 = deuxième moitié de l’année

La plupart des versions majeures ont historiquement été livrées à l’automne (H2), mais les versions H1 se produisent également.

Règle: Le numéro de build du système d’exploitation sur l’appareil de l’utilisateur détermine les API de plateforme disponibles au moment de l’exécution.

Correspondance entre le SDK Windows et les versions du système d’exploitation

Chaque famille de versions du KIT de développement logiciel (SDK) Windows correspond à une version Windows du système d’exploitation. Le numéro de build principal du SDK correspond généralement au numéro de build du système d’exploitation, bien que certaines mises à jour de fonctionnalités du système d’exploitation (fournies en tant que packages d’activation) partagent la même famille de SDK qu’une version antérieure.

Règle: L’installation d’un Windows SDK donné accorde un accès au temps de compilation à toutes les API à partir de cette version du système d’exploitation et de toutes les versions antérieures. Les API sont cumulatives.

versions de SDK d'application Windows

Le SDK d'application Windows est indépendant du système d’exploitation Windows et du SDK Windows. Il est publié selon son propre rythme sous forme de package NuGet.

Règle : Vous pouvez utiliser la dernière SDK d'application Windows sur les versions antérieures du système d’exploitation (retour à son minimum indiqué). La version SDK d'application Windows n’a pas besoin de correspondre à la version du système d’exploitation Windows ou Windows version du SDK.

Pour obtenir la matrice complète de prise en charge, consultez Versions de Windows prises en charge par SDK d'application Windows.

Relation entre les trois composants

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

Relations clés :

1. SDK d'application Windows ne remplace pas le SDK Windows. Vous avez besoin des deux.
2. La version Windows SDK peut être plus récente que le système d’exploitation sur lequel votre application s’exécute (utilisez des vérifications d’exécution pour les API plus récentes).
3. La version SDK d'application Windows est complètement indépendante : mettez-la à jour sans changer d’autre chose.
4. Vous ne pouvez pas appeler une API de plateforme au moment de l’exécution si la build du système d’exploitation de l’utilisateur est antérieure à la build qui l’a introduite, quel que soit le SDK sur lequel vous avez compilé.

Configuration du fichier projet

Les propriétés MSBuild de votre fichier projet contrôlent le ciblage de la plateforme. Les noms de propriétés diffèrent légèrement entre C# et C++ :

Fichier projet C# (.csproj)

Dans les projets de .NET de style SDK (utilisés par les modèles WinUI 3 et SDK d'application Windows), la version de la plateforme Windows est incorporée dans le TFM (Target Framework Moniker) :

<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>

Fichier projet C++ (.vcxproj)

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

Guide de décision : choix des versions

Utilisez les règles suivantes pour sélectionner des versions pour un nouveau projet :

1. Définissez la version de la plateforme Windows dans votre module TFM sur le kit SDK Windows stable le plus récent (par exemple). net8.0-windows10.0.26100.0 Cela vous donne la plus grande surface d’API au moment de la compilation et active les avertissements de l’analyseur de compatibilité de plateforme pour les API indisponibles sur votre système d’exploitation minimal.
2. Définissez SupportedOSPlatformVersion (ou TargetPlatformMinVersion) en fonction de votre audience :
   • Applications d’entreprise avec appareils gérés : correspondent au système d’exploitation minimum pris en charge par votre organisation.
   • Applications grand public (portée la plus large) : 10.0.19041.0 (Windows 10 2004) ou 10.0.17763.0 (Windows 10 1809).
   • Applications utilisant des fonctionnalités d’une version de système d’exploitation spécifique : définissez le numéro de build de cette version.
3. Utilisez toujours la dernière SDK d'application Windows stable. Il n’existe aucune pénalité de compatibilité ; prend en charge Windows 10 1809.
4. N’utilisez jamais les versions préliminaires/expérimentales du Kit de développement logiciel (SDK) en production.

Vérifications de disponibilité de l’API runtime

Lorsque la version de la plateforme Windows dans votre TFM est supérieure SupportedOSPlatformVersionà , certaines API visibles au moment de la compilation peuvent ne pas exister sur l'appareil de l'utilisateur. L’analyseur de compatibilité de plateforme .NET vous avertit de ces informations au moment de la compilation, mais vous devez également vérifier la disponibilité au moment de l’exécution avant de les appeler.

Modèle : Vérifier le contrat d’API (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
}

Modèle : Rechercher un type spécifique

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

Modèle : Rechercher une méthode spécifique

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

Règle: Si vous ignorez ces vérifications et appelez une API indisponible, l’application échoue au moment de l’exécution. L’échec exact dépend du type d’API : les exceptions courantes incluent TypeLoadException, MissingMethodExceptionou une erreur spécifique à la plateforme.

Questions courantes

« Quel Windows SDK dois-je utiliser ? »

Utilisez le dernier Windows SDK disponible (actuellement 10.0.26100). Vous pouvez toujours compiler sur un kit SDK plus récent que votre minimum cible, ce qui affecte uniquement ce qui est visible au moment de la compilation.

« Dois-je mettre à jour le Kit de développement logiciel (SDK) Windows lorsque je mets à jour le SDK d'application Windows ? »

Non. Ils sont indépendants. Vous pouvez effectuer une mise à jour Microsoft.WindowsAppSDK de la version 1.7 vers la version 1.8 sans modifier votre version du Kit de développement logiciel (SDK) Windows.

« Mon application cible Windows 10. Puis-je utiliser le SDK d'application Windows ?

Yes. Le SDK d'application Windows prend en charge Windows 10 version 1809 (build 17763) et versions ultérieures. Définissez votre SupportedOSPlatformVersion valeur en conséquence.

« Que se passe-t-il si je compile sur sdk 10.0.26100, mais que l’utilisateur exécute Windows 11 22H2 (build 22621) ? »

Les API introduites entre la build 22621 et 26100 sont visibles dans votre code, mais échouent au moment de l’exécution, sauf si vous ajoutez des vérifications de disponibilité d’API. Les API de 22621 et antérieures fonctionnent normalement.

« Comment savoir quel numéro de build a introduit une API spécifique ? »

Consultez la page de référence de l'API sur Microsoft Learn. La section Configuration requise répertorie la build minimale du système d’exploitation (en tant que version de contrat d’API ou version Windows).

Résumé des règles

Contenu connexe

• Versions Windows supportées par le SDK d'application Windows
• notes de publication SDK d'application Windows
• Archive du SDK Windows
• Applications qui s’adaptent à la version
• Configurer votre environnement de développement