Compartir a través de

C#/WinRT

C#/WinRT es un kit de herramientas empaquetado por NuGet que proporciona compatibilidad con proyección de Windows Runtime (WinRT) para el lenguaje C#. Un ensamblado de proyección es un ensamblado de interoperabilidad, que permite programar API de WinRT de forma natural y familiar para el lenguaje de destino. La proyección de C#/WinRT oculta los detalles de la interoperabilidad entre las interfaces de C# y WinRT, y proporciona asignaciones de muchos tipos de WinRT a equivalentes de .NET adecuados, como cadenas, URI, tipos de valores comunes y colecciones genéricas.

Actualmente, C#/WinRT proporciona compatibilidad con el consumo de API de WinRT mediante el uso de Identificadores de Marcos de Trabajo de Destino (TFMs) en .NET. Al establecer el TFM con una versión específica de Windows SDK, se agregan referencias a los ensamblados de proyección y tiempo de ejecución de Windows SDK generados por C#/WinRT.

El paquete NuGet de C#/WinRT permite crear y hacer referencia a sus propios ensamblados de interoperabilidad de WinRT para consumidores de .NET. La versión más reciente de C#/WinRT también incluye una previsualización de la creación de tipos de WinRT en C#.

Para obtener más información, consulte el repositorio de GitHub de C#/WinRT.

Motivación para C#/WinRT

.NET (anteriormente conocido como .NET Core) es un entorno de ejecución multiplataforma de código abierto que se puede usar para compilar aplicaciones de dispositivo, nube e IoT.

Las versiones anteriores de .NET Framework y .NET Core tenían conocimientos integrados de WinRT, una tecnología específica de Windows. Para admitir los objetivos de portabilidad y eficiencia de .NET 6+, extrajimos la compatibilidad con la proyección de WinRT del compilador y el entorno de ejecución de .NET y la trasladamos al kit de herramientas de C#/WinRT (consulte Compatibilidad integrada con WinRT se ha quitado de .NET). El objetivo de C#/WinRT es proporcionar paridad con la compatibilidad integrada con WinRT proporcionada por versiones anteriores del compilador de C# y el entorno de ejecución de .NET. Para obtener más información, consulte Mapeos de .NET de tipos de Windows Runtime.

C#/WinRT también admite componentes en el SDK de aplicaciones de Windows, incluido WinUI. Windows App SDK eleva los controles nativos de la interfaz de usuario de Microsoft y otros componentes nativos fuera del sistema operativo. Esto permite a los desarrolladores de aplicaciones usar los controles y componentes más recientes en Windows 10, versión 1809 y versiones posteriores.

Por último, C#/WinRT es un kit de herramientas general y está pensado para admitir otros escenarios en los que la compatibilidad integrada con WinRT no está disponible en el compilador de C# o en tiempo de ejecución de .NET.

Novedades

Las últimas versiones de C#/WinRT se pueden encontrar en nuestra página de notas de la versión en el repositorio de Github.

Usage

El paquete NuGet de C#/WinRT se puede usar para generar proyecciones de C# (también denominadas ensamblados de interoperabilidad) a partir de componentes de WinRT y en Creación de componentes de C#/WinRT. Para obtener más información sobre los escenarios de uso de C#/WinRT, consulte la guía de uso de nuestro repositorio.

Generación y distribución de un ensamblado de interoperabilidad

Las API de WinRT se definen en archivos de metadatos de Windows (WinMD). El paquete NuGet de C#/WinRT (Microsoft.Windows.CsWinRT) incluye el compilador de C#/WinRT, cswinrt.exe, que puede usar para procesar archivos WinMD y generar código de C# de .NET. C#/WinRT compila estos archivos de origen en un ensamblado de interoperabilidad, similar a cómo C++/WinRT genera encabezados para la proyección del lenguaje C++. Después, puede distribuir el ensamblado de interoperabilidad de C#/WinRT junto con el ensamblado de implementación para que las aplicaciones .NET hagan referencia, normalmente como un paquete NuGet.

Para obtener más información sobre cómo generar y distribuir un ensamblado de interoperabilidad, consulte Generación de una proyección de C# a partir de un componente de C++/WinRT, distribuir como nuGet para aplicaciones .NET.

Hacer referencia a un ensamblado de interoperabilidad

Normalmente, los proyectos de aplicación hacen referencia a los ensamblados de interoperabilidad de C#/WinRT. Pero también se puede hacer referencia a ellos a su vez mediante ensamblados de interoperabilidad intermedios. Por ejemplo, el ensamblado de interoperabilidad de WinUI haría referencia al ensamblado de interoperabilidad de Windows SDK.

Si distribuye un componente de WinRT de terceros sin un ensamblado de interoperabilidad oficial, un proyecto de aplicación puede seguir el procedimiento para generar un ensamblado de interoperabilidad para generar sus propios orígenes de proyección privada. No se recomienda este enfoque, ya que puede producir proyecciones en conflicto del mismo tipo dentro de un proceso. El empaquetado de NuGet, siguiendo el esquema de control de versiones semántico , está diseñado para evitarlo. Se prefiere un ensamblado de interoperabilidad oficial de terceros.

Compatibilidad integrada con tipos WinRT (versión preliminar)

