Programmation avec les kits SDK d’extension

Article
07/20/2023

Afin de comprendre comment Windows 10 permet à votre application plateforme Windows universelle (UWP) de cibler plus efficacement différentes classes d’appareils, cette rubrique explique les concepts suivants.

Famille d’appareils
Kit de développement logiciel (SDK) d
Contrat API

Nous montrons également comment les utiliser dans votre programmation.

Vidéo : Présentation des familles UWP et d’appareils

Familles d’appareils et famille d’appareils cibles de votre application

Une famille d’appareils identifie les API, les caractéristiques système et les comportements que vous pouvez attendre sur les différentes catégories d’appareils.

Familles d’appareils

Une famille d’appareils est la base d’un système d’exploitation . Par exemple, les PC et les tablettes exécutent une édition de bureau du système d’exploitation, basée sur la famille d’appareils de bureau. Les appareils IoT exécutent une édition IoT du système d’exploitation, qui est basée sur la famille d’appareils IoT.

Chaque famille d’appareils enfants ajoute ses propres API aux API qu’elle hérite de la famille d’appareils universelle. L’union d’API résultante dans une famille d’appareils enfants est garantie d’être présente dans un système d’exploitation basé sur cette famille d’appareils, et donc sur chaque appareil exécutant ce système d’exploitation.

La décision concernant la famille d’appareils (ou les familles) que votre application ciblera vous appartient. Cette décision a une incidence sur votre application de plusieurs façon. Il détermine

les familles d’appareils sur lesquels votre application est proposée pour l’installation à partir du Microsoft Store (et, par conséquent, les facteurs de forme que vous devez prendre en compte lorsque vous concevez l’interface utilisateur de votre application), et
l’ensemble particulier d’API sur lequel vous pouvez compter sur la présence sur un appareil exécutant votre application (l’appareil hôte).

En vous appuyant sur la présence, nous voulons dire que vous pouvez appeler ces API sans avoir d’abord besoin de tester pour voir si elles sont présentes sur l’appareil hôte. La famille d’appareils que vous ciblez fournit cette garantie (différentes garanties pour différentes familles d’appareils).

Configurer votre famille d’appareils cibles

Dans le fichier source du manifeste de votre package d’application (le Package.appxmanifest fichier), l’élément TargetDeviceFamily a un attribut Name . La valeur de cet attribut est le nom de la famille d’appareils cible par votre application. Les valeurs suivantes sont valides.

Windows.Desktop
Windows.Holographic
Windows.IoT
Windows.Mobile
Windows.Team
Windows.Universal
Windows.Xbox

Par défaut, votre application UWP cible la famille d’appareils universels (autrement dit, Microsoft Visual Studio spécifie Windows.Universal pour TargetDeviceFamily). Cela signifie que votre application peut être installée sur tous les appareils Windows 10 et que vous pouvez compter sur la présence d’un grand ensemble d’API de base sur l’appareil hôte. Une application comme celle-ci doit disposer d’une interface utilisateur hautement adaptative et de fonctionnalités d’entrée complètes, car elle peut s’exécuter sur un large éventail d’appareils. Consultez Aperçu de votre interface utilisateur sur différentes tailles d’écran plus loin dans cette rubrique.

Si vous souhaitez limiter les familles d’appareils auxquels votre application est proposée pour l’installation à partir du Microsoft Store, vous pouvez choisir de cibler une autre famille d’appareils, par exemple, la famille d’appareils de bureau (Windows.Desktop) ou la famille d’appareils IoT (Windows.IoT). Bien sûr, il y aura moins d’appareils pouvant héberger votre application, mais vous pourrez compter sur un plus grand ensemble d’API présents sur ces appareils (qui seront les ensembles de la famille d’appareils universels, plus l’ensemble dans la famille d’appareils cible). Une application comme celle-ci ne doit généralement être que modérément adaptative ; il peut être quelque peu spécialisé dans ses fonctionnalités d’interface utilisateur et d’entrée, car il ne peut s’exécuter que sur un type spécifique d’appareil.

