Programmation avec les kits SDK d’extension

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

  • Famille d’appareils
  • SDK d’extension
  • Contrat API

Nous expliquons également comment les utiliser dans votre programmation.

—Présentation vidéo des familles UWP et des 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 dans une classe d’appareils.

Familles d’appareils

Une famille d’appareils est la base d’un système d’exploitation. Par exemple, les PC et tablettes exécutent une édition Desktop du système d’exploitation, qui est basé 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 par conséquent sur chaque appareil exécutant ce système d’exploitation.

La décision relative à la famille de périphériques ciblée par votre application sera la vôtre. Cette décision a une incidence sur votre application de plusieurs façon. Elle détermine

  • les familles d’appareils auxquels votre application est destinée pour l’installation à partir de la 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
  • ensemble particulier d’API que vous pouvez utiliser sur un appareil exécutant votre application (l’appareil hôte).

En s' appuyant sur la présence, nous entendons que vous pouvez appeler ces API sans avoir préalablement à effectuer un test pour voir si elles sont présentes sur l’appareil hôte. La famille d’appareils que vous ciblez fournit cette garantie (garanties différentes pour différentes familles d’appareils).

Configurer la famille de votre appareil cible

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

  • Windows. Desktop
  • Windows. holographique
  • Windows. IoT
  • Windows. mobile
  • Windows. Team
  • Windows. universel
  • Windows. Xbox

Par défaut, votre application UWP cible la famille d’appareils universelle (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 vous appuyer sur un grand ensemble d’API de l’appareil hôte. Une application telle que a besoin 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 de la Microsoft Store, vous pouvez choisir de cibler une autre famille d’appareils, — par exemple, la famille de périphériques de bureau ( Windows.Desktop ) ou la famille d’appareils IOT ( Windows.IoT ). Bien entendu, il y aura moins d’appareils qui peuvent héberger votre application, mais vous pourrez vous appuyer sur un plus grand nombre d’API présentes sur ces appareils (qui sera le jeu dans la famille d’appareils universels, plus le jeu dans la famille d’appareils cibles). Une application telle que ne doit généralement être adaptative que modérément ; Il peut être quelque peu spécialisé dans son interface utilisateur et ses capacités d’entrée, car il ne peut s’exécuter que sur un type spécifique d’appareil.

Conseil

Mais vous pouvez également avoir le meilleur des deux mondes. Vous pouvez configurer votre application pour qu’elle s’exécute sur tous les appareils Windows 10, ainsi que pour accéder aux fonctionnalités spécialisées de certaines familles d’appareils quand vous trouvez que vous exécutez sur un. Ce scénario idéal pour les deux mondes nécessite un peu de travail supplémentaire et nous allons dans les détails de ce scénario plus loin dans cette rubrique.

Configurer la version de la famille d’appareils cible

Les API sont ajoutées à Windows dans le temps. par conséquent, 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 les versions de votre plateforme cible directement dans le fichier projet.

Voici un exemple qui montre 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 de TargetDeviceFamily@Name Package.appxmanifest ) sont copiées dans le AppxManifest.xml fichier généré dans le 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 ciblée par votre application pour laquelle vous l’avez testée. Et 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 pas AppxManifest.xml , car la génération 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 ( Package.appxmanifest fichier), car ces valeurs sont ignorées.

Extensions SDK d’extension et comment les référencer

Si, dans votre projet Visual Studio, vous remplacez votre cible de la famille d’appareils universelle 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, puis (avec le nœud de projet sélectionné dans Explorateur de solutions), cliquez sur projet > Ajouter une référence... > Windows universel > Extensions, puis sélectionnez la version appropriée des Extensions IOT Windows pour la série 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électionner le SDK d’extension IoT

C’est ainsi que cette référence s’afficherait 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

D’autres kits de développement logiciel (SDK) d’extension incluent les extensions de bureau Windows pour UWP, les extensions Windows Mobile pour la série UWPet les extensions d’équipe Windows pour UWP.

Si vous laissez votre application ciblant la famille de périphériques universels, vous pouvez toujours ajouter une référence à un ou plusieurs kits de développement logiciel (SDK) d’extension. Référencez les autres kits de développement logiciel (SDK) d’extension qui contiennent les API supplémentaires que vous souhaitez appeler. N’oubliez pas que vous ciblez la famille d’appareils universels, c’est pourquoi il s’agit des seules API que vous pouvez utiliser . Pour les API dans le ou les kits de développement logiciel (SDK) d’extension que vous avez référencés, vous devez vérifier qu’ils sont présents sur l’appareil hôte au moment de l’exécution avant de les appeler (plus de détails dans la section écriture de code plus loin dans cette rubrique). Bien entendu, vous n’avez pas besoin d’effectuer ce test pour les API dans la famille d’appareils universelle. Il s’agit du scénario idéal des mondes que nous avons mentionnés 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 si vous ciblez ou non la famille d’appareils correspondante.

Contrats d’API et comment les Rechercher

Les API d’une famille d’appareils sont sous-divisées en groupes appelés contrats d’API. Quand une nouvelle version d’une famille d’appareils est publiée, cette nouvelle version représente simplement 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 universelle. 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 vous pouvez rechercher le nom de contrat d’API et le numéro de version d’une API de 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.

