Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
La información de este tema se aplica a todas las versiones de Windows 10 y versiones posteriores. Aquí nos referiremos a esas versiones como "Windows", señalando las excepciones cada vez que sea necesario.
Todas las versiones de Windows tienen una base común de componentes del sistema operativo (SO) que se denomina sistema operativo principal (en algunos contextos, esta base común también se denomina OneCore). En los componentes del sistema operativo principal, las API de Win32 se organizan en grupos funcionales denominados conjuntos de API.
El propósito de un conjunto de API es proporcionar una separación arquitectónica entre el archivo DLL de host en el que se implementa una API win32 determinada y el contrato funcional al que pertenece la API. La desacoplamiento que ofrecen los conjuntos de API entre implementación y contratos ofrece muchas ventajas en el proceso de ingeniería para los desarrolladores. En concreto, el uso de conjuntos de API en el código puede mejorar la compatibilidad con dispositivos Windows.
Los conjuntos de API sirven específicamente en estos casos:
Aunque la amplitud completa de la API de Win32 se admite en equipos, solo hay un subconjunto de la API de Win32 disponible en otros dispositivos Windows, como HoloLens, XBOX y otros dispositivos. Un nombre de conjunto de API le proporciona una cosa estable sobre la que preguntar, de modo que la aplicación pueda detectar en tiempo de ejecución si una funcionalidad está disponible en el dispositivo actual. La propia consulta se realiza mediante la función IsApiSetImplemented .
Algunas implementaciones de API de Win32 existen en archivos DLL con nombres diferentes en distintos dispositivos con Windows. El uso de nombres de conjuntos de API en lugar de nombres dll al detectar la disponibilidad de la API y retrasar la carga de API proporciona una ruta correcta a la implementación independientemente de dónde se implemente realmente la API.
Para obtener más información, consulte Operación del cargador del conjunto de API y Detección de disponibilidad del conjunto de API.
¿Son los conjuntos de API y los archivos DLL lo mismo?
No: un nombre de conjunto de API identifica un contrato, no un archivo. En tiempo de ejecución, el cargador resuelve ese contrato mediante el esquema del conjunto de API en el dispositivo actual y enruta la referencia al archivo DLL que hospeda la implementación. Es una técnica de ocultación de la implementación, donde usted como autor de la llamada no tiene que saber exactamente qué módulo hospeda la información.
La técnica permite refactorizar módulos (dividir, consolidar, cambiar el nombre, etc.) en diferentes versiones y ediciones de Windows. Y tus aplicaciones siguen enlazándose y se siguen dirigiendo al código correcto en tiempo de ejecución.
¿Por qué en los conjuntos de API aparece .dll en sus nombres? La razón es la forma en que se implementa el cargador de DLL. El cargador es la parte del sistema operativo que carga archivos DLL y/o resuelve referencias a archivos DLL, e identifica qué debe cargarse por el nombre del módulo, escrito de la misma forma que se escriben los nombres de archivo en una tabla de importación. Los nombres de conjuntos de API siguen la misma convención para que se ajusten al mismo lugar.
El cargador reconoce un nombre que comienza por api- o ext- y lo enruta al entorno de ejecución del conjunto de API, una extensión del cargador que resuelve los contratos a través del esquema. Desde ese punto, las reglas de nomenclatura del conjunto de API analizan el nombre en lugar de como un nombre de archivo, por lo que el .dll sufijo no forma parte del nombre del contrato que se va a resolver.
Puede pasar un nombre de conjunto de API a LoadLibrary o usarlo como destino de carga retrasada. La operación se realiza correctamente cuando el esquema del dispositivo actual asigna ese contrato a un host utilizable; no hay necesariamente un archivo real con ese nombre en cualquier parte del equipo. Si el contrato no está mapeado en el dispositivo actual, una llamada directa a LoadLibrary falla. Una referencia de carga diferida se comporta de forma diferente: el proceso sigue cargándose, y la ausencia solo se manifiesta más tarde, cuando se llama a la API.
En cualquier caso, un enlace o una carga correctos no constituyen por sí solos prueba de que exista una implementación. Para determinarlo, consulte Detección de la disponibilidad del conjunto de API.
Enlace de bibliotecas contenedoras
Para facilitar la restricción de su código a las API de Win32 compatibles con el núcleo del sistema operativo, ofrecemos una serie de bibliotecas contenedoras. Una biblioteca unificada permite enlazar una única biblioteca en lugar de identificar la biblioteca de importación correspondiente para cada API que se utilice.
Para obtener más información y elegir la biblioteca general que coincida con su objetivo, consulte Bibliotecas generales de Windows.
Nombres de contrato de conjuntos de API
Los conjuntos de API se identifican mediante un nombre de contrato que sigue las convenciones reconocidas por el cargador de biblioteca.
Todos los nombres de contrato comparten estas convenciones:
- El nombre comienza por la cadena api- o bien ext-.
- El cuerpo del nombre puede estar formado por caracteres alfanuméricos o guiones (-). Una tilde (~) solo aparece como separador antes de un nombre de grupo.
- El nombre no distingue entre mayúsculas y minúsculas.
Hay dos formas de nombre de contrato en uso y puede encontrar cualquiera de ellas.
Un nombre de contrato versionado termina con la secuencia l<n>->n<-<n>, donde n consta de dígitos decimales; por ejemplo, ext-ms-win-core-samplefeature-l1-1-0. Los números finales identifican una versión específica del contrato y un nombre en este formulario debe considerarse un identificador inmutable para esa versión.
Un alias de contrato no incluye ninguna versión, por ejemplo, api-win-core-samplefeature. Identifica el propio contrato en lugar de una versión de él. Cuando un contrato organiza sus capacidades disponibles individualmente en grupos con nombre, se referencia un grupo añadiendo el nombre del grupo al alias del contrato, separado por una tilde: api-win-core-samplefeature~AdvancedOperations.
Los samplefeature nombres que se usan aquí son nombres ilustrativos para un componente de Windows ficticio.
Prefijos api y ext-
El prefijo es una convención de nomenclatura. Originalmente se concibió para distinguir los contratos que están presentes en cada edición compatible (api-) de los contratos que podrían no estar presentes (ext-). Esa distinción no se aplicó de forma coherente y el rol de un contrato puede cambiar con el tiempo sin que se cambie el nombre del contrato.
El cargador no atribuye ninguna importancia al prefijo; resuelve los nombres api- y ext- según las mismas reglas. No deduzcas la disponibilidad a partir del prefijo. Consúltelo en su lugar; consulte Detectar disponibilidad del conjunto de API.
Uso de un nombre de contrato
Dos tipos diferentes de operaciones toman un nombre de contrato.
Las operaciones del cargador, como LoadLibrary o P/Invoke, toman el nombre del contrato en el mismo lugar donde aparece normalmente un nombre de módulo DLL. Agregar .dll al final es habitual en ese contexto, pero no es necesario para la resolución de nombres de conjuntos de API y no forma parte del nombre del contrato. Use un nombre de contrato en lugar de un nombre de módulo DLL físico para garantizar una ruta correcta a la implementación, independientemente de dónde se implemente realmente la API en el dispositivo actual. No es necesario que haya un archivo con ese nombre de contrato en el disco.
Los ejemplos de consultas de disponibilidad omiten convencionalmente el sufijo .dll y usan el formulario que coincide con el modo en que se aborda la API:
| Superficie de la API | Formulario de consulta | Example |
|---|---|---|
| Grupo con nombre | <contract>~<group> |
api-win-core-samplefeature~AdvancedOperations |
| Grupo predeterminado | Alias del contrato, sin ~Default |
api-win-core-samplefeature |
| Contrato versionado | Nombre completo del contrato versionado | ext-ms-win-core-samplefeature-l1-1-0 |
No se puede combinar un nombre de grupo con un nombre de contrato versionado.
Identificación de conjuntos de API para API de Win32
Para identificar si una API de Win32 determinada pertenece a un conjunto de API, consulte la tabla de requisitos en la documentación de referencia de la API. Si la API pertenece a un conjunto de API, en la tabla de requisitos del artículo aparecerá el nombre del conjunto de API y la versión de Windows en la que la API se integró por primera vez en el conjunto de API. Para ver ejemplos de API que pertenecen a un conjunto de API, consulte estos artículos:
Si el encabezado de la API proporciona una Is<APIName>Present función auxiliar, prefiera ese asistente al probar la disponibilidad. Ya contiene el nombre correcto para el conjunto o grupo de API que contiene la API. Para obtener más información, consulte Detección de disponibilidad del conjunto de API.