WinRT es COM — IInspectable, .winmd, proyecciones de lenguaje y por qué WinUI sigue apoyándose en un contrato binario

Quiere añadir una capacidad nueva de Windows a una aplicación WPF o WinForms. Pero llamar a un selector WinRT lanza una excepción. Luego lee sobre WinUI y parece que habría que reconstruir la interfaz. Esta confusión se aclara una vez que separa el funcionamiento de WinRT de la elección del marco de interfaz.

El punto de partida de este artículo es que WinRT también se apoya en el contrato binario de COM. Microsoft mismo afirma con claridad que «The Windows Runtime is based on COM».¹ La tabla de Excel incrustada en Word que vimos en el artículo anterior sobre objetos OLE, y el WinRT y WinUI de hoy, tienen el mismo IUnknown en la raíz.

Aquí fijamos primero los tres elementos que componen WinRT, luego vemos a qué prestar atención al usarlo desde una aplicación de escritorio y, por último, cómo tratar los activos existentes. Los lectores previstos son desarrolladores con experiencia en COM o en el desarrollo de escritorio para Windows, los requisitos previos son Windows 10/11 y .NET 6 o posterior (C#) o C++17 (C++/WinRT), y el nivel de dificultad es intermedio.

1. Primero la conclusión

Hay tres conclusiones que conviene retener.

• WinRT no es un runtime administrado; es un ABI (un contrato binario) construido sobre COM. A ese contrato se añaden .winmd, que transporta información de tipos, y las proyecciones de lenguaje, que permiten a cada lenguaje llamarlo con naturalidad.¹²³⁴
• La mayoría de las API WinRT se pueden usar desde aplicaciones WPF, WinForms y Win32 existentes. Pero hay que comprobar tres requisitos previos: pasar un HWND, la identidad de paquete y la inicialización del subproceso.⁵⁶⁷⁸
• Una migración completa de interfaz a WinUI y el uso selectivo de API WinRT son decisiones distintas. WinUI también se asienta en el ABI de WinRT, y los activos COM/ActiveX existentes y WinRT pueden coexistir sobre el mismo fundamento.⁹²¹

A partir de aquí, leer en el orden siguiente hace más fácil seguir las conexiones.

El mapa de conocimiento siguiente sirve para revisar cómo se relacionan los elementos. Si prefiere leer primero la explicación, continúe en orden desde la sección 2.

En el diagrama, una línea continua marca una relación que siempre se cumple y una línea discontinua una relación condicional (las condiciones están en la explicación de cada relación en la página de detalle). La lista completa de relaciones (20 en total, con evidencia y grado de certeza) y las definiciones de los conceptos principales están reunidas en la página de detalle del mapa de conocimiento (en japonés). Datos: JSON-LD / Turtle

2. OLE y WinRT comparten en la raíz el mismo contrato binario

En este blog hemos seguido hasta ahora el mundo de COM clásico: la filosofía de diseño de COM, el modelo de subprocesos STA/MTA, el trato de ActiveX/OCX y los documentos compuestos OLE. Todas son tecnologías de la década de 1990.

WinRT, en cambio, es el fundamento de API introducido con Windows 8 (2012). Hoy proporciona notificaciones toast, Compartir, Bluetooth, OCR y más como las API de los espacios de nombres Windows.*, y es también aquello sobre lo que se apoyan WinUI y el Windows App SDK.¹⁰ Lo antiguo y lo nuevo parecen mundos enteramente separados, pero en sustancia son continuos.

Lo que comparten es la promesa de llamar a través de interfaces

Los componentes COM y las clases WinRT exponen ambos su funcionalidad a través de interfaces. Al comparar las interfaces base, la relación queda así.¹

En otras palabras, WinRT no sustituyó COM por un mecanismo ajeno; es una capa más apilada sobre IUnknown. El recuento de referencias, QueryInterface y HRESULT siguen vivos tal como estaban.

La documentación de C++/WinRT también llama a las API WinRT «an evolution of COM» y explica que están diseñadas para consumirse, como API basadas en COM, a través de proyecciones de lenguaje.²¹¹

flowchart TB
    accTitle: El linaje de COM clásico y WinRT
    accDescr: Sobre el fundamento compartido del contrato binario COM hecho de IUnknown y vtables se sostienen, lado a lado, el mundo COM clásico de OLE y ActiveX de la década de 1990 y el mundo de WinRT a partir de 2012, con WinUI y el Windows App SDK encima; los dos no se excluyen, son continuos
    base["Contrato binario COM (IUnknown, vtable)"]
    base --> classic["COM clásico (OLE, ActiveX, COM propio)"]
    base --> winrt["WinRT (IInspectable, .winmd)"]
    winrt --> winui["WinUI / Windows App SDK"]
    classic -.-> coexist["Pueden coexistir sobre el mismo fundamento"]
    winrt -.-> coexist

Figura 1: COM clásico y WinRT no son mundos separados, sino dos generaciones, antigua y nueva, sobre el mismo contrato binario.

Por eso este artículo no es meramente «una introducción a una API nueva». Es un artículo que confirma dónde el conocimiento de COM que ya tiene se aplica en el desarrollo para Windows de 2026.

3. IInspectable encima de IUnknown

El fundamento inalterado y los tres métodos añadidos

La especificación oficial del sistema de tipos de WinRT estipula que cada interfaz WinRT exige implícitamente IInspectable, e IInspectable exige IUnknown. Lo que IUnknown define son, como siempre, los tres métodos QueryInterface, AddRef y Release.¹²

Encima, IInspectable añade los tres métodos siguientes.¹³

flowchart TB
    accTitle: IInspectable asentado sobre IUnknown
    accDescr: Cada interfaz WinRT exige IInspectable, e IInspectable exige IUnknown. IUnknown proporciona QueryInterface, AddRef y Release; IInspectable proporciona GetIids, GetRuntimeClassName y GetTrustLevel; y los métodos de cada interfaz WinRT se asientan encima
    unk["IUnknown (QI, AddRef, Release)"]
    insp["IInspectable (GetIids, nombre de tipo, nivel de confianza)"]
    api["Métodos de cada interfaz WinRT"]
    unk --> insp
    insp --> api

Figura 2: Un objeto WinRT apila los tres métodos de IInspectable sobre los tres métodos de IUnknown, y las API individuales se asientan encima.

A partir de un nombre de tipo se consultan las definiciones de métodos, propiedades y eventos

Lo que importa no es el número de métodos añadidos, sino la capacidad de conectar un nombre de tipo con metadatos.

En COM clásico, el modo estándar de conocer la identidad de un objeto en tiempo de ejecución era «conocer el IID y preguntar mediante QueryInterface». Para los lenguajes de scripting había una vía distinta, IDispatch.

En WinRT, el nombre de tipo obtenido de GetRuntimeClassName se puede resolver frente a los metadatos .winmd de la sección siguiente. De ahí se obtiene la definición completa de sus métodos, propiedades y eventos. La propia especificación dice que poder obtener un nombre de tipo WinRT resoluble mediante metadatos «enables language projection».¹²

flowchart TB
    accTitle: De GetRuntimeClassName a la proyección de lenguaje
    accDescr: Cuando el llamador invoca GetRuntimeClassName en un objeto, vuelve el nombre de tipo WinRT plenamente calificado; resolver ese nombre de tipo frente a Windows Metadata da la definición completa del tipo, y eso es lo que hace posible la proyección a cada lenguaje
    obj["Objeto WinRT"] --> name["Nombre de tipo (GetRuntimeClassName)"]
    name --> md["Resolver la definición de tipo en .winmd"]
    md --> proj["La proyección de lenguaje se vuelve posible"]

Figura 3: «El nombre de tipo está disponible en tiempo de ejecución, y el nombre de tipo lleva a los metadatos» es el corazón del mecanismo de WinRT.

Separar «herencia» y «requires» en las interfaces definidas por el usuario

También hay una diferencia que quien está acostumbrado a COM debe notar. El sistema de tipos de WinRT no tiene herencia entre interfaces definidas por el usuario. Una derivación como IFileSystemBindData2 : IFileSystemBindData de COM clásico está deliberadamente ausente; en su lugar se expresa con la declaración «la interfaz A exige la interfaz B (requires)».¹²¹

Esto es un asunto distinto de la cadena ABI base IUnknown → IInspectable vista hasta ahora. Esa base permanece como fundamento de cada interfaz WinRT.

Los contratos definidos por el usuario se desplazaron hacia una forma más laxa, que no depende del diseño de herencia de la vtable. Al mismo tiempo, las llamadas en sí siguen pasando por la vtable. Importa no confundir la forma de escribir los contratos con el mecanismo de la llamada.

4. Lo que resolvió .winmd — el infierno de enlace de la información de tipos

La dificultad de COM clásico estaba en «cómo distribuir la información de tipos»

En la práctica de COM clásico, más esfuerzo iba a cómo distribuir la información de tipos que a implementar las interfaces mismas.

Una TLB tiene restricciones de tipos orientadas a automatización: cierta información que se puede escribir en IDL no cabe en una TLB. Y como cada lenguaje tiene su propia vía, cuando cualquiera de ellas queda desfasada aparecen desajustes de tipos. Tratamos estas dificultades en el artículo sobre bibliotecas de tipos y dscom y el artículo sobre compatibilidad retroactiva de interfaces DLL y COM.

.winmd es el contrato común que lee cada lenguaje

La respuesta de WinRT es Windows Metadata (.winmd). Las API se describen como metadatos legibles por máquina, y las herramientas y las proyecciones de lenguaje los leen para generar una proyección para cada lenguaje.³

Windows incluye los metadatos de cada API WinRT que proporciona el sistema y también ofrece API que resuelven espacios de nombres y tipos en tiempo de ejecución. El Windows SDK contiene una copia para el tiempo de compilación. Los terceros también pueden participar en la proyección de lenguaje por el mismo mecanismo que las API del sistema, adjuntando un .winmd a su propio componente WinRT.³

Lo que cambió aquí es la forma en que se distribuye la información de tipos. En lugar de TLB, encabezados y ensamblados de interop dispersos por lenguaje, un único .winmd lo leen ahora las proyecciones de cada lenguaje.

Dicho esto, IDL no se ha vuelto innecesario. Cuando se crea un componente WinRT, el contrato se sigue describiendo en IDL (MIDL 3.0, modernizado para WinRT), y el compilador MIDL genera el .winmd.¹⁴

flowchart TB
    accTitle: El conducto de producción de un componente WinRT
    accDescr: El contrato de un componente WinRT se sigue escribiendo en IDL, es decir, MIDL 3.0, y el compilador MIDL lo compila en un .winmd. Lo que se distribuye es este .winmd, y la herramienta de proyección de cada lenguaje, como cppwinrt.exe o cswinrt.exe, lo lee para generar la proyección. Lo que se sustituyó no es IDL, sino la forma en que se distribuye la información de tipos
    idl2["Escribir el contrato (IDL, MIDL 3.0)"]
    midl2["Compilador MIDL"]
    winmd4[".winmd (información de tipos distribuida)"]
    proj3["Generar la proyección de cada lenguaje"]
    idl2 --> midl2
    midl2 --> winmd4
    winmd4 --> proj3

Figura 4: El punto de entrada del contrato (IDL) sigue en servicio; el punto de salida, la información de tipos distribuida, se unificó en .winmd.

El mismo formato de archivo que .NET, pero no un runtime administrado

El formato físico de un .winmd usa la especificación ECMA-335, la misma que un ensamblado CLR. Las reglas sobre qué combinaciones de datos son válidas difieren, no obstante, de las de los ensamblados CLR. Tomar prestado el formato y necesitar el CLR para ejecutarse son dos cosas distintas.³

Aquí hay que leer por separado las API del sistema y los componentes de terceros.

Como un .winmd parece un ensamblado de .NET al abrirlo en una herramienta, es fácil caer en la idea falsa «WinRT = administrado». Pero el contenido de un .winmd que proporciona el sistema es un contrato para interfaces COM.³

flowchart TB
    accTitle: Separación del .winmd y la implementación
    accDescr: Un .winmd es un archivo de metadatos que toma prestado el formato físico ECMA-335; los que proporciona el sistema son contratos sin código ejecutable, y la implementación de las API WinRT que proporciona el sistema vive en DLL nativas del sistema operativo. Por esta separación, aunque un .winmd parezca un ensamblado de .NET, no se necesita el CLR para ejecutar las API WinRT del sistema (el .winmd de un componente administrado de terceros contiene MSIL y exige el runtime de .NET)
    winmd3[".winmd (contrato, formato ECMA-335)"]
    impl["DLL nativa del sistema operativo (implementación)"]
    winmd3 -.->|"Proporcionado por el sistema: sin código"| note3["Las API del sistema no necesitan CLR"]
    impl --> note3
    winmd3 ---|"Las definiciones de tipo corresponden a la implementación"| impl

Figura 5: En las API WinRT que proporciona el sistema, el .winmd es el contrato y la implementación una DLL nativa del sistema operativo. El formato parece .NET, pero la ejecución es COM nativo.

flowchart TB
    accTitle: Información de tipos de COM clásico frente a .winmd
    accDescr: En COM clásico la vía de información de tipos estaba partida por lenguaje, de IDL a encabezados de C++, de bibliotecas de tipos a VB6 y scripting, de ensamblados de interop a .NET, lo que causaba incoherencias, mientras que en WinRT un único .winmd lo leen en común las proyecciones de cada lenguaje
    subgraph old["COM clásico: una vía por lenguaje"]
    idl["IDL a encabezados de C++"]
    tlb["TLB a VB6 y scripting"]
    ia["Ensamblado de interop a .NET"]
    end
    winmd[".winmd (metadatos únicos)"]
    winmd --> all["Leído en común por la proyección de cada lenguaje"]

Figura 6: .winmd plegó la dispersión de la información de tipos por lenguaje en «un archivo de metadatos que todos leen».

Las restricciones no desaparecieron; se desplazaron a un eje de proyectabilidad

Para quien conoce COM clásico, en una frase: .winmd es «la biblioteca de tipos, rehecha». Piénselo como el papel que una TLB intentaba desempeñar, rediseñado desde el principio como única fuente de verdad compartida por todos los lenguajes, sobre el formato acreditado ECMA-335, y su lugar queda claro.

Las restricciones, no obstante, no se han ido. Las restricciones orientadas a automatización de las TLB fueron sustituidas por las restricciones del sistema de tipos propio de WinRT, cuyo eje es «poder proyectarse con seguridad a cada lenguaje». La ausencia de herencia entre interfaces definidas por el usuario, vista en la sección 3, es un ejemplo.¹²

En consecuencia, un contrato COM/IDL existente no necesariamente se puede llevar a WinRT tal cual. Puede que haya que rediseñar la API.

flowchart TB
    accTitle: Sustitución de las restricciones de biblioteca de tipos por las del sistema de tipos WinRT
    accDescr: Las restricciones de expresividad orientadas a automatización de la TLB (biblioteca de tipos) no las eliminó .winmd, sino que las sustituyó por las restricciones del sistema de tipos propio de WinRT, cuyo eje es la proyección segura a cada lenguaje. Un ejemplo es la ausencia de herencia de interfaces definidas por el usuario; un contrato COM/IDL existente no necesariamente se puede retomar tal cual, y puede que haya que rediseñar la API
    tlb["Restricciones de TLB (orientadas a automatización)"] -->|"Sustituidas por"| wrt["Restricciones del sistema de tipos WinRT (eje de proyectabilidad)"]
    wrt -.-> ex["Ejemplo: sin herencia definida por el usuario"]
    wrt -.-> re["Los contratos COM existentes pueden necesitar rediseño"]

Figura 7: Las restricciones de TLB no «desaparecieron»; se sustituyeron por otras restricciones cuyo eje es la proyectabilidad a cada lenguaje.

5. C++/WinRT y C#/WinRT son proyecciones, no «contenedores»

Mostrar el contrato común a cada lenguaje en su forma natural

Una vez que hay un contrato común en forma de .winmd, la vista para cada lenguaje se puede generar automáticamente con herramientas. Esto es una proyección de lenguaje (language projection). Expone las API WinRT en el idioma de cada lenguaje y oculta los detalles de COM, ofreciendo una experiencia de programación natural para ese lenguaje.⁴¹¹

Las proyecciones que Microsoft admite actualmente son las dos siguientes.⁴

La historia del lado de C# es un poco confusa, así que la desenredamos. Hasta .NET Core 3.x, el runtime de .NET tenía compatibilidad integrada para consumir WinRT/winmd. En .NET 5 se retiró esa compatibilidad integrada y el papel pasó a C#/WinRT.¹⁶ Las API WinRT no dejaron de ser usables; cambió dónde se trata la proyección.

Hoy, cuando se indica en C# un TFM como net8.0-windows10.0.19041.0, los ensamblados de proyección del Windows SDK se referencian automáticamente.¹⁰

flowchart TB
    accTitle: Generación de las proyecciones para cada lenguaje a partir de .winmd
    accDescr: Cuando cppwinrt.exe lee el .winmd único, genera encabezados de proyección C++17; cuando cswinrt.exe lo lee, genera un ensamblado de interop C#; y las API WinRT se exponen de una forma que sigue el idioma de cada lenguaje
    winmd2[".winmd (el contrato de API)"]
    winmd2 --> cpp["cppwinrt.exe a encabezados C++17"]
    winmd2 --> cs["cswinrt.exe a ensamblado de interop C#"]
    cpp --> cppcode["Invocable en el idioma de C++"]
    cs --> cscode["Invocable en el idioma de C#"]

Figura 8: Una proyección no es un contenedor escrito a mano; las herramientas la generan de forma mecánica a partir del contrato (.winmd).

Aunque se genere, la llamada en sí sigue siendo COM

Este artículo dice «proyección» en lugar de «contenedor» para subrayar que es un mecanismo derivado de forma mecánica de los metadatos, no una capa de traducción que las personas mantienen API por API. Cualquier API presente en el .winmd se puede hacer usable desde el principio en cada lenguaje admitido.

Y desde el lenguaje que se llame, lo que ocurre bajo la proyección es la misma llamada COM. Por ejemplo, cuando se escribe await picker.PickSingleFolderAsync() en C#, la proyección tiende un puente entre el IAsyncOperation de WinRT y el mundo del Task de .NET. Aun así, en el lado ABI se usan llamadas a métodos de vtable y HRESULT. Por eso los errores aparecen en forma de excepciones COM (un HRESULT como 0x80070005).

flowchart TB
    accTitle: Las capas del código C# a la API WinRT del sistema operativo
    accDescr: El código C# o C++ de la aplicación se convierte, a través de la proyección de lenguaje, en llamadas ABI de WinRT, es decir, llamadas de vtable sobre IInspectable, y llega a la API WinRT implementada por el sistema operativo. La proyección solo oculta los detalles de COM; la llamada en sí es COM
    code["Código de la aplicación (C#, C++)"]
    proj2["Proyección de lenguaje"]
    abi["ABI de WinRT (vtable de IInspectable)"]
    os["Implementación del sistema operativo de la API WinRT"]
    code --> proj2
    proj2 --> abi
    abi --> os

Figura 9: Lo que oculta la proyección son los «detalles» de COM, no COM en sí.

Conocer esta estructura permite partir un incidente en dos capas. Un desajuste de versión del código generado o un TFM que falta es la capa de proyección; los HRESULT, los apartments y el recuento de referencias son la capa ABI. En esta última, la experiencia de desarrollo COM sirve de inmediato.

6. Dónde se atascan las aplicaciones de escritorio — HWND, identidad, apartments

Primero separar «poder referenciar la API» de «las condiciones para que funcione»

La mayoría de las API WinRT se pueden llamar desde aplicaciones de escritorio WPF, WinForms y Win32.⁵ El punto de entrada para llamarlas difiere entre C# y C++ como sigue.¹⁰

Poder referenciar las API, no obstante, no significa que cada API funcione tal cual. Compruebe los tres puntos siguientes. Las condiciones de registro de las notificaciones toast se tratan por separado en la sección 9.

Punto de atasco 1: pasar un HWND a una interfaz como los selectores

Algunos selectores, cuadros de diálogo y la interfaz de Compartir esperan un CoreWindow de UWP como superficie de visualización. Una aplicación de escritorio no tiene CoreWindow, así que el HWND de la ventana propietaria debe pasarse de forma explícita antes de mostrar el objeto.⁶

El punto de entrada que se usa para selectores y similares es una interfaz COM llamada IInitializeWithWindow. Hereda de IUnknown y proporciona una ventana propietaria a los objetos WinRT usados en aplicaciones de escritorio.¹⁷

En C#, primero obtenga el HWND según el marco de interfaz en uso.¹⁸⁶

A continuación, páselo al selector con WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd) y solo entonces muéstrelo. En C++/WinRT, obtenga el objeto como as<IInitializeWithWindow>() y luego llame a Initialize(hwnd). Si se omite la inicialización, lanza o falla en silencio.¹⁸¹⁹