Conseil

Mais vous pouvez aussi avoir le meilleur des deux mondes. Vous pouvez configurer votre application pour qu’elle s’exécute sur tous les appareils Windows 10, et également accéder aux fonctionnalités spécialisées de certaines familles d’appareils lorsque vous constatez que vous exécutez sur l’un d’eux. Ce scénario best-of-both-worlds nécessite un peu de travail supplémentaire, et nous en reviendrons plus loin dans cette rubrique.

Configurer la version de votre famille d’appareils cibles

Les API étant ajoutées à Windows au fil du temps, une autre dimension pour choisir une famille d’appareils consiste à choisir la ou les versions à cibler. Certains types de projets dans Visual Studio ont une page de propriétés dans laquelle vous pouvez configurer les versions de votre plateforme cible. Toutefois, pour tous les types de projets, vous pouvez configurer vos versions de plateforme cible directement dans le fichier projet.

Voici un exemple montrant les propriétés pertinentes dans un fichier projet.

<!-- MyProject.Xxxproj -->
<PropertyGroup Label="Globals">
    ...
    <WindowsTargetPlatformVersion>10.0.19041.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17134.0</WindowsTargetPlatformMinVersion>
    ...
</PropertyGroup>

Au moment de la génération, ces valeurs (ainsi que la valeur de TargetDeviceFamily@Name de Package.appxmanifest) sont copiées dans le fichier généré dans le AppxManifest.xml dossier de sortie de votre projet. Voici un exemple.

<!-- AppxManifest.xml -->
<Dependencies>
    <TargetDeviceFamily Name="Windows.Universal"
        MaxVersionTested="10.0.19041.0"
        MinVersion="10.0.17134.0" />
    ...
</Dependencies>

MaxVersionTested spécifie la version maximale de la famille d’appareils que votre application cible et que vous avez testée. MinVersion spécifie la version minimale de la famille d’appareils ciblée par votre application. Pour plus d’informations, consultez TargetDeviceFamily.

Important

Vous devez configurer ces numéros de version au moyen des pages de propriétés de votre projet Visual Studio ou des valeurs de WindowsTargetPlatformVersion et WindowsTargetPlatformMinVersion dans votre fichier projet. Ne modifiez AppxManifest.xmlpas , car la build remplace ce fichier. Et ne modifiez pas les attributs MinVersion et MaxVersionTested de l’élément TargetDeviceFamily dans le fichier source du manifeste de votre package d’application (le Package.appxmanifest fichier), car ces valeurs sont ignorées.

Kits de développement logiciel (SDK) d’extension et comment les référencer

Si, dans votre projet Visual Studio, vous remplacez votre cible de la famille d’appareils universels par une autre famille d’appareils, vous devez ajouter une référence au KIT de développement logiciel (SDK) d’extension correspondant à cette famille d’appareils. Cela rend les API de cette famille d’appareils disponibles pour votre projet.

Si, par exemple, vous ciblez la famille d’appareils IoT, alors (avec le nœud de projet sélectionné dans Explorateur de solutions) cliquez surAjouter une référencede projet>...>Windows> universelExtensions, puis sélectionnez la version appropriée des extensions Windows IoT pour UWP. Par exemple, si la dernière API IoT que vous souhaitez appeler a été introduite dans la version 10.0.17134.0, sélectionnez cette version.

Sélectionnez le Kit de développement logiciel (SDK) de l’extension IoT

Et c’est ainsi que cette référence se présenterait dans votre fichier projet.

<ItemGroup>
    <SDKReference Include="WindowsIoT, Version=10.0.17134.0" />
</ItemGroup>

Le nom et le numéro de version correspondent à ceux des dossiers dans l’emplacement d’installation de votre SDK. Par exemple, les informations ci-dessus correspondent au dossier nommé