Dans notre premier exemple, nous allons utiliser la méthode StorageFolder. TryGetChangeTracker . Dans la section Configuration requise pour Windows 10 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 .

Nous allons maintenant examiner la rubrique relative à la méthode StorageFolder. TryGetItemAsync . Il n’existe aucune section relative à la Configuration requise pour Windows 10 dans cette rubrique. Au lieu de cela, examinez la rubrique relative à la classe StorageFolder elle-même. La section Configuration requise pour Windows 10 a la réponse. Étant donné que la rubrique StorageFolder. TryGetItemAsync n’est pas différente, nous pouvons conclure qu’elle partage ses spécifications 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 éléments à prendre en considération pour vous aider à déterminer la famille de périphériques à cibler. Pour plus d’informations, consultez TargetDeviceFamily.

Maximisez la portée de votre application

Pour atteindre la plage 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 universelle. Plus précisément, comme nous l’avons vu, vous allez cibler une série de versions de la famille d’appareils universelle.

Limiter votre application à un type d’appareil

Vous ne souhaitez peut-être pas que votre application s’exécute sur un large éventail de facteurs de forme de périphérique. Il est peut-être spécialisé pour un ordinateur 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 de cibler une des familles d’appareils enfants, vous pouvez cibler au lieu de deux familles d’appareils enfants (ou plus). Le ciblage des postes de travail et des appareils mobiles peut être judicieux pour votre application. Ou le bureau et l’équipe. Ou poste de travail, mobile et équipe, etc.

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

Dans de rares cas, vous souhaiterez peut-être 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 dans le futur — disons 10.0. x. 2 — à ce stade, 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 sur 10.0. x. 0 de la console universelle 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

La plupart de votre code sera universel dans le sens où il s’exécutera de la même façon sur chaque appareil. Mais 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 qui est implémentée par votre famille d’appareils cible

Chaque fois que vous souhaitez appeler une API dans une application UWP, vous souhaiterez peut-être savoir si l’API est implémentée par la famille de périphériques ciblée par votre application. Visual Studio IntelliSense affiche les API dans la famille d’appareils universelle, ainsi que les API disponibles pour tous les kits de développement logiciel (s) d’extension que vous avez référencés.

La documentation de référence sur les API Windows Runtime indique la famille de périphériques dont une API fait partie. Si vous recherchez la rubrique de référence d’API pour une API de Windows Runtime et recherchez la section Configuration requise pour Windows 10 , vous verrez ce qu’est la famille d’appareils en cours d’implémentation, ainsi que la version de la famille d’appareils dans laquelle l’API s’affiche pour la première fois. S’il n’existe aucune section relative à la Configuration requise pour Windows 10 , examinez la classe propriétaire du membre et consultez les informations dans la section Configuration requise pour Windows 10 . 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 peut-être appeler une API dans un 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 pouvez cibler la famille de périphériques universels, mais il existe une API de bureau que vous aimeriez 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 uniquement disponible dans les versions les plus récentes de la même famille d’appareils.

Dans les cas de ce type, vous pouvez choisir d’écrire du code adaptatif afin que vous puissiez appeler ces API en toute sécurité. La section suivante vous indique comment procéder.

Écrire du code adaptatif à l’aide de ApiInformation

Il y a deux étapes impliquées dans l’utilisation de code adaptatif pour appeler une API de façon conditionnelle. La première étape consiste à mettre l’API à la disposition de votre projet. Pour ce faire, ajoutez une référence au kit de développement logiciel (SDK) d’extension qui représente la famille de périphériques 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 à chaque fois que votre application s’exécute. Toutefois, elle prend true la valeur uniquement sur les appareils où l’API est présente et peut donc être appelée.

Si vous souhaitez appeler uniquement 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, il y a confiance que 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 de spécifications. Toutefois, dans le temps, de nouveaux membres seront ajoutés aux classes déjà introduites, et ces membres auront été 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 d’API au sein d’une famille d’appareils est divisé 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 condition unique afin d’en savoir plus sur la présence ou sur 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 qui vous intéressent, consultez la section Rechercher le contrat d’API pour une API WinRT plus haut dans cette rubrique.

Une fois que vous disposez de ces informations, vous pouvez les brancher dans votre code adaptatif. Par exemple, si le nom du contrat d’API est Windows.Devices.Scanners.ScannerDeviceContract , et que ses numéros de version majeure et mineure sont 1 et 0, respectivement, votre condition ressemble à 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. Toutefois, même si vous ciblez un seul type de facteur de forme de périphérique, il y aura probablement différentes tailles d’écran sur lesquelles votre application pourrait s’afficher.

Quand vous êtes prêt à voir comment votre application regarde et se présente à une taille particulière de l’écran, 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 TV. De cette façon, si vous avez utilisé les fonctionnalités de disposition adaptative de XAML (voir Didacticiel : créer des dispositions adaptatives), vous pouvez également tester cela.

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

Vous n’avez pas besoin de prendre une 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.

Voir aussi