Programmation avec les kits SDK d’extension

Pour 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 d’appareils et UWP

 

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 tablettes exécutent une édition de bureau du système d’exploitation, qui est 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 universelles. L’union résultante des API 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 cible est la vôtre. Cette décision a une incidence sur votre application de plusieurs façon. Il détermine

  • les familles d’appareils auxquels 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 que vous pouvez utiliser pour être présent sur un appareil exécutant votre application (l’appareil hôte).

En s’appuyant sur être présent, nous voulons dire que vous pouvez appeler ces API sans avoir d’abord besoin de tester s’ils sont présents 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 du 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 que votre application cible. 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 universelles (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 présentes sur l’appareil hôte. Une application comme celle-ci doit avoir une interface utilisateur hautement adaptative et des fonctionnalités d’entrée complètes, car elle peut s’exécuter sur un large éventail d’appareils. Consultez Afficher un 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 qui peuvent héberger votre application, mais vous serez en mesure de vous appuyer sur un plus grand ensemble d’API présentes sur ces appareils (qui sera le jeu dans la famille d’appareils universelle, ainsi que l’ensemble dans la famille d’appareils cible). Une application comme celle-ci doit généralement être uniquement adaptative modérément ; elle peut être un peu spécialisée dans ses fonctionnalités d’interface utilisateur et d’entrée, car elle 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 êtes en cours d’exécution sur un. Ce scénario best-of-both-worlds nécessite un peu de travail supplémentaire, et nous allons entrer dans les spécificités de cela plus loin dans cette rubrique.

Configurer la version de votre famille d’appareils cibles

Les API sont ajoutées à Windows au fil du temps. Par conséquent, une autre dimension pour choisir une famille d’appareils décide de la version (ou des versions) à cibler. Certains types de projets dans Visual Studio ont une page de propriétés dans laquelle vous pouvez configurer vos versions de plateforme cible. Toutefois, pour tous les types de projet, 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 sur laquelle votre application cible que vous 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 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 du 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 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 Project>Add Reference...>Windows> universel Extensions, 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électionner le Kit de développement logiciel (SDK) d’extension IoT

Et c’est ainsi que cette référence ressemblerait 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 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 laissez votre application ciblant la famille d’appareils universels, vous pouvez toujours ajouter une référence à un ou plusieurs kits SDK d’extension. Les kits SDK d’extension de référence 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 que vous pouvez compter sur être présentes. Pour les API du ou des SDK d’extension référencés, vous devez tester 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 meilleur scénario des deux mondes que nous avons mentionné dans la section précédente.

En utilisant 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 la famille d’appareils correspondante ou non.

Contrats d’API et comment les rechercher

Les API d’une famille d’appareils sont divisé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 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 livré avec la version 10.0.17134.0 de la famille d’appareils universels. Mais ce même contrat était à la version 10.0 quand il était livré 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 et le numéro de version du contrat d’API pour n’importe quelle API Windows Runtime donnée. Dans la section Écriture de code plus loin dans cette rubrique, vous verrez pourquoi et comment utiliser ces informations.

Comme premier exemple, nous allons prendre la méthode StorageFolder.TryGetChangeTracker . Dans la section Windows 10 conditions requises 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 de la méthode StorageFolder.TryGetItemAsync . Il n’existe aucune section Windows 10 conditions requises dans cette rubrique. Examinez plutôt la rubrique de la classe StorageFolder elle-même. La section Windows 10 conditions requises contient la réponse. Étant donné que la rubrique StorageFolder.TryGetItemAsync ne dit rien de différent, nous pouvons conclure qu’elle partage ses exigences avec sa classe parente. StorageFolder.TryGetItemAsync a donc é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 à prendre en compte pour vous aider à déterminer la famille d’appareils à cibler. Pour plus d’informations, consultez TargetDeviceFamily.

Optimiser 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 universels. Plus précisément, comme nous l’avons vu, vous ciblerez une plage de versions de la famille d’appareils universels.

Limiter votre application à un 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 universels ou de cibler l’une des familles d’appareils enfants, vous pouvez plutôt cibler deux familles d’appareils enfants (ou plus). Le ciblage du bureau et du mobile peut être judicieux pour votre application. Ou Bureau et équipe. 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 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 à l’avenir , dites à 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 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 le sens où elle 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. Prenons 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 ciblant votre application. Visual Studio IntelliSense vous montre les API de la famille d’appareils universelles, ainsi que les API disponibles pour les sdk d’extension que vous avez référencés.

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

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

Il y aura des cas lorsque vous souhaitez 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 les cas comme ceux-ci, vous pouvez choisir d’écrire du code adaptatif afin de pouvoir appeler ces API en toute sécurité. La section suivante vous montre comment.

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

Il existe deux étapes impliquées dans l’utilisation du code adaptatif pour appeler une API de manière conditionnelle. 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 dans votre code pour tester la présence de l’API que vous souhaitez appeler. Cette condition est évaluée partout et chaque fois que votre application s’exécute. Mais elle est évaluée true uniquement sur les appareils où l’API est présente et donc disponible pour appeler.

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

// 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 est sûr 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 requises. Mais dans le temps, de nouveaux membres seront ajoutés à des classes déjà introduites, et ces membres auront plus tard introduit 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 plus divisé en sous-divisions appelées contrats 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 sinon 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 API qui a introduit d’abord les API d’intérêt, consultez la section Rechercher le contrat API pour une section API WinRT plus haut dans cette rubrique.

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

Lorsque vous êtes prêt à voir comment votre application ressemble et se présente sur une taille particulière d’é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 petit ou moyen, 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 xaml (voir Dispositions adaptatives avec des états visuels et des déclencheurs d’état), vous pouvez également le tester.

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 prendrez en charge. Vous pouvez ajouter une taille d’appareil supplémentaire à votre projet à tout moment.

Voir aussi