Tutorial: Uso de la API de arranque en una aplicación empaquetada con ubicación externa o sin empaquetar que usa el Windows App SDK

En este artículo se muestra cómo configurar una aplicación que no está instalada mediante MSIX (es decir, se empaqueta con una ubicación externa o sin empaquetar) para usar la API de arranque para que cargue explícitamente el entorno de ejecución de Windows App SDK y llame a Windows App SDK API. Las aplicaciones que no están instaladas a través de MSIX incluyen aplicaciones empaquetadas con ubicación externa y aplicaciones sin empaquetar.

Importante

A partir de Windows App SDK 1.0, el enfoque predeterminado para cargar Windows App SDK desde una aplicación empaquetada con una ubicación externa o una aplicación sin empaquetar es usar auto-initialization a través de la propiedad del proyecto <WindowsPackageType> y también realizar cambios de configuración adicionales. Para conocer los pasos implicados en la inicialización automática en el contexto de un proyecto de WinUI 3, consulte Crear su primer proyecto de WinUI. O bien, si tiene un proyecto existente que no es WinUI, consulte Use el SDK de Aplicaciones Windows en un proyecto existente.

Si tiene necesidades avanzadas (como el control de errores personalizado o para cargar una versión específica del Windows App SDK), puede llamar explícitamente a la API de arranque. Y ese es el enfoque que muestra este tema. Además, para obtener más información, consulta Utilice el entorno de tiempo de ejecución de Windows App SDK para aplicaciones empaquetadas con ubicación externa o sin empaquetar.

En este tema se muestra cómo llamar explícitamente a la API de arrancador desde una aplicación de consola básica, pero los pasos se aplican a cualquier aplicación de escritorio sin empaquetar que use Windows App SDK.

Antes de completar este tutorial, se recomienda revisar la arquitectura Runtime para obtener más información sobre la Framework dependencia de paquete que la aplicación toma cuando usa la Windows App SDK y los componentes adicionales necesarios para trabajar en una ubicación externa o una aplicación sin empaquetar.

Requisitos previos

1. Instalar herramientas para el Windows App SDK.
2. Asegúrese de que todas las dependencias para empaquetadas con ubicación externa y aplicaciones sin empaquetar están instaladas (consulte Windows App SDK guía de implementación para aplicaciones dependientes del marco empaquetadas con ubicación externa o sin empaquetar). Una manera sencilla de hacer eso es ejecutar el instalador de runtime de Windows App SDK.

Instrucciones

Puede seguir este tutorial mediante un project de C# o C++.

Nota:

Las dependencias dinámicas y las API de arranque producen un error cuando se les llama mediante un proceso con privilegios elevados. Como resultado, Visual Studio no se debe iniciar con privilegios elevados. Consulte Dynamic Dependencies no admite la elevación #567 para obtener más información.

C#

Siga estas instrucciones para configurar una project winUI de C# empaquetada con ubicación externa o sin empaquetar.

1. En Visual Studio, cree un nuevo proyecto de C# Console App. Nombre el proyecto DynamicDependenciesTest. Después de crear el proyecto, debería tener una aplicación de consola de C# "Hello, World!".

2. A continuación, configure el proyecto.

   1. En Solution Explorer, haga clic con el botón derecho en el proyecto y elija Editar archivo de proyecto.
   2. Reemplace el valor del elemento TargetFramework por un moniker de la plataforma de destino. Por ejemplo, use lo siguiente si la aplicación tiene como destino Windows 10, versión 2004.

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

   1. Guarde y cierre el archivo del proyecto.

3. Cambie la plataforma de la solución a x64. El valor predeterminado de un .NET project es AnyCPU, pero WinUI no admite esa plataforma.

   1. Seleccione Build>Configuration Manager.
   2. Seleccione la lista desplegable que hay bajo Plataforma de solución activa y haga clic en Nueva para abrir el cuadro de diálogo Nueva plataforma de solución.
   3. En el menú desplegable que hay bajo Escriba o seleccione la nueva plataforma, seleccione x64.
   4. Haga clic en Aceptar para cerrar el cuadro de diálogo Nueva plataforma de solución.
   5. En Configuration Manager, haga clic en Close.

4. Instale el paquete NuGet Windows App SDK en el project.

   1. En Solution Explorer, haga clic con el botón derecho en el nodo Dependencies y elija Administrar paquetes Nuget.
   2. En la ventana NuGet Package Manager, seleccione la pestaña Browse e instale el paquete Microsoft.WindowsAppSDK.

5. Ya está listo para usar la API de arranque (consulte Use el entorno de ejecución de Windows App SDK para aplicaciones empaquetadas con ubicación externa o sin empaquetar) para tomar dinámicamente una dependencia del paquete de Windows App SDK framework. Esto le permite usar las API de Windows App SDK en la aplicación.

   Abra el archivo de código Program.cs y reemplace el código predeterminado por el código siguiente para llamar al método Bootstrap.Initialize y así inicializar el bootstrapper. Este código define de qué versión de Windows App SDK depende la aplicación al inicializar el bootstrapper.

   Importante

   Deberá editar el código siguiente para adaptarse a su configuración específica. Consulte las descripciones de los parámetros del método Bootstrap.Initialize para que pueda especificar una de las versiones del Windows App SDK que ha instalado.

   using System;
   using Microsoft.Windows.ApplicationModel.DynamicDependency;
   
   namespace DynamicDependenciesTest
   {
       class Program
       {
           static void Main(string[] args)
           {
               Bootstrap.Initialize(0x00010002);
               Console.WriteLine("Hello, World!");
   
               // Release the DDLM and clean up.
               Bootstrap.Shutdown();
           }
       }
   }
   

   En su raíz, la API de arranque es una API nativa de C/C++ que permite usar las API de Windows App SDK en la aplicación. Pero en una aplicación de .NET que usa el Windows App SDK 1.0 o posterior, puede usar el contenedor .NET para la API de arranque. Ese contenedor proporciona una manera más sencilla de llamar a la API de arranque en una aplicación de .NET que llamar directamente a las funciones nativas de C/C++. El ejemplo de código anterior llama a los métodos estáticos Initialize y Shutdown de la clase Bootstrap en el envoltorio .NET para la API bootstrapper.