\Program Files (x86)\Windows Kits\10\Extension SDKs\WindowsIoT\10.0.17134.0

Les autres kits SDK d’extension incluent les extensions de bureau Windows pour UWP, les extensions Windows Mobile pour UWP et les extensions d’équipe Windows pour UWP.

Si vous quittez votre application ciblant la famille d’appareils universels, vous pouvez toujours ajouter une référence à un ou plusieurs kits SDK d’extension. Référencez les SDK d’extension qui contiennent les API supplémentaires que vous souhaitez appeler. N’oubliez pas que vous ciblez la famille d’appareils universels. Il s’agit donc des seules API sur lesquelles vous pouvez compter sur la présence. Pour les API dans les SDK d’extension que vous avez référencés, vous devez vérifier qu’elles sont présentes sur l’appareil hôte au moment de l’exécution avant de les appeler (plus d’informations dans la section Écriture de code plus loin dans cette rubrique). Bien sûr, vous n’avez pas besoin d’effectuer ce test pour les API dans la famille d’appareils universels. Il s’agit du scénario best-of-both-worlds que nous avons mentionné dans la section précédente.

À l’aide d’un KIT de développement logiciel (SDK) d’extension, vous pouvez cibler les API uniques d’une famille spécifique d’appareils et ainsi accéder à leurs fonctionnalités spécialisées. Vous pouvez le faire, que vous ciblez la famille d’appareils correspondante ou non.

Contrats d’API et comment les rechercher

Les API d’une famille d’appareils sont subdivées en groupes appelés contrats d’API. Lorsqu’une nouvelle version d’une famille d’appareils est publiée, cette nouvelle version représente essentiellement la collection de nouvelles versions de tous les contrats d’API qui appartiennent à cette famille d’appareils.

Par exemple, le contrat d’API nommé Windows.Foundation.UniversalApiContract était à la version 6.0 lorsqu’il était fourni avec la version 10.0.17134.0 de la famille d’appareils universels. Mais ce même contrat était à la version 10.0 lorsqu’il était fourni avec la version 10.0.19041.0 de cette même famille d’appareils.

Rechercher le contrat d’API pour une API WinRT

Voyons comment rechercher le nom du contrat d’API et le numéro de version pour une API Windows Runtime donnée. Dans la section Écriture de code plus loin dans cette rubrique, vous verrez pourquoi et comment vous pouvez utiliser ces informations.

Comme premier exemple, nous allons utiliser la méthode StorageFolder.TryGetChangeTracker . Dans la section Windows 10 exigences de cette rubrique, nous pouvons voir que StorageFolder.TryGetChangeTracker a été introduit pour la première fois avec la version 6.0 de Windows.Foundation.UniversalApiContract.

Examinons ensuite la rubrique relative à la méthode StorageFolder.TryGetItemAsync . Il n’existe aucune section Windows 10 exigences dans cette rubrique. Au lieu de cela, examinez la rubrique pour la classe StorageFolder elle-même. La section exigences Windows 10 a la réponse. Étant donné que la rubrique StorageFolder.TryGetItemAsync ne dit pas autre chose, nous pouvons conclure qu’elle partage ses exigences avec sa classe parente. StorageFolder.TryGetItemAsync a été introduit pour la première fois avec la version 1.0 de Windows.Foundation.UniversalApiContract.

Comment choisir une famille d’appareils à cibler

Voici quelques considérations pour vous aider à choisir la famille d’appareils à cibler. Pour plus d’informations, consultez TargetDeviceFamily.

Optimiser la portée de votre application

Pour atteindre la gamme maximale de types d’appareils avec votre application et, par conséquent, pour qu’elle s’exécute sur autant d’appareils que possible, votre application doit cibler la famille d’appareils universels. Plus précisément, comme nous l’avons vu, vous allez cibler une gamme de versions de la famille d’appareils universels.

Limiter votre application à un seul type d’appareil

