Uso del tiempo de ejecución del SDK de Windows para aplicaciones empaquetadas con ubicación externa o sin empaquetar

  • Artículo

Nota

Si la aplicación está instalada mediante la tecnología MSIX, consulte SDK de Aplicaciones para Windows guía de implementación para aplicaciones empaquetadas dependientes del marco.

Si la aplicación no está instalada mediante MSIX (es decir, se empaqueta con una ubicación externa o sin empaquetar), debe inicializar el SDK de Aplicaciones para Windows para su uso antes de poder llamar a SDK de Aplicaciones para Windows características como WinUI 3, Ciclo de vida de la aplicación, MRT Core y DWriteCore. La aplicación debe inicializar el entorno de ejecución de SDK de Aplicaciones para Windows antes de usar cualquier otra característica del SDK de Aplicaciones para Windows.

  • A partir de SDK de Aplicaciones para Windows 1.0, que se puede realizar automáticamente cuando la aplicación se inicia a través de la inicialización automática (establece la propiedad <WindowsPackageType>None</WindowsPackageType>del proyecto ). Para obtener una demostración, consulte Creación del primer proyecto de WinUI 3.
  • Pero si tiene necesidades avanzadas (por ejemplo, controlar errores mostrando su propia interfaz de usuario personalizada o registro, o si necesita cargar una versión del SDK de Aplicaciones para Windows diferente de la versión con la que ha creado), continúe leyendo este tema. En esos escenarios, en lugar de la inicialización automática, puede llamar a la API de arranque explícitamente.

Cualquiera de las dos técnicas anteriores permite que una aplicación que no use MSIX tome una dependencia dinámica de la SDK de Aplicaciones para Windows en tiempo de ejecución.

Para obtener información general sobre las dependencias dinámicas, consulte Paquetes de marcos MSIX y dependencias dinámicas.

En segundo plano y no participar en la inicialización automática del módulo

El código generado por la WindowsPackageType propiedad mencionada anteriormente aprovecha los inicializadores de módulo para llamar a la API del programa previo. El programa previo realiza el trabajo pesado para encontrar el SDK de Aplicaciones para Windows y permitir que el proceso actual lo use. El código generado controla la inicialización y el apagado. Puede controlar el comportamiento de la inicialización con las siguientes propiedades del proyecto:

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Use las opciones predeterminadas.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • No use ninguna opción.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Llame a DebugBreak() si se produce un error solo si un depurador está asociado al proceso.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Realice un error rápido si se produce un error.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Pida al usuario que adquiera el entorno de ejecución de SDK de Aplicaciones para Windows si no se encuentra uno coincidente.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Si se llama a en un proceso con identidad de paquete (de lo contrario, se produce un error y se devuelve un error).

Si quieres que la aplicación tenga control explícito, puedes llamar directamente a boostrapper API al principio del inicio de la aplicación. En ese caso, no necesita WindowsPackageType en el archivo del proyecto.

Nota

Además de la inicialización automática y la API de arranque, el SDK de Aplicaciones para Windows también proporciona una implementación de la API de dependencia dinámica. Esta API permite que las aplicaciones sin empaquetar tomen una dependencia de cualquier paquete de marco (no solo el paquete de marco de SDK de Aplicaciones para Windows) y la API de arranque la usa internamente. Para obtener más información sobre la API de dependencia dinámica, consulte Uso de la API de dependencia dinámica para hacer referencia a paquetes MSIX en tiempo de ejecución.

No participar en la inicialización automática de módulos (o en)

La propiedad <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> project deshabilita la inicialización automática del módulo descrita anteriormente (no se llama a la API de programa previo). Esto permite a la aplicación asumir la responsabilidad y llamar directamente a la API del programa previo.

A partir de la versión 1.2 del SDK de Aplicaciones para Windows (desde el canal estable), la inicialización automática del módulo solo se aplica a los proyectos que generan un ejecutable (es decir, la propiedad del proyecto OutputType se establece en Exe o WinExe). Esto es para evitar la adición de inicializadores automáticos en archivos DLL de biblioteca de clases y otros no ejecutables de forma predeterminada. Si necesita un inicializador automático en un no ejecutable (por ejemplo, un archivo DLL de prueba cargado por un ejecutable de proceso de host que no inicializa el programa previo), puede habilitar explícitamente un inicializador automático en el proyecto con <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Uso de la API del programa previo

Importante

La función MddBootstrapInitialize2 mencionada a continuación está disponible a partir de la versión 1.1.

La API del programa previo consta de tres funciones de C/C++ que se declaran en el archivo de encabezado mddbootstrap.h en el SDK de Aplicaciones para Windows: MddBootstrapInitialize, MddBootstrapInitialize2 y MddBootstrapShutdown. La biblioteca del programa previo proporciona esas funciones en el SDK de Aplicaciones para Windows. Esa biblioteca es un pequeño archivo DLL que debe distribuir con la aplicación; no forma parte del propio paquete de marco.