6. Para demostrar que los componentes en tiempo de ejecución de Windows App SDK se cargaron correctamente, agregue código que use la clase ResourceManager en el Windows App SDK para cargar un recurso de cadena.

   1. Agregue un nuevo Resources File (.resw) al project (deje el nombre predeterminado).

   2. Con el archivo resources abierto en el editor, cree un nuevo recurso de cadena con las siguientes propiedades.

      • Nombre: Message
      • Valor: Hello, resources!

   3. Guarde el archivo de recursos.

   4. Abra el archivo de código Program.cs y reemplace la Console.WriteLine("Hello, World!"); línea por el código siguiente.

   // Create a resource manager using the resource index generated during build.
      var manager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager("DynamicDependenciesTest.pri");
   
   // Look up a string in the .resw file using its name.
   Console.WriteLine(manager.MainResourceMap.GetValue("Resources/Message").ValueAsString);
   

   1. Haga clic en Iniciar sin depurar (o Iniciar depuración) para compilar y ejecutar la aplicación. Debería ver que la cadena Hello, resources! se muestra correctamente.

C++

Siga estas instrucciones para configurar un proyecto WinUI de C++ que esté empaquetado en una ubicación externa o sin empaquetar.

1. En Visual Studio, crea un nuevo proyecto de aplicación de consola C++. Nombre el proyecto DynamicDependenciesTest.

   

   Después de crear el proyecto, debería tener una aplicación de consola de C++ "Hola, Mundo!".

2. A continuación, instale el paquete NuGet Windows App SDK en el project.

   1. En Solution Explorer, haga clic con el botón derecho en el nodo References y elija Administrar paquetes Nuget.
   2. En la ventana NuGet Package Manager, seleccione la pestaña Browse y busque Microsoft.WindowsAppSDK.

3. Ya estás listo para usar la API de bootstrapper (ver Utilice el entorno de ejecución de Windows App SDK para aplicaciones empaquetadas con ubicación externa o sin empaquetar) para inicializar el entorno de ejecución de Windows App SDK en tu aplicación. Esto le permite usar las API de Windows App SDK en la aplicación.

   1. Agregue los siguientes archivos de inclusión en la parte superior del archivo DynamicDependenciesTest.cpp. El encabezado mddbootstrap.h está disponible a través del paquete NuGet de Windows App SDK.

   #include <windows.h>
   #include <MddBootstrap.h>
   

   1. A continuación, agregue este código al principio de su método main para llamar a la función MddBootstrapInitialize y así inicializar el bootstrapping, y manejar cualquier error. Este código define de qué versión del Windows App SDK depende la aplicación cuando se inicializa el bootstrapper.

   Importante

   Deberá editar el código siguiente para adaptarse a su configuración específica. Consulte las descripciones de los parámetros de la función MddBootstrapInitialize para que pueda especificar una de las versiones de la Windows App SDK que ha instalado.

   const UINT32 majorMinorVersion{ 0x00010002 }; 
   PCWSTR versionTag{ L"" }; 
   const PACKAGE_VERSION minVersion{};
   
   const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
   // Check the return code for errors. If there is an error, display the result.
   if (FAILED(hr)) 
   { 
       wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
           hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
       return hr; 
   } 
   

   1. Por último, agregue este código para mostrar la cadena Hello, World! y llamar a la función MddBootstrapShutdown para desinicializar el bootstrapper.

   std::cout << "Hello, World!\n"; 
   
   // Release the DDLM and clean up.
   MddBootstrapShutdown(); 
   

   1. El código final debe tener el aspecto siguiente.

   #include <iostream> 
   #include <windows.h> 
   #include <MddBootstrap.h>
   
   int main() 
   { 
       // Take a dependency on Windows App SDK Stable.
       const UINT32 majorMinorVersion{ 0x00010002 }; 
       PCWSTR versionTag{ L"" }; 
       const PACKAGE_VERSION minVersion{};
   
       const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
       // Check the return code. If there is a failure, display the result.
       if (FAILED(hr)) 
       { 
           wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
               hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
           return hr; 
       } 
   
       std::cout << "Hello, World!\n"; 
   
       // Release the DDLM and clean up.
       MddBootstrapShutdown(); 
   } 
   

4. Haga clic en Iniciar sin depurar (o Iniciar depuración) para compilar y ejecutar la aplicación.

Si el project es WPF

Para una aplicación de Windows Presentation Foundation (WPF), consulta Usar el SDK de Windows App en una app WPF.

Temas relacionados

• Windows App SDK guía de implementación para aplicaciones dependientes del marco empaquetadas con ubicación externa o sin empaquetar
• Arquitectura del entorno de ejecución