Vous ne souhaiterez peut-être pas que votre application s’exécute sur un large éventail de facteurs de forme d’appareil ; il est peut-être spécialisé pour un PC de bureau ou pour une console Xbox. Dans ce cas, vous pouvez choisir de cibler l’une des familles d’appareils enfants.

Limiter votre application à un sous-ensemble de tous les appareils possibles

Au lieu de cibler la famille d’appareils universelle ou l’une des familles d’appareils enfants, vous pouvez cibler deux (ou plusieurs) familles d’appareils enfants. Le ciblage de Desktop et Mobile peut être judicieux pour votre application. Ou Desktop et Team. Ou Desktop, Mobile et Team, et ainsi de suite.

Exclure la prise en charge d’une version particulière d’une famille d’appareils

Dans de rares cas, vous pouvez souhaiter que votre application s’exécute partout, sauf sur les appareils avec une version particulière d’une famille d’appareils particulière. Par exemple, supposons que votre application cible la version 10.0.x.0 de la famille d’appareils universelle. Lorsque la version du système d’exploitation change à l’avenir (par exemple, 10.0.x.2), vous pouvez spécifier que votre application s’exécute partout, à l’exception de la version 10.0.x.1 de Xbox, en ciblant votre application vers 10.0.x.0 de Universal et 10.0.x.2 de Xbox. Votre application sera alors inaccessible pour l’ensemble des versions de la famille d’appareils Xbox 10.0.x.1 (inclus) et pour les versions antérieures.

L’écriture du code

Une grande partie de votre code sera universelle dans la mesure où il s’exécutera de la même façon sur chaque appareil. Toutefois, pour le code adapté à une famille d’appareils particulière, vous avez la possibilité d’utiliser du code adaptatif. Examinons ces différents cas.

Appeler une API implémentée par votre famille d’appareils cible

Chaque fois que vous souhaitez appeler une API dans une application UWP, vous devez savoir si l’API est implémentée ou non par la famille d’appareils ciblée par votre application. Visual Studio IntelliSense affiche les API de la famille d’appareils universels, ainsi que les API disponibles pour tous les SDK d’extension que vous avez référencés.

La documentation de référence sur l’API Windows Runtime vous indique la famille d’appareils dont une API fait partie. Si vous recherchez une API Windows Runtime dans la rubrique de référence de l’API et que vous recherchez la section Exigences Windows 10, vous verrez la famille d’appareils d’implémentation et la version de cette famille d’appareils dans laquelle l’API apparaît en premier. S’il n’existe pas de section exigences Windows 10, examinez la classe propriétaire du membre et consultez les informations dans la section Windows 10 exigences. Ces informations s’appliquent également au membre.

Appeler une API qui n’est pas implémentée par votre famille d’appareils cible

Dans certains cas, vous souhaiterez appeler une API dans un KIT de développement logiciel (SDK) d’extension que vous avez référencé, mais cette API ne fait pas partie de la famille d’appareils que vous ciblez.

Par exemple, vous ciblez peut-être la famille d’appareils universels, mais il existe une API de bureau que vous souhaitez appeler chaque fois que votre application s’exécute sur un appareil de bureau.

Ou votre application peut prendre en charge les versions antérieures d’une famille d’appareils, mais il existe une API que vous souhaitez appeler qui est disponible uniquement dans les versions très récentes de la même famille d’appareils.

Dans de tels cas, vous pouvez choisir d’écrire du code adaptatif afin de pouvoir appeler ces API en toute sécurité. La section suivante vous montre comment procéder.

Écrire du code adaptatif à l’aide d’ApiInformation

L’utilisation du code adaptatif pour appeler une API de manière conditionnelle implique deux étapes. La première étape consiste à rendre l’API disponible pour votre projet. Pour ce faire, ajoutez une référence au Kit de développement logiciel (SDK) d’extension qui représente la famille d’appareils propriétaire de l’API.