MddBootstrapInitialize2

Esta función inicializa el proceso de llamada para usar la versión del paquete de marco de SDK de Aplicaciones para Windows que mejor coincida con los criterios que se pasan a los parámetros de función. Normalmente, esto da como resultado hacer referencia a la versión del paquete de marco que coincide con el SDK de Aplicaciones para Windows paquete NuGet que está instalado. Si varios paquetes cumplen los criterios, se selecciona el mejor candidato. Esta función debe ser una de las primeras llamadas en el inicio de la aplicación para asegurarse de que el componente del programa previo puede inicializar correctamente el SDK de Aplicaciones para Windows y agregar la referencia en tiempo de ejecución al paquete de marco.

La API del programa previo usa la API de dependencias dinámicas para agregar el paquete de marco del entorno de ejecución de SDK de Aplicaciones para Windows al gráfico de paquetes del proceso actual y, de lo contrario, habilitar el acceso al paquete.

Esta función también inicializa el Administrador de duración de dependencia dinámica (DDLM). Ese componente proporciona infraestructura para evitar que el sistema operativo siga el paquete de marco de SDK de Aplicaciones para Windows mientras se usa en una aplicación sin empaquetar.

MddBootstrapShutdown

Esta función quita los cambios en el proceso actual que realizó una llamada a MddBootstrapInitialize. Después de llamar a esta función, la aplicación ya no puede llamar a SDK de Aplicaciones para Windows API, incluida la API de dependencias dinámicas.

Esta función también apaga el Administrador de duración de dependencia dinámica (DDLM) para que Windows pueda atender el paquete de marco según sea necesario.

Contenedor de .NET para la API de programa previo

Aunque puede llamar a la API de programa previo de C/C++ directamente desde aplicaciones .NET, que requiere el uso de la invocación de plataforma para llamar a las funciones. En SDK de Aplicaciones para Windows 1.0 y versiones posteriores, hay disponible un contenedor de .NET para la API de programa previo en el Microsoft.WindowsAppRuntime.Bootstrap.Net.dll ensamblado. Ese ensamblado proporciona una API más sencilla y natural para que los desarrolladores de .NET accedan a la funcionalidad del programa previo. La clase Bootstrap proporciona funciones estáticas Initialize, TryInitialize y Shutdown que encapsulan las llamadas a las funciones MddBootstrapInitialize y MddBootstrapShutdown para los escenarios más comunes. Para ver un ejemplo que muestra cómo usar el contenedor de .NET para la API de programa previo, consulte las instrucciones de C# en Tutorial: Uso de la API del programa previo en una aplicación empaquetada con ubicación externa o desempaquetada que usa el SDK de Aplicaciones para Windows.

Para obtener más información sobre el contenedor de .NET para la API de programa previo, consulte estos recursos:

  • API de C# de arranque.
  • Sección 6.1.4 de la especificación de dependencias dinámicas.
  • Bootstrap.cs: la implementación código abierto del contenedor de .NET para la API del programa previo.

Contenedor de C++ para la API de programa previo

Hay disponible un contenedor de C++ para la API de programa previo a partir de SDK de Aplicaciones para Windows 1.1.

Consulte Bootstrapper C++ API (API de C++).

Declaración de la compatibilidad del sistema operativo en el manifiesto de aplicación

Para declarar la compatibilidad del sistema operativo (SO) y evitar el SDK de Aplicaciones para Windows el comportamiento predeterminado de Windows 8 (y posibles bloqueos), puede incluir un manifiesto de aplicación en paralelo con el empaquetado con la ubicación externa o la aplicación sin empaquetar. Consulte Manifiestos de aplicación (es el archivo que declara elementos como el reconocimiento de PPP y se inserta en .exe de la aplicación durante la compilación). Esto puede ser un problema si va a agregar SDK de Aplicaciones para Windows compatibilidad con una aplicación existente, en lugar de crear una nueva a través de una plantilla de proyecto de Visual Studio.

Si aún no tiene un manifiesto de aplicación en paralelo en el proyecto, agregue un nuevo archivo XML al proyecto y asígnele el nombre recomendado en Manifiestos de aplicación. Agregue al archivo el elemento de compatibilidad y los elementos secundarios que se muestran en el ejemplo siguiente. Estos valores controlan el nivel de peculiaridades de los componentes que se ejecutan en el proceso de la aplicación.

Reemplace el atributo Id del elemento maxversiontested por el número de versión de Windows de destino (debe ser 10.0.17763.0 o una versión posterior). Tenga en cuenta que establecer un valor superior significa que las versiones anteriores de Windows no ejecutarán la aplicación correctamente porque cada versión de Windows solo conoce las versiones anteriores. Por lo tanto, si quieres que la aplicación se ejecute en Windows 10, versión 1809 (10.0; Compilación 17763), debe dejar el valor 10.0.17763.0 tal como está o agregar varios elementos maxversiontested para los distintos valores que admite la aplicación.

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>