Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Important
Les infos de cette rubrique s'appliquent à toutes les versions de Windows 10, et suivantes. Nous nous référerons ici à ces versions en tant que « Windows », en mentionnant les exceptions si nécessaire.
Toutes les versions de Windows partagent une base commune de composants du système d'exploitation (OS) appelée core OS (dans certains contextes, cette base commune est également appelée OneCore). Dans les composants centraux du système d'exploitation, les API Win32 sont organisées en groupes fonctionnels appelés Ensembles d'API.
L’objectif d’un jeu d’API est de fournir une séparation architecturale entre la DLL hôte dans laquelle une API Win32 donnée est implémentée et le contrat fonctionnel auquel appartient l’API. Le découplage que les ensembles d'API permettent entre la mise en œuvre et les contrats offre de nombreux avantages techniques aux développeurs. En particulier, l'utilisation d'ensembles d'API dans votre code peut améliorer la compatibilité avec les appareils Windows.
Les ensembles d'API répondent spécifiquement aux scénarios suivants :
Bien que l’étendue complète de l’API Win32 soit prise en charge sur les PC, seul un sous-ensemble de l’API Win32 est disponible sur d’autres appareils Windows tels que HoloLens, XBOX et d’autres appareils. Un nom d’ensemble d’API vous donne une question stable pour que votre application puisse détecter au moment de l’exécution si une fonctionnalité est disponible sur l’appareil actuel. La requête elle-même est effectuée par la fonction IsApiSetImplemented .
Certaines implémentations d'API Win32 existent dans des DLL avec des noms différents sur différents appareils Windows. L’utilisation de noms d’ensembles d’API au lieu de noms DLL lors de la détection de la disponibilité de l’API et du retard du chargement des API fournit un itinéraire correct vers l’implémentation, quel que soit l’emplacement où l’API est réellement implémentée.
Pour plus de détails, voir Fonctionnement du chargeur d'ensembles d'API et Détecter la disponibilité des ensembles d'API.
Les ensembles d’API et les DLL sont-ils identiques ?
Non : un nom d’ensemble d’API identifie un contrat, et non un fichier. Lors de l’exécution, le chargeur résout ce contrat via le schéma d’ensemble d’API sur l’appareil en cours d’utilisation, puis redirige la référence vers la DLL qui héberge l’implémentation. Il s'agit d'une technique de dissimulation de l'implémentation, qui vous permet, en tant qu'appelant, de ne pas savoir exactement quel module héberge les informations.
Cette technique permet aux modules d'être remaniés (divisés, consolidés, renommés, etc.) sur différentes versions et éditions de Windows. Et vos applications continuent de lier et sont toujours acheminées vers le code correct au moment de l’exécution.
Alors pourquoi les noms des ensembles d'API contiennent-ils .dll ? La raison en est la manière dont le chargeur de DLL est implémenté. Le chargeur fait partie du système d’exploitation qui charge des DLL et/ou résout les références aux DLL, et identifie ce qu’il faut charger par un nom de module orthographié de la façon dont les noms de fichiers sont orthographiés dans une table d’importation. Les noms des ensembles d’API suivent la même convention afin de s'adapter au même espace.
Le chargeur reconnaît un nom qui commence par api- ou ext- l’achemine vers le runtime du jeu d’API, une extension du chargeur qui résout les contrats via le schéma. À partir de ce point, le nom est analysé par les règles d’affectation de noms de l’ensemble d’API plutôt que comme nom de fichier, de sorte que le .dll suffixe ne fait pas partie du nom du contrat en cours de résolution.
Vous pouvez passer un nom d’ensemble d’API à LoadLibrary ou l’utiliser comme cible de chargement différé. L’opération réussit lorsque le schéma sur l’appareil actuel mappe ce contrat à un hôte utilisable ; il n’y a pas nécessairement de fichier réel portant ce nom n’importe où sur le PC. Si le contrat n’est pas associé à l’appareil actuel, l’appel direct à LoadLibrary échoue. Une référence à chargement différé se comporte différemment : le processus se charge quand même, et l’absence ne se manifeste que plus tard, lorsque l’API est appelée.
D’une manière ou d’une autre, une liaison ou une charge réussie n’est pas en soi une preuve qu’une implémentation est présente. Pour déterminer cela, consultez Détecter la disponibilité du groupe d’API.
Lier des bibliothèques parapluie
Pour faciliter la restriction de votre code aux API Win32 qui sont prises en charge dans le système d'exploitation principal, nous fournissons une série de bibliothèques parapluies. Une bibliothèque parapluie vous permet de lier une bibliothèque unique au lieu d’identifier la bibliothèque d’importation individuelle pour chaque API que vous appelez.
Pour plus d'informations et pour choisir la bibliothèque parapluie qui correspond à ce que vous ciblez, consultez Windows bibliothèques parapluies.
Noms de contrat des ensembles d'API
Les ensembles d’API sont identifiés par un nom de contrat qui suit les conventions reconnues par le chargeur de bibliothèque.
Tous les noms de contrat partagent ces conventions :
- Le nom commence soit par la chaîne api-, soit par ext-.
- Le corps du nom peut être constitué de caractères alphanumériques ou de tirets (-). Un tilde (~) apparaît uniquement comme séparateur avant un nom de groupe.
- Le nom n’est pas sensible à la casse.
Deux formes de nom de contrat sont en cours d’utilisation et vous pouvez en rencontrer une.
Un nom de contrat versionné se termine par la séquence l<n>->n<->n<, où n est constitué de chiffres décimaux, par exemple ext-ms-win-core-samplefeature-l1-1-0. Les numéros de fin identifient une version spécifique du contrat et un nom dans ce formulaire doit être considéré comme un identificateur immuable pour cette version.
Un alias de contrat ne comporte aucune version, par exemple api-win-core-samplefeature. Il identifie le contrat lui-même plutôt qu’une version de celui-ci. Lorsqu’un contrat organise ses fonctionnalités individuelles disponibles en groupes nommés, un groupe est traité en ajoutant le nom du groupe à l’alias de contrat, séparé par un tilde : api-win-core-samplefeature~AdvancedOperations
Les samplefeature noms utilisés ici sont des noms illustrant un composant de Windows fictif.
Les préfixes « api- » et « ext- »
Le préfixe est une convention d’affectation de noms. Il a été initialement destiné à distinguer les contrats présents sur chaque édition éligible (api-) des contrats qui pourraient être absents (ext-). Cette distinction n’a pas été appliquée de manière cohérente et le rôle d’un contrat peut changer au fil du temps sans que le contrat ne soit renommé.
Le chargeur n’affecte aucune importance au préfixe ; il résout les noms d’API et d’ext- par les mêmes règles. N’inférencez pas la disponibilité à partir du préfixe. Interrogez-la à la place : consultez Détecter la disponibilité du groupe d’API.
Utilisation d’un nom de contrat
Deux types d’opérations différents prennent un nom de contrat.
Les opérations de chargeur, telles que LoadLibrary ou P/Invoke, prennent le nom du contrat dans le même endroit qu’un nom de module DLL s’affiche généralement. Un ajout .dll est conventionnel dans ce contexte, mais il n’est pas requis par la résolution de noms de l’ensemble d’API et ne fait pas partie du nom du contrat. Utilisez un nom de contrat au lieu d’un nom de module DLL physique pour garantir un itinéraire correct vers l’implémentation, quel que soit l’emplacement où l’API est réellement implémentée sur l’appareil actuel. Il n’est pas nécessaire d’avoir un fichier portant ce nom de contrat sur le disque.
Les exemples de requêtes de disponibilité omettent traditionnellement le suffixe .dll et utilisent le formulaire qui correspond à la façon dont l’API est traitée :
| Surface d’API | Format de requête | Example |
|---|---|---|
| Groupe nommé | <contract>~<group> |
api-win-core-samplefeature~AdvancedOperations |
| Groupe par défaut | Alias du contrat, sans ~Default |
api-win-core-samplefeature |
| Contrat versionné | Nom complet du contrat versionné | ext-ms-win-core-samplefeature-l1-1-0 |
Un nom de groupe ne peut pas être associé à un nom de contrat versionné.
Identification des ensembles d'API pour les API Win32
Pour déterminer si une API Win32 particulière appartient à un ensemble d'API, consultez le tableau des exigences dans la documentation de référence de l'API. Si l'API appartient à un ensemble d'API, le tableau des exigences de l'article répertorie le nom de l'ensemble d'API et la version de Windows dans laquelle l'API a été introduite pour la première fois dans l'ensemble d'API. Pour des exemples d'API appartenant à un ensemble d'API, reportez-vous à ces articles :
Si l’en-tête de l’API fournit une fonction d’assistance Is<APIName>Present , préférez cette assistance lorsque vous testez la disponibilité. Il contient déjà le nom correct pour l’ensemble d’API ou le groupe qui contient l’API. Pour plus d’informations, consultez Détecter la disponibilité du groupe d’API.