Inicializar un objeto WinRT moderno mediante QueryInterface a una interfaz COM clásica: que este puente sea la práctica oficial es otro lugar en el que WinRT muestra que es COM.

La interfaz de Compartir usa otra interfaz. Para DataTransferManager no se usa IInitializeWithWindow. Se usa el IDataTransferManagerInterop dedicado y se pasa el HWND a ShowShareUIForWindow.⁶

Los selectores más nuevos del Windows App SDK son otra vía distinta. Microsoft.Windows.Storage.Pickers recibe un WindowId en el constructor, así que el patrón InitializeWithWindow es innecesario. No son, no obstante, API que se puedan usar solo con un ajuste de TFM. Además de añadir el Windows App SDK, una aplicación sin empaquetar necesita que el runtime se despliegue e inicialice en las máquinas de destino.¹⁹

sequenceDiagram
    accTitle: Pasos para mostrar un selector desde una aplicación de escritorio
    accDescr: Tras crear un selector, una aplicación de escritorio que llama PickSingleFolderAsync tal cual obtiene una excepción o un fallo silencioso, así que primero hay que obtener el HWND de la ventana propietaria y pasarlo mediante Initialize de IInitializeWithWindow antes de mostrar el selector
    participant A as Aplicación de escritorio
    participant P as Selector (WinRT)
    A->>P: Crear
    alt Mostrar sin pasar un HWND
        A->>P: PickSingleFolderAsync
        P-->>A: Excepción o fallo silencioso
    else Pasar primero el HWND
        A->>P: Establecer el HWND mediante IInitializeWithWindow
        A->>P: PickSingleFolderAsync
        P-->>A: Se muestra el selector
    end