La deuxième étape consiste à utiliser la classe ApiInformation dans une condition de votre code pour tester la présence de l’API que vous souhaitez appeler. Cette condition est évaluée où et à chaque fois que votre application s’exécute. Mais elle s’évalue uniquement true sur les appareils où l’API est présente et donc disponible pour l’appel.

Si vous souhaitez appeler un petit nombre d’API, vous pouvez utiliser la méthode ApiInformation.IsTypePresent comme suit.

// Cache the value, instead of querying it multiple times.
bool isHardwareButtonsAPIPresent =
    Windows.Foundation.Metadata.ApiInformation.IsTypePresent("Windows.Phone.UI.Input.HardwareButtons");

if (isHardwareButtonsAPIPresent)
{
    Windows.Phone.UI.Input.HardwareButtons.CameraPressed += HardwareButtons_CameraPressed;
}

Dans ce cas, la présence de la classe HardwareButtons implique la présence de l’événement CameraPressed , car la classe et le membre ont les mêmes informations requises. Mais avec le temps, de nouveaux membres seront ajoutés aux classes déjà introduites, et ces membres auront introduits ultérieurement dans les numéros de version. Dans ce cas, au lieu d’utiliser IsTypePresent, vous pouvez tester la présence de membres individuels à l’aide des méthodes IsEventPresent, IsMethodPresent, IsPropertyPresent et d’autres méthodes similaires. Voici un exemple.

bool isHardwareButtons_CameraPressedAPIPresent =
    Windows.Foundation.Metadata.ApiInformation.IsEventPresent
        ("Windows.Phone.UI.Input.HardwareButtons", "CameraPressed");

Comme nous le savons, l’ensemble des API au sein d’une famille d’appareils est encore décomposé en sous-divisions appelées contrats d’API. La méthode ApiInformation.IsApiContractPresent permet de tester la présence d’un contrat API. Il s’agit d’un moyen efficace d’exécuter une seule condition afin de connaître la présence ou non d’un grand nombre d’API qui appartiennent toutes à la même version d’un contrat d’API.

Pour plus d’informations sur la façon de déterminer le contrat d’API qui a introduit la ou les API intéressantes, consultez la section Rechercher le contrat d’API pour une API WinRT plus haut dans cette rubrique.

Une fois que vous avez ces informations, vous pouvez les connecter à votre code adaptatif. Par exemple, si le nom du contrat d’API est Windows.Devices.Scanners.ScannerDeviceContract, et que ses numéros de version principale et secondaire sont 1 et 0, respectivement, votre condition ressemblera à l’exemple ci-dessous.

bool isWindows_Devices_Scanners_ScannerDeviceContract_1_0Present =
    Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent
        ("Windows.Devices.Scanners.ScannerDeviceContract", 1, 0);

Afficher un aperçu de votre interface utilisateur sur différentes tailles d’écran

Nous vous recommandons d’optimiser la portée de votre application. Mais même si vous ne ciblez qu’un seul type de facteur de forme d’appareil, il y aura probablement des tailles d’écran différentes sur lesquelles votre application peut finir par s’afficher.

Lorsque vous êtes prêt à voir l’apparence et la disposition de votre application sur une taille d’écran particulière, utilisez la barre d’outils d’aperçu de l’appareil dans Visual Studio pour afficher un aperçu de votre interface utilisateur sur un appareil mobile de petite ou moyenne taille, sur un PC ou sur un grand écran de télévision. De cette façon, si vous avez utilisé les fonctionnalités de disposition adaptative de XAML (voir Dispositions adaptatives avec des états visuels et des déclencheurs d’état), vous pouvez également tester cela.

Barre d’outils de prévisualisation d’appareil de Visual Studio 2015

Vous n’avez pas à prendre de décision à l’avance sur chaque type d’appareil que vous allez prendre en charge. Vous pouvez ajouter une taille d’appareil supplémentaire à votre projet à tout moment.

Partager via