Tutorial: uso de la API bootstrapper en una aplicación empaquetada con ubicación externa o sin empaquetar que utiliza el SDK de Windows App

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 SDK de Aplicaciones para Windows y llame a SDK de Aplicaciones para Windows API. Las aplicaciones que no se instalan a través de MSIX incluyen aplicaciones empaquetadas con ubicación externa y aplicaciones sin empaquetar.

Importante

A partir del SDK de Aplicaciones para Windows 1.0, el enfoque predeterminado para cargar el SDK de Aplicaciones para Windows desde una aplicación empaquetada con una ubicación externa o sin empaquetar es usar la inicialización automática mediante la propiedad <WindowsPackageType> del proyecto (así como realizar cambios de configuración adicionales). Para conocer los pasos implicados en la inicialización automática en el contexto del proyecto de WinUI 3, consulte Creación del primer proyecto de WinUI 3. O bien, si tiene un proyecto existente que no es WinUI 3, consulte Uso del SDK de Aplicaciones para Windows en un proyecto existente.

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

En este tema se muestra cómo llamar explícitamente a la API del programa previo desde un proyecto básico de aplicación de consola; pero los pasos se aplican a cualquier aplicación de escritorio sin empaquetar que use el SDK de Aplicaciones para Windows.

Antes de completar este tutorial, se recomienda revisar La arquitectura en tiempo de ejecución para obtener más información sobre la dependencia del paquete de Framework que toma la aplicación cuando usa la SDK de Aplicaciones para Windows y los componentes adicionales necesarios para trabajar en un empaquetado con ubicación externa o aplicación sin empaquetar.

Requisitos previos

  1. Instalación de herramientas para el SDK de Aplicaciones para Windows.
  2. Asegúrese de que todas las dependencias de empaquetadas con la ubicación externa y las aplicaciones sin empaquetar estén instaladas (consulte SDK de Aplicaciones para Windows guía de implementación para aplicaciones dependientes del marco empaquetadas con ubicación externa o sin empaquetar). Una manera fácil de hacerlo es ejecutar el instalador en tiempo de ejecución de SDK de Aplicaciones para Windows.

Instrucciones

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

Nota

Las dependencias dinámicas y las API del programa previo producen un error cuando se llama mediante un proceso con privilegios elevados. Como resultado, Visual Studio no debe iniciarse con privilegios elevados. Consulte Dependencias dinámicas no admite la elevación n.º 567 para obtener más detalles.

Siga estas instrucciones para configurar un proyecto de WinUI 3 de C# que esté empaquetado con ubicación externa o sin empaquetar.

  1. En Visual Studio, cree un nuevo proyecto de aplicación de consola de C#. Asigne al proyecto el nombre DynamicDependenciesTest. Después de crear el proyecto, debe tener un mensaje "Hello, World!" Aplicación de consola de C#.

  2. A continuación, configure el proyecto.

    1. En Explorador de soluciones, 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, usa lo siguiente si la aplicación tiene como destino Windows 10, versión 2004.
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    
    1. Guarda y cierra el archivo de proyecto.
  3. Cambie la plataforma de la solución a x64. El valor predeterminado de un proyecto de .NET es AnyCPU, pero WinUI 3 no admite esa plataforma.

    1. Seleccione Compilar>Administrador de configuración.
    2. Seleccione la lista desplegable en Plataforma de solución activa y haga clic en Nuevo para abrir el cuadro de diálogo Nueva plataforma de soluciones .
    3. En la lista desplegable en Tipo o seleccione la nueva plataforma, seleccione x64.
    4. Haga clic en Aceptar para cerrar el cuadro de diálogo Nueva plataforma de soluciones .
    5. En Configuration Manager, haga clic en Cerrar.
  4. Instale el paquete NuGet SDK de Aplicaciones para Windows en el proyecto.

    1. En Explorador de soluciones, haga clic con el botón derecho en el nodo Dependencias y elija Administrar paquetes NuGet.
    2. En la ventana Administrador de paquetes NuGet , seleccione la pestaña Examinar e instale el paquete Microsoft.WindowsAppSDK .
  5. Ya está listo para usar la API de arranque (consulte Uso del entorno de ejecución de SDK de Aplicaciones para Windows para aplicaciones empaquetadas con ubicación externa o sin empaquetar) para tomar dinámicamente una dependencia en el paquete de SDK de Aplicaciones para Windows framework. Esto le permite usar las API de SDK de Aplicaciones para Windows 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 para inicializar el programa previo. Este código define qué versión del SDK de Aplicaciones para Windows depende la aplicación al inicializar el programa previo.

    Importante

    Deberá editar el código siguiente para adaptarse a su configuración específica. Vea las descripciones de los parámetros del método Bootstrap.Initialize para que pueda especificar una de las versiones de la SDK de Aplicaciones para Windows 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 SDK de Aplicaciones para Windows en la aplicación. Pero en una aplicación de .NET que usa la SDK de Aplicaciones para Windows 1.0 o posterior, puede usar el contenedor de .NET para la API de arranque. Ese contenedor proporciona una manera más sencilla de llamar a la API del programa previo en una aplicación .NET que llamar directamente a las funciones nativas de C/C++. El ejemplo de código anterior llama a los métodos static Initialize y Shutdown de la clase Bootstrap en el contenedor de .NET para la API de arranque.

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

    1. Agregue un nuevo archivo de recursos (.resw) al proyecto (deje el nombre predeterminado).

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

      • Nombre: Mensaje
      • Valor: ¡Hola, recursos!
    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.

Si el proyecto es WPF

Para obtener una aplicación de Windows Presentation Foundation (WPF), consulte Uso del SDK de Aplicaciones para Windows en una aplicación WPF.