Figura 10: Cubrir el hueco de «no hay CoreWindow en el escritorio» pasando un HWND de forma explícita es la práctica oficial.

Punto de atasco 2: algunas API exigen identidad de paquete

Algunas API WinRT, como el historial de notificaciones toast (ToastNotificationHistory), las listas de accesos directos y los destinos de Compartir, solo funcionan en aplicaciones que tienen identidad de paquete (aplicaciones empaquetadas). Llamarlas desde una aplicación sin empaquetar distribuida con un instalador tradicional falla.⁷

Hay dos remedios. Empaquetar la aplicación con MSIX, o usar un «paquete con ubicación externa» (un sparse package), que concede una identidad y conserva el instalador existente.²⁰ Qué API exigen identidad se puede comprobar en la lista oficial.⁷

flowchart TB
    accTitle: Dos vías hacia las API que exigen identidad de paquete
    accDescr: Llamar una API WinRT que exige identidad de paquete desde una aplicación sin empaquetar falla, así que dé a la aplicación identidad de paquete empaquetándola con MSIX o con un paquete con ubicación externa, que solo concede el identificador y conserva el instalador existente
    need["Querer usar una API que exige identidad"]
    need --> m1["Empaquetar con MSIX"]
    need --> m2["Paquete con ubicación externa"]
    m1 --> id2["Obtener identidad de paquete"]
    m2 --> id2
    id2 -.-> okid["El historial de notificaciones etc. funciona"]