A partir de C#/WinRT versión 1.4.1, se incluye compatibilidad para incrustar las fuentes de proyección y de tiempo de ejecución del SDK de Windows en el resultado de su biblioteca o aplicación para .NET y .NET Standard 2.0. Esto es útil en los casos en los que el uso de tipos de Windows SDK es independiente. La compatibilidad insertada quita las dependencias de WinRT.Runtime.dll y Microsoft.Windows.SDK.NET.dll, lo que reduce el tamaño de salida de la biblioteca o la aplicación. También permite a los desarrolladores de bibliotecas proporcionar compatibilidad de nivel inferior y elimina la necesidad de varios destinos.

Para obtener más información, consulte la documentación insertada de C#/WinRT en nuestro repositorio.

Activación de tipos de WinRT

C#/WinRT admite la activación de tipos de WinRT hospedados por el sistema operativo, así como componentes de terceros como Win2D. La compatibilidad con la activación de componentes de terceros en una aplicación de escritorio está habilitada con el registro de activación gratuita de WinRT (consulta Mejorar las aplicaciones de escritorio no empaquetadas con componentes de Windows Runtime), disponibles en Windows 10, versión 1903 y posteriores. Los componentes nativos de C++ deben establecer la propiedad Compatible para escritorio de Windows en True a través de las propiedades del proyecto o el .vcxproj archivo, para hacer referencia y reenviar los archivos binarios microsoft.VCLibs.Desktop a las aplicaciones que consumen. De lo contrario, el paquete de reenviadores de VCRT será necesario por las aplicaciones que lo utilizan si el componente está diseñado solo para aplicaciones UWP.

C#/WinRT también proporciona una ruta de acceso alternativa de activación si Windows no puede activar el tipo como se ha descrito anteriormente. En este caso, C#/WinRT intenta localizar una DLL de implementación nativa basada en el nombre de tipo completo, quitando progresivamente los elementos. Por ejemplo, la lógica de respaldo intentaría activar el tipo Contoso.Controls.Widget desde los siguientes módulos, en el siguiente orden:

  1. Contoso.Controls.Widget.dll
  2. Contoso.Controls.dll
  3. Contoso.dll

C#/WinRT usa el orden de búsqueda alternativo LoadLibrary para buscar un archivo DLL de implementación. Una aplicación que se basa en este comportamiento de respaldo debe empaquetar la DLL de implementación junto con el módulo de la aplicación.

Errores comunes y solución de problemas

  • Error: "Metadatos de Windows no proporcionados o detectados".

    Puede especificar metadatos de Windows mediante la propiedad del <CsWinRTWindowsMetadata> proyecto, por ejemplo:

    <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>

    En C#/WinRT versión 1.2.1 y posteriores, esta propiedad tiene como valor predeterminado TargetPlatformVersion, que se deriva de la versión de Windows SDK especificada en la TargetFramework propiedad .

  • Error CS0246: No se encontró el nombre de tipo o espacio de nombres "Windows" (¿falta una directiva using o una referencia de ensamblado?)

    Para solucionar este error, edite la <TargetFramework> propiedad para tener como destino una versión específica de Windows, por ejemplo:

    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>

    Consulte la documentación sobre cómo llamar a las API de Windows Runtime para obtener más información sobre cómo especificar la <TargetFramework> propiedad .

  • System.InvalidCastException al convertir en una interfaz que tenga el atributo ComImport

    Al convertir un objeto en una interfaz que tenga el ComImport atributo , deberá usar el .As<> operador en lugar de usar una expresión de conversión explícita. Por ejemplo:

    someObject.As<SomeComImportInterface>

    Para obtener más información, consulte la guía de interoperabilidad COM.

  • System.Runtime.InteropServices.COMException: Clase no registrada (0x80040154 (REGDB_E_CLASSNOTREG))

    • Si ve esta excepción al consumir una proyección de C#/WinRT desde un componente de C++/WinRT, asegúrese de que el componente ha establecido la propiedad Compatible para escritorio de Windows en True a través de las propiedades del proyecto o a través del .vcxproj archivo.

Errores de control de versiones del SDK de .NET

Es posible que encuentre los siguientes errores o advertencias en un proyecto compilado con una versión anterior del SDK de .NET que cualquiera de sus dependencias.

Mensaje de error o advertencia Motivo
Advertencia MSB3277: se encontraron conflictos entre diferentes versiones de WinRT.Runtime o Microsoft.Windows.SDK.NET que no se pudieron resolver. Esta advertencia de compilación se produce al hacer referencia a una biblioteca que expone los tipos de Windows SDK en su superficie de API.
Error CS1705: El ensamblado 'AssemblyName1' usa 'TypeName' que tiene una versión superior a la del ensamblado al que se hace referencia 'AssemblyName2' Este error de compilación del compilador se produce al hacer referencia y consumir tipos expuestos de Windows SDK en una biblioteca.
System.IO.FileLoadException Este error en tiempo de ejecución puede producirse al llamar a determinadas API en una biblioteca que no expone los tipos de Windows SDK.

Para corregir estos errores, actualice el SDK de .NET a la versión más reciente. Al hacerlo, se asegurará de que las versiones de ensamblado de Windows SDK y runtime usadas por la aplicación sean compatibles con todas las dependencias. Estos errores pueden producirse con actualizaciones tempranas de mantenimiento o características en el SDK de .NET, ya que las correcciones en tiempo de ejecución pueden requerir actualizaciones en nuestras versiones de ensamblado.

Problemas conocidos

Los problemas conocidos y los cambios importantes se indican en el repositorio de GitHub de C#/WinRT.

Si encuentra algún problema funcional con el paquete NuGet de C#/WinRT, el compilador de cswinrt.exe o los orígenes de proyección generados, envíenos problemas a través de la página problemas de C#/WinRT.

Recursos adicionales

  • Last updated on