Compartir a través de

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 se instala 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), debes inicializar el SDK de Aplicaciones para Windows para usarlo 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 (establezca 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 de la SDK de Aplicaciones para Windows diferente de la versión con la que creó), continúe leyendo este tema. En esos escenarios, en lugar de la inicialización automática, puede llamar explícitamente a la API de arranque.

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 marco 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 del módulo para llamar a la API de arranque. 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 opciones.
  • <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 SDK de Aplicaciones para Windows tiempo de ejecución si no se encuentra uno coincidente.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Se realiza correctamente si se llama en un proceso con la identidad del 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 es necesario 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 en 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.

Cómo optar por no participar (o participar) en la inicialización automática del módulo

La propiedad <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> del proyecto deshabilita la inicialización automática del módulo descrita anteriormente (no se llama a la API de arranque). 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 producen 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 a archivos DLL de biblioteca de clases y otros archivos no ejecutables de forma predeterminada. Si necesita un inicializador automático en un archivo no ejecutable (por ejemplo, un archivo DLL de prueba cargado por un ejecutable de proceso de host que no inicialice el programa previo), puede habilitar explícitamente un inicializador automático en el proyecto con <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Uso de la API de programa previo

Importante

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

La API de arranque consta de tres funciones de C/C++ declaradas en el archivo de encabezado mddbootstrap.h en el SDK de Aplicaciones para Windows: MddBootstrapInitialize, MddBootstrapInitialize2 y MddBootstrapShutdown. La biblioteca de programa previo proporciona esas funciones en el SDK de Aplicaciones para Windows. Esa biblioteca es un archivo DLL pequeño 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 de arranque pueda inicializar correctamente el SDK de Aplicaciones para Windows y agregar la referencia en tiempo de ejecución al paquete de marco.

La API de arranque 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 dynamic Dependency Lifetime Manager (DDLM). Ese componente proporciona infraestructura para evitar que el sistema operativo de mantenimiento del paquete de marco de SDK de Aplicaciones para Windows mientras se usa en una aplicación desempaquetada.

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 dynamic Dependency Lifetime Manager (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 arranque 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 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 arranque, consulte las instrucciones de C# en Tutorial: Uso de la API de arranque 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 arranque, 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 de arranque.

Contenedor de C++ para la API de arranque

Hay disponible un contenedor de C++ para la API de arranque 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 que tenga como 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 correctamente la aplicación porque cada versión de Windows solo conoce las versiones anteriores. Por lo tanto, si quieres que tu 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>

Consulte también