Figura 11: El remedio para las API que exigen identidad es una elección entre dos: «MSIX» o «instalador existente + concesión de un identificador».

Punto de atasco 3: comprobar la inicialización del subproceso y STA/MTA

Un subproceso que trata objetos WinRT debe inicializarse para WinRT de antemano. En código nativo, use RoInitialize o winrt::init_apartment e indique el modelo de concurrencia, STA o MTA. En aplicaciones C# WPF/WinForms, el runtime suele encargarse de la inicialización.⁸

RoInitialize es el punto de entrada de la generación WinRT dentro del mismo marco que CoInitializeEx de COM. La propia documentación de CoInitialize indica llamar a RoInitialize o Windows::Foundation::Initialize en su lugar cuando se usa Windows Runtime.²¹

El subproceso de interfaz de WPF/WinForms es un STA; los objetos de interfaz deben tocarse en el subproceso de interfaz; las esperas bloqueantes en un STA invitan a interbloqueos. El pensamiento tratado en el artículo de STA/MTA se traslada sin cambios a las API WinRT.

Algunas API no se pueden usar ni con HWND e identidad en su sitio

Los remedios hasta aquí conciernen a API que tienen un punto de entrada para uso de escritorio. Las API que dependen de CoreWindow o ApplicationView en sí no se pueden usar desde aplicaciones de escritorio. En ese caso, en lugar de añadir inicialización, busque una API alternativa.⁵⁷

flowchart TB
    accTitle: Ramificación de los puntos de atasco al llamar API WinRT desde el escritorio
    accDescr: Primero confirmar que el subproceso está inicializado para WinRT (en código nativo, indicar STA/MTA de forma explícita con RoInitialize o similar; en C#, el runtime suele encargarse). Luego, si la API WinRT que se quiere llamar es una interfaz que presupone un CoreWindow, pasar un HWND mediante IInitializeWithWindow o usar los selectores nuevos; si exige identidad de paquete, conceder un identificador con MSIX o un paquete con ubicación externa; las API que dependen de CoreWindow o ApplicationView en sí no se pueden usar en el escritorio, así que hay que buscar una API alternativa; y el gran resto de API se pueden llamar tal cual solo con el ajuste de TFM o C++/WinRT
    pre["Inicialización del subproceso"] --> q{"¿Qué tipo de API es?"}
    pre -.-> auto["Nativo: explícito; C#: suele ser automático"]
    q -->|"Interfaz"| h["HWND o los selectores nuevos"]
    q -->|"Identidad exigida"| p2["MSIX o conceder un identificador"]
    q -->|"Depende de CoreWindow en sí"| x["Buscar una API alternativa"]
    q -->|"Todo lo demás"| ok3["Invocable tal cual"]

Figura 12: Con la inicialización del subproceso como requisito previo (explícita en código nativo, en C# normalmente dejada al runtime), los puntos de atasco caen en tres familias, cada una con un remedio tipo.

flowchart TB
    accTitle: Correspondencia de la inicialización del subproceso entre COM y WinRT
    accDescr: En COM clásico un subproceso se inicializa con CoInitializeEx indicando STA o MTA, mientras que en WinRT se inicializa con RoInitialize indicando el mismo modelo de concurrencia STA o MTA. La documentación de CoInitialize también indica llamar a RoInitialize al usar WinRT, y el concepto de apartment es compartido
    com3["COM clásico: CoInitializeEx"] --> apt["Apartment (STA / MTA)"]
    wrt["WinRT: RoInitialize"] --> apt
    apt -.-> rule["El subproceso de interfaz es STA; cuidado con las esperas"]

Figura 13: El nombre de la API de inicialización cambió, pero se sigue usando el mismo concepto de apartment.

7. Lo que sostiene a WinUI — el desarrollo a la vista no cambia el contrato

Pasar al desarrollo a la vista no es un cambio del contrato binario

En el verano de 2025, Microsoft anunció oficialmente, como enfoque por fases, su política de llevar el desarrollo principal de WinUI a la vista en GitHub. Hay cuatro etapas: aumentar la frecuencia de actualización del espejo, hacer posibles las compilaciones locales, aceptar contribuciones de la comunidad una vez que las pruebas estén en su sitio y, por último, hacer de GitHub el hogar principal del desarrollo.²²

A la fecha de publicación de este artículo (finales de agosto de 2026), la documentación oficial también afirma con claridad que WinUI está «built in the open». El avance cotidiano de la ingeniería se puede seguir ahora en el repositorio público.⁹

Los desarrolladores que han seguido los relevos generacionales de WinForms a WPF a UWP a WinUI sienten con naturalidad «¿el marco vuelve a cambiar?». Pero los marcos de interfaz que no han dejado de cambiar y el fundamento debajo hay que mirarlos por separado. Win32 y COM, y desde 2012 el ABI de WinRT, se han quedado en el mismo sitio.

Las ventanas WinUI también las sostiene un HWND

WinUI es un conjunto de API WinRT proporcionado como parte del Windows App SDK.⁹²³ Su Microsoft.UI.Xaml.Window es una ventana sostenida por un HWND, que sustituye el modelo de ventana basado en CoreWindow de la generación UWP. El tutorial oficial de interop también empieza por obtener el identificador de ventana.²⁴

En otras palabras, una aplicación WinUI es una aplicación Win32 en la que un árbol de objetos que sigue el contrato IInspectable se ejecuta sobre una ventana HWND. El conocimiento de QueryInterface, recuento de referencias y apartments adquirido a través de COM, y el conocimiento de HWND y bucles de mensajes adquirido a través de Win32, se aplican ambos de inmediato a la resolución de problemas de WinUI.

flowchart TB
    accTitle: Relevos generacionales de los marcos de interfaz y el fundamento inalterado
    accDescr: Los marcos de interfaz WinForms, WPF, XAML de UWP y WinUI han encadenado generaciones, pero WinForms y WPF se asientan directamente sobre el fundamento de Win32 y COM, mientras que el XAML de UWP y WinUI se asientan sobre el mismo fundamento de Win32 y COM a través del ABI de WinRT. Lo que cambió de generación es la capa superior; el contrato debajo no ha cambiado
    gen["Relevos generacionales de los marcos de interfaz"]
    gen --> f1["WinForms, WPF"]
    gen --> f2["XAML de UWP"]
    gen --> f3["WinUI (actual)"]
    f2 --> abi3["ABI de WinRT (desde 2012)"]
    f3 --> abi3
    f1 --> stable["Fundamento inalterado (Win32 + COM)"]
    abi3 --> stable

Figura 14: Lo que subió y bajó fue la capa del marco. WinForms y WPF se asientan directamente sobre Win32 + COM; UWP y WinUI se asientan sobre el mismo fundamento a través del ABI de WinRT.

flowchart TB
    accTitle: Las capas que sostienen una aplicación WinUI
    accDescr: El XAML y los controles de WinUI se proporcionan como parte del Windows App SDK, se ejecutan sobre el ABI de WinRT, es decir, el contrato IInspectable, y debajo está el fundamento de COM y el HWND de Win32. Bajo los relevos generacionales de los marcos de interfaz, este contrato subyacente no ha cambiado
    ui["WinUI (XAML, controles)"]
    sdk["Windows App SDK"]
    abi2["ABI de WinRT (IInspectable)"]
    base2["COM + Win32 (HWND)"]
    ui --> sdk
    sdk --> abi2
    abi2 --> base2

Figura 15: Debajo de WinUI está el ABI de WinRT, y más abajo aún COM clásico y Win32. Solo cambió el apilado; el fundamento es el mismo.

Mezclar con XAML Islands: comprobar las restricciones de cada generación

La estrategia de «mezclar solo controles WinUI en pantallas WPF/WinForms existentes» hay que evaluarla por separado para cada generación de XAML Islands.

Si planea una mezcla gradual, es más seguro no presuponer solo la mezcla a nivel de control. Organizar el plan en torno al uso de API WinRT a nivel de funcionalidad (sección 6) o a una separación a nivel de pantalla o de proceso es el enfoque más sólido a fecha de 2026.

8. Implicaciones para las aplicaciones de negocio — la migración completa y el uso selectivo son problemas distintos

«WinRT es un mundo nuevo y separado, así que usarlo significa tirar los activos existentes y reconstruir.» Esta idea falsa, que aparece en proyectos de desarrollo a medida, se disuelve una vez que se parte en dos.

Los activos COM existentes y WinRT pueden coexistir

A una aplicación WPF que usa automatización COM de Excel, hospeda controles ActiveX y llama a componentes COM internos se le pueden añadir API WinRT. No es ninguna acrobacia especial, porque se combinan funciones sobre el mismo fundamento COM.

Para las notificaciones toast, por ejemplo, establezca el TFM para referenciar la API y cumpla las condiciones de registro para mostrar notificaciones. Para que esto último no se olvide, la sección 9 lo expone vía por vía. En C++/WinRT, las interfaces WinRT y COM clásicas se pueden tratar con los mismos mecanismos, winrt::com_ptr y winrt::implements.²¹

Estimar por separado la renovación de interfaz y la adición de funciones

«¿Migrar la interfaz por completo a WinUI?» y «¿Usar API WinRT solo donde haga falta?» son decisiones que difieren en escala, duración y riesgo.

Una migración completa de interfaz es un problema de elección de marco que depende de los activos de pantalla, los controles de terceros y la organización de desarrollo. Tratamos esa decisión en Cómo elegir entre WinForms, WPF y WinUI. El uso selectivo de API WinRT, en cambio, es una mejora pequeña que se puede empezar hoy en una aplicación existente.

Para un proyecto que solo quiere notificaciones toast, no hace falta estimar una migración completa de interfaz. A la inversa, no hace falta aplazar el uso de API WinRT «porque no vamos a migrar a WinUI».

flowchart TB
    accTitle: La migración completa y el uso selectivo son decisiones distintas
    accDescr: Una migración completa de interfaz a WinUI es una gran decisión de elección de marco que depende de los activos de pantalla y de la organización, mientras que el uso selectivo de API WinRT es una decisión pequeña que se puede añadir hoy a una aplicación WPF o WinForms existente con un ajuste de TFM o similar; considere las dos por separado sin confundirlas
    goal["Querer usar funciones nuevas de Windows"]
    goal --> big["Migración completa de interfaz (decisión grande)"]
    goal --> small["Uso selectivo de API WinRT (decisión pequeña)"]
    big -.-> dep["Depende de los activos de pantalla y de la organización"]
    small -.-> today["Se puede añadir a la aplicación existente hoy"]

Figura 16: Hay dos caminos hacia «funciones nuevas», y confundirlos desvía tanto la estimación como la decisión.

9. Tabla de decisión — la versión WinRT de conservar, envolver, reemplazar

Elegir solo los cambios que cada situación necesita

Como extensión de la tabla de decisión de ActiveX, aquí hay una guía de decisión por situación del lado WinRT.

Las notificaciones toast no aparecen solo con un ajuste de TFM

El ajuste que hace la API invocable y el registro que hace aparecer una notificación son dos cosas distintas. Cuando «la compilación funciona pero no aparece ninguna notificación», compruebe no solo el código de llamada, sino la vía en uso, la forma de empaquetado y si el proceso está elevado.

Al usar el ToastNotificationManager clásico

Para una aplicación sin empaquetar y sin identidad de paquete, el requisito previo es registrar un acceso directo del menú Inicio con un AppUserModelID (AUMID) asignado. Sin él no se pueden mostrar toasts.²⁷

Una aplicación empaquetada con MSIX o similar no necesita este registro manual, porque la identidad de paquete proporciona el AUMID.

Al usar AppNotificationManager del Windows App SDK

En esta vía recomendada actualmente se exigen añadir el Windows App SDK y llamar a Register() al arrancar. Más allá, las condiciones se ramifican según la forma de empaquetado.²⁸

Además, en la vía del Windows App SDK las notificaciones desde un proceso elevado a administrador no están admitidas. Show falla en silencio sin lanzar. En una aplicación que necesita elevación, plantee separar las notificaciones en un proceso no elevado.²⁸

Los detalles de implementación en torno al registro se tratan en la guía de implementación de iconos de bandeja y notificaciones.

flowchart TB
    accTitle: Las dos vías de las notificaciones toast y el registro que cada una necesita
    accDescr: Para mostrar una notificación toast desde una aplicación de escritorio, la vía clásica ToastNotificationManager se ramifica según si la aplicación está empaquetada: una aplicación sin empaquetar debe pasar por el registro de un acceso directo del menú Inicio con un AppUserModelID asignado, mientras que para una empaquetada la identidad de paquete proporciona el AppUserModelID. En la vía AppNotificationManager del Windows App SDK, además de añadir el SDK y llamar a Register al arrancar, una aplicación sin empaquetar debe desplegar el runtime en cada PC de destino y una aplicación empaquetada con MSIX debe declarar un activador COM en el manifiesto antes de poder seguir. La vía del Windows App SDK se ramifica además según si el proceso está elevado: las notificaciones desde un proceso elevado a administrador no están admitidas y Show falla en silencio sin lanzar, así que en esta vía una notificación solo se muestra para un proceso no elevado, y una aplicación que necesita elevación separa las notificaciones en un proceso no elevado
    want["Querer mostrar un toast"]
    want --> c1["Clásico: ToastNotificationManager"]
    want --> c2["WASDK: AppNotificationManager"]
    c1 --> q1{"¿Empaquetada?"}
    q1 -->|"No"| s1["Registrar un acceso directo AUMID"]
    q1 -->|"Sí"| s2["La identidad proporciona el AUMID"]
    c2 --> r2["Añadir el SDK + Register()"]
    r2 --> q2{"¿Empaquetada?"}
    q2 -->|"No"| s3["Desplegar el runtime"]
    q2 -->|"Sí"| s4["Declarar COM en el manifiesto"]
    s1 --> shown["Se muestra la notificación"]
    s2 --> shown
    s3 --> elev{"¿Proceso elevado?"}
    s4 --> elev
    elev -->|"No"| shown
    elev -->|"Sí"| fail["No admitido: Show falla en silencio"]
    fail -.-> comp["Separar las notificaciones en un proceso no elevado"]

Figura 17: En cualquiera de las dos vías, la notificación aparece solo después de satisfacer los requisitos previos de la forma de empaquetado. En la vía del Windows App SDK, incluso con todos los requisitos previos en su sitio, no se muestra nada desde un proceso elevado.

Por último, volver a conservar, envolver, reemplazar

¿Necesita una función nueva, o quiere renovar la interfaz en sí? Volver a esta pregunta permite decidir por separado sobre el uso de WinRT y sobre el reemplazo de los activos existentes.

flowchart TB
    accTitle: Flujo de decisión sobre cómo encajan los activos existentes y WinRT
    accDescr: Partiendo de una aplicación de escritorio existente, un flujo de decisión por pasos: si no se necesita una función nueva de Windows, conservar; si se necesita una función, envolver con uso selectivo de API WinRT (atentos a los puntos de atasco de la sección 6 de HWND, identidad de paquete e inicialización del subproceso); y solo cuando la interfaz en sí necesite renovarse, plantear reemplazarla por WinUI
    start["Aplicación de escritorio existente"] --> q2{"¿Qué se necesita?"}
    q2 -->|"El estado actual basta"| keep2["Conservar (mantener tal cual)"]
    q2 -->|"Una función nueva"| wrap2["Envolver (uso selectivo de API WinRT)"]
    q2 -->|"Renovación de interfaz"| rep["Reemplazar (evaluar WinUI)"]
    wrap2 -.-> note2["Atención a HWND, identidad, inicialización (sección 6)"]

Figura 18: La misma estructura «conservar, envolver, reemplazar» que la tabla de decisión de ActiveX se aplica de inmediato del lado WinRT.

10. Resumen

WinRT no es un entorno de ejecución nuevo, cortado de COM. Es un fundamento de API que combina el contrato binario de COM con metadatos y proyecciones a cada lenguaje.

Aunque la superficie sea una API C# o C++ natural, debajo hay llamadas COM a través de vtables y HRESULT. Por eso entender el paso de HWND en el escritorio, la identidad de paquete y STA/MTA con la inicialización del subproceso hace más fácil aislar los incidentes de WinRT.

El esfuerzo de llevar el desarrollo principal de WinUI a la vista se anunció en el verano de 2025 como un enfoque por fases. A la fecha de publicación de este artículo la documentación oficial también dice «built in the open», pero el contrato debajo, IUnknown → IInspectable, no ha cambiado.²²⁹

La conclusión para las aplicaciones de negocio es la misma. Los activos COM/ActiveX existentes y WinRT pueden coexistir. No confundir una migración completa de interfaz con el uso selectivo de API WinRT es lo que protege la precisión de las estimaciones y las decisiones.

Los documentos compuestos de la década de 1990 vistos en el artículo OLE y el WinUI de hoy se sostienen sobre el mismo IUnknown. Conocer COM no es meramente «estar versado en lo legado». Es poder leer el fundamento de Windows hoy.

Artículos relacionados

• Qué es COM — por qué el diseño de Windows COM sigue siendo hermoso hoy
• Qué son COM, ActiveX y OCX - Diferencias y relación explicadas
• Conocimientos básicos de STA/MTA en COM - El modelo de subprocesos y cómo evitar los bloqueos
• ActiveX / OCX: cómo tratarlos hoy — tabla de decisión para mantener, envolver o reemplazar
• Cómo elegir entre WinForms, WPF y WinUI: tabla de decisión práctica
• What Is an OLE Object? — How Embedding and Linking Work, and the Pitfalls in Business Documents
• Cómo usar una DLL de .NET 8 desde VBA con tipado - Exposición COM y TLB con dscom

Áreas de consultoría relacionadas

KomuraSoft LLC se ocupa del desarrollo de componentes COM y del mantenimiento, la modificación y el reemplazo de aplicaciones de negocio para Windows que incluyen activos COM. Puede consultarnos desde la etapa en la que el contenido de este artículo es exactamente el tema en juego: «queremos notificaciones toast y selectores sin dejar WPF», «llamar a una API WinRT se detuvo con una excepción», «queremos decidir si migrar a WinUI o aprovechar los activos existentes».

• Desarrollo de aplicaciones para Windows
• Desarrollo de componentes COM
• Consultoría técnica y revisión de diseño
• Contacto

Referencias

Artículos relacionados

Artículos recientes con las mismas etiquetas para profundizar en temas cercanos.

Temas relacionados

Estas páginas sitúan el tema en un contexto más amplio de servicios y decisiones.

Servicios relacionados con este tema

El artículo está directamente relacionado con los siguientes servicios.

Preguntas frecuentes

Preguntas habituales en las consultas sobre el tema del artículo.

¿Es WinRT un runtime administrado como .NET?

No. WinRT (Windows Runtime) no es un entorno de ejecución con una máquina virtual o un recolector de basura; es un ABI (un contrato binario) construido sobre COM. La propia documentación de Microsoft afirma con claridad que "The Windows Runtime is based on COM", y cada interfaz WinRT exige IInspectable, que deriva de IUnknown. Cada llamada sigue siendo una llamada COM a través de una vtable, basada en el recuento de referencias (AddRef/Release) y QueryInterface. El nombre ".winmd" y el encaje cercano con .NET hacen fácil tomar WinRT por un entorno administrado, pero un .winmd es un archivo de metadatos que toma prestado el mismo formato físico que ECMA-335, y los archivos .winmd que proporciona el sistema no contienen código ejecutable. Que C# pueda llamarlo con tanta naturalidad se debe a que una proyección de lenguaje genera una vista C# a partir de esos metadatos.

Oigo que UWP ya no es lo principal. ¿Sigue teniendo sentido aprender WinRT?

Sí. UWP, el modelo de aplicación, y WinRT, el fundamento de API, son dos cosas distintas. Incluso después de que UWP se recortara, la mayoría de las API WinRT siguen ofreciéndose de forma que las aplicaciones de escritorio WPF, WinForms y Win32 puedan llamarlas, y muchas de las capacidades de Windows hoy, como las notificaciones toast, Compartir, Bluetooth y OCR, se exponen como API WinRT. Además, WinUI (Windows App SDK), el marco de interfaz nativo que Microsoft recomienda actualmente, está construido sobre el ABI de WinRT. En otras palabras, la maquinaria de WinRT (IInspectable, .winmd, proyecciones de lenguaje) no es un vestigio de UWP; es precisamente el fundamento del desarrollo actual de aplicaciones para Windows.

¿Puede una aplicación WPF o WinForms llamar a API WinRT?

Sí. En .NET 6 o posterior basta con establecer el TargetFramework del proyecto en un TFM con versión de sistema operativo Windows, por ejemplo net8.0-windows10.0.19041.0; entonces se referencian los ensamblados de proyección del Windows SDK y las API WinRT de los espacios de nombres Windows.* se pueden llamar directamente desde C#. En C++, añada el paquete NuGet Microsoft.Windows.CppWinRT y use C++/WinRT con C++17 o posterior. Hay, no obstante, tres puntos de atasco. Primero, las clases de interfaz que presuponen un CoreWindow, como selectores y cuadros de diálogo, necesitan que el HWND de la ventana propietaria se pase mediante IInitializeWithWindow antes de mostrarlas (la excepción es DataTransferManager de la interfaz de Compartir: en lugar de IInitializeWithWindow usa el IDataTransferManagerInterop dedicado, una vía distinta que pasa el HWND a ShowShareUIForWindow). Segundo, algunas API, como el historial de notificaciones y las listas de accesos directos, exigen identidad de paquete (empaquetado MSIX o un paquete con ubicación externa). Tercero, un subproceso que trata objetos WinRT debe inicializarse primero. En código nativo, indique el modelo de concurrencia STA/MTA con winrt::init_apartment o RoInitialize (en aplicaciones C# WPF/WinForms el runtime suele encargarse). Tenga en cuenta que las API que dependen de CoreWindow o ApplicationView en sí no se pueden usar en absoluto desde aplicaciones de escritorio.

Llamar a un selector como FolderPicker desde una aplicación de escritorio lanza una excepción. ¿Por qué?

Porque algunas clases WinRT de selector y de cuadro de diálogo se diseñaron para mostrarse en un CoreWindow de UWP. Una aplicación de escritorio no tiene CoreWindow, así que hay que indicar explícitamente la ventana propietaria antes de mostrar el objeto. En concreto, primero obtenga el HWND de la ventana propietaria (WinRT.Interop.WindowNative.GetWindowHandle para una Window de WinUI, WindowInteropHelper para WPF, la propiedad Handle del formulario para WinForms) y, en C#, páselo al selector con WinRT.Interop.InitializeWithWindow.Initialize. En C++/WinRT, haga QueryInterface del objeto a IInitializeWithWindow (as<IInitializeWithWindow>()) y llame a Initialize(hwnd). Sin esta inicialización, la llamada lanza o falla en silencio. Tenga en cuenta que los selectores más nuevos del Windows App SDK (Microsoft.Windows.Storage.Pickers) se rediseñaron para recibir un WindowId en el constructor, lo que hace innecesario este patrón de inicialización (pero, como son API del Windows App SDK, un ajuste de TFM no basta: hay que añadir el SDK y, para una aplicación sin empaquetar, desplegar e inicializar el runtime en las máquinas de destino).

He oído que el desarrollo de WinUI se ha abierto en GitHub. ¿Hay que tirar las aplicaciones WPF/WinForms existentes?

No hay que precipitarse. Abrir el desarrollo principal de WinUI es una declaración de dirección, de que Microsoft invierte en serio en su marco nativo, no un aviso de fin de los marcos existentes. WPF y WinForms siguen admitidos hoy como parte de .NET. Divida la decisión en dos. Una es si migrar el marco de interfaz, una decisión grande que depende del tamaño de los activos de pantalla, los controles de terceros y la organización de desarrollo. La otra es si usar API WinRT de forma selectiva desde la aplicación existente, lo que puede empezar hoy con un ajuste de TFM. Tenga en cuenta que el TFM solo hace las API invocables; las notificaciones toast, por ejemplo, requieren un registro además de la llamada (en la vía clásica, una aplicación sin empaquetar debe registrar un acceso directo con AppUserModelID — una empaquetada no, porque la identidad de paquete proporciona el AppUserModelID; en la vía del Windows App SDK hay que añadir el SDK — y para una aplicación sin empaquetar también instalar el runtime del Windows App SDK en cada PC de destino — y llamar a Register() de AppNotificationManager, mientras que en una aplicación empaquetada con MSIX el registro automático de Register() no funciona y además hay que declarar un activador COM en Package.appxmanifest). Además, en la vía del Windows App SDK las notificaciones desde un proceso elevado a administrador no están admitidas, y Show falla en silencio sin lanzar — una aplicación que necesita elevación debería plantearse separar las notificaciones en un proceso no elevado. Aun así, si solo quiere notificaciones toast, no hace falta migrar a WinUI. Tenga en cuenta que mezclar controles WinUI en pantallas WPF/WinForms existentes (XAML Islands) exige distinguir generaciones. Los Islands de generación UWP se detuvieron en .NET Core 3.x para WPF/WinForms, y para la generación WinUI 3 la API de hospedaje XAML del Windows App SDK (DesktopWindowXamlSource) es usable desde WPF/WinForms, pero no hay controles contenedor cómodos y la carga de implementación es alta, así que evaluarlo con cautela es por ahora el camino seguro.

Perfil del autor

Página de presentación del autor del artículo.

Go Komura

Representante de KomuraSoft LLC

Especializado en desarrollo de software para Windows, consultoría técnica e investigación de fallos, sobre todo en proyectos con sistemas existentes y errores difíciles de reproducir.