Compartir por

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

En este tema se proporcionan instrucciones sobre la implementación de aplicaciones empaquetadas con ubicación externa o sin empaquetar y que usan el Windows App SDK.

  • Estas aplicaciones son aplicaciones de escritorio (no aplicaciones para UWP).
  • Se pueden escribir en un lenguaje .NET, como C#, o en C++.
  • Para su interfaz de usuario, pueden usar WinUI 3, o WPF, o WinForms, u otro marco de interfaz de usuario.

Información general

Los desarrolladores de paquetes con ubicación externa y aplicaciones sin empaquetar son responsables de implementar los paquetes en tiempo de ejecución necesarios Windows App SDK en sus usuarios finales. Para ello, se puede ejecutar el instalador o instalar directamente los paquetes MSIX. Estas opciones se describen con más detalle en la sección Deploy Windows App SDK runtime siguiente.

Las aplicaciones empaquetadas con ubicación externa y las aplicaciones sin empaquetar también tienen requisitos adicionales del entorno de ejecución. Debe inicializar el acceso en el entorno de ejecución de Windows App SDK utilizando la Bootstrapper API. Además, la API de dependencias dinámicas se puede usar si la aplicación usa otros paquetes de marco aparte de la Windows App SDK. Estos requisitos se describen con más detalle en la sección Requisitos del entorno de ejecución para aplicaciones empaquetadas con ubicación externa o sin empaquetar más adelante.

Requisitos previos

Requisitos previos adicionales

  • Las versiones experimentales y preliminares del Windows App SDK requieren que la carga lateral esté habilitada para poder instalar el entorno de ejecución.

    • La carga lateral se habilita automáticamente en Windows 10 versión 2004 y posteriores.

    • Si el equipo de desarrollo o el equipo de implementación está ejecutando Windows 11, confirme si la carga lateral está habilitada.

      • Configuración>Privacidad y seguridad>Para desarrolladores. Asegúrese de que la opción Modo de desarrollador esté activada.

    • Si el equipo de desarrollo o el equipo de implementación están ejecutando Windows 10 versión 1909 o una versión anterior, confirme si la carga de aplicaciones externas está habilitada:

      • Configuración>Actualización y seguridad>Para desarrolladores>Usar características de desarrollador. Confirme que la opción Instalación de prueba de aplicaciones o Modo de desarrollador esté seleccionada.

    • La opción Modo de desarrollador incluye la carga lateral, así como otras características.

      Nota:

      Si el equipo se administra en un entorno empresarial, puede haber una directiva que impida que se cambie esta configuración. En ese caso, si recibe un error cuando usted o su aplicación intentan instalar el entorno de ejecución de Windows App SDK, póngase en contacto con su profesional de TI para habilitar la instalación local o el modo de desarrollador.

Implementación del entorno de ejecución de Windows App SDK

Empaquetadas con ubicación externa y aplicaciones sin empaquetar tienen dos opciones para implementar el entorno de ejecución de Windows App SDK:

  • Option 1: Use el instalador: el instalador silencioso distribuye todos los paquetes MSIX de Windows App SDK. Hay disponible un instalador independiente para cada una de las arquitecturas X64, X86 y Arm64.
  • Opción 2: instale los paquetes directamente: puede hacer que su configuración existente o herramienta MSI lleve e instale los paquetes MSIX del Windows App SDK.

Opción 1: Utilizar el instalador

Puede implementar todos los paquetes en tiempo de ejecución de Windows App SDK ejecutando el instalador. El instalador está disponible en Downloads para el Windows App SDK. Cuando se ejecute el instalador (.exe), debería ver una salida similar a la siguiente:

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

Puede ejecutar el instalador sin interacción del usuario y suprimir todas las salidas de texto con la opción --quiet:

WindowsAppRuntimeInstall.exe --quiet

También puede forzar la actualización de los paquetes MSIX y apagar los procesos de Windows App SDK actualmente en ejecución mediante la opción --force. Esta característica se introdujo en 1.1.

WindowsAppRuntimeInstall.exe --force

Para ver todas las opciones de línea de comandos del instalador, ejecute WindowsAppRuntimeInstall --h.

Una vez completada la instalación, puede ejecutar la aplicación empaquetada con ubicación externa o la aplicación sin empaquetar. Para obtener un ejemplo de cómo compilar y ejecutar un empaquetado con una ubicación externa o una aplicación sin empaquetar que usa el Windows App SDK, consulte 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.

Encadene el instalador de Windows App SDK a la configuración de la aplicación

Si tienes un programa de instalación personalizado para la aplicación, puedes encadenar el proceso de configuración de Windows App SDK en el proceso de configuración de la aplicación. Actualmente, el instalador de Windows App SDK no proporciona una interfaz de usuario predeterminada, por lo que deberá vincular utilizando la interfaz de usuario personalizada de su configuración.

Puede iniciar y realizar un seguimiento silencioso de la configuración de Windows App SDK mientras muestra su propia vista del progreso de la instalación mediante ShellExecute. El instalador de Windows App SDK desempaqueta silenciosamente el paquete msix de Windows App y llama al método PackageManager.AddPackageAsync para completar la instalación. Esto es muy similar a otros instaladores en tiempo de ejecución que puede haber usado, como .NET, Visual C++o DirectX.

Para obtener un ejemplo de código que muestra cómo ejecutar el instalador de Windows App SDK desde el programa de instalación, consulte la función RunInstaller en las pruebas funcionales de installer.

Ejemplo del instalador

Consulte el ejemplo siguiente para ver cómo iniciar el instalador desde un programa de instalación de Win32 sin que aparezca una ventana de consola durante la instalación:

ejemplo del instalador de Explore

Solución de problemas

Códigos de retorno

En la tabla siguiente se enumeran los códigos de retorno más comunes para el instalador de Windows App SDK .exe. Los códigos devueltos son los mismos para todas las versiones del instalador.

Código de retorno Descripción
0x0 La instalación o el aprovisionamiento de los paquetes se completaron correctamente.
0x80073d06 No se pudieron instalar uno o varios paquetes.
0x80070005 No se pudo instalar o aprovisionar todo el sistema porque la aplicación no se ejecuta con privilegios elevados o el usuario encargado de la instalación no tiene privilegios de administrador.

Errores de instalación

Si el instalador de Windows App SDK devuelve un error durante la instalación, devolverá un código de error que describe el problema.

Opción 2: Implementar paquetes en tiempo de ejecución de Windows App SDK directamente

Como alternativa al uso del instalador de Windows App SDK para la implementación a los usuarios finales, puedes implementar manualmente los paquetes MSIX a través del programa o MSI de la aplicación. Esta opción puede ser la mejor para los desarrolladores que desean tener más control.

Para ver un ejemplo que muestra cómo el programa de instalación puede instalar los paquetes MSIX, consulte install.cpp en el código del instalador de Windows App SDK.

Para comprobar si el Windows App SDK ya está instalado (y, si es así, qué versión), puede comprobar si hay familias de paquetes específicas llamando a PackageManager.FindPackagesForUserWithPackageTypes.

Desde un mediumIL sin empaquetar de plena confianza (consulte el Application element), puede usar el código siguiente para comprobar si hay un paquete registrado para el usuario actual:

using Windows.Management.Deployment;

public class WindowsAppSDKRuntime
{
    public static IsPackageRegisteredForCurrentUser(
        string packageFamilyName,
        PackageVersion minVersion,
        Windows.System.ProcessorArchitecture architecture,
        PackageTypes packageType)
    {
        ulong minPackageVersion = ToVersion(minVersion);

        foreach (var p : PackageManager.FindPackagesForUserWithPackageTypes(
            string.Empty, packageFamilyName, packageType)
        {
            // Is the package architecture compatible?
            if (p.Id.Architecture != architecture)
            {
                continue;
            }

            // Is the package version sufficient for our needs?
            ulong packageVersion = ToVersion(p.Id.Version);
            if (packageVersion < minPackageVersion)
            {
                continue;
            }

            // Success.
            return true;
        }

        // No qualifying package found.
        return false;
    }

    private static ulong ToVersion(PackageVersion packageVersion)
    {
        return ((ulong)packageVersion.Major << 48) |
               ((ulong)packageVersion.Minor << 32) |
               ((ulong)packageVersion.Build << 16) |
               ((ulong)packageVersion.Revision);
    }
}

Para el escenario anterior, llamar a FindPackagesForUserWithPackageTypes es preferible a llamar a FindPackagesForUser. Esto se debe a que puede restringir la búsqueda a (en este ejemplo), solo framework o paquetes principales. Además, evita buscar coincidencias con otros tipos de paquetes (como recurso, opcional o agrupación) que no son de interés para este ejemplo.

Para usar el contexto de usuario actual o de llamada, establezca el parámetro userSecurityId en una cadena vacía.

Y ahora hay información que le ayudará a decidir cómo llamar a la función en el ejemplo de código anterior. Un entorno de ejecución instalado correctamente se compone de varios paquetes que dependen de la arquitectura de CPU del sistema:

  • En una máquina x86: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
  • En una máquina x64: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
  • En una máquina arm64: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

Para los paquetes Main y Singleton , su arquitectura debe coincidir con la arquitectura de CPU del sistema; por ejemplo, paquetes x64 en un sistema x64. Para el paquete Framework , un sistema x64 puede ejecutar aplicaciones x64 y x86; de forma similar, un sistema arm64 puede ejecutar aplicaciones arm64, x64 y x86. Una comprobación de paquetes DDLM es similar a una comprobación de Framework, excepto que PackageType=main, y packagefamilynamedifieren, y más de un packagefamilyname (diferente) podría ser aplicable, debido al esquema de nomenclatura único de DDLM. Para obtener más información, consulta la especificación de paquetes MSIX. Por lo tanto, las comprobaciones son más similares a esto:

public static bool IsRuntimeRegisteredForCurrentUser(PackageVersion minVersion)
{
    ProcessorArchitecture systemArchitecture = DetectSystemArchitecture();

    return IsFrameworkRegistered(systemArchitecture, minVersion) &&
           IsMainRegistered(systemArchitecture, minVersion) &&
           IsSingletonRegistered(systemArchitecture, minVersion) &&
           IsDDLMRegistered(systemArchitecture, minVersion);
}

private static ProcecssorArchitecture DetectSystemArchitecture()
{
    // ...see the call to IsWow64Process2(), and how the result is used...
    // ...as per `IsPackageApplicable()` in
    // [install.cpp](https://github.com/microsoft/WindowsAppSDK/blob/main/installer/dev/install.cpp)
    // line 99-116...
    // ...WARNING: Use IsWow64Process2 to detect the system architecture....
    // ...         Other similar APIs exist, but don't give reliably accurate results...
}

private static bool IsFrameworkRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // Check x86.
    if (!IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
        minVersion, ProcessorArchitecture.X86,
        PackageTypes.Framework))
    {
        return false;
    }

    // Check x64 (if necessary).
    if ((systemArchitecture == ProcessorArchitecture.X64) || 
        (systemArchitecture == ProcessorArchitcture.Arm64))
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.X64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    // Check arm64 (if necessary).
    if (systemArchitecture == ProcessorArchitcture.Arm64)
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.Arm64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    return true;
}

private static bool IsMainRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Main.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsSingletonRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Singleton.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsDDLMRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // ...similar to IsFrameworkRegistered, but the packageFamilyName is more complicated...
    // ...and no predefined constant is currently available...
    // ...for more details, see
    // https://github.com/microsoft/WindowsAppSDK/blob/main/specs/Deployment/MSIXPackages.md.
}

La información y el código anterior tratan el escenario de detección básico. Para detectar si el tiempo de ejecución está aprovisionado para todos los usuarios, o hacer lo anterior desde un contenedor de aplicaciones, y/o desde un proceso empaquetado de mediumIL, se necesita lógica adicional.

Escenarios de implementación

  • Instalación del sistema en tiempo de ejecución de Windows App SDK de manera global: La instalación en todo el sistema modifica la máquina para todos los usuarios, incluidos los nuevos usuarios que se añadan en el futuro. Si la aplicación se ejecuta con privilegios elevados y el usuario que se encarga de la instalación tiene privilegios de administrador, el instalador llamará a ProvisionPackageForAllUsersAsync para registrar los paquetes MSIX en todo el sistema. Si el registro en todo el sistema no se completa correctamente, la instalación se completará solo para el usuario actual que realiza la instalación. En un entorno empresarial administrado, el administrador de TI debe poder aprovisionar para todos los usuarios como de costumbre.

  • Architecturas redistribuidas por el instalador de Windows App SDK: El instalador de Windows App SDK está disponible en las arquitecturas x86, x64 y Arm64. Cada versión del instalador incluye los paquetes MSIX solo para la arquitectura específica para la cual está diseñada. Por ejemplo, si ejecuta el x86WindowsAppRuntimeInstall.exe en un dispositivo x64 o Arm64, ese x86 instalador solo implementará en ese dispositivo los paquetes de la arquitectura x86.

  • Todos los paquetes MSIX de Windows App SDK ya están instalados en el equipo: los paquetes MSIX se instalan en una ubicación en todo el sistema con solo una copia en el disco. Si una aplicación intenta instalar la Windows App SDK cuando todas las dependencias del paquete MSIX ya están instaladas en el equipo, no se realiza la instalación.

  • Uno o más de los paquetes MSIX de Windows App SDK no están instalados en el equipo: Al implementar Windows App SDK, asegúrese de intentar instalar siempre todos los paquetes MSIX (framework, main, singleton, DDLM) para garantizar que todas las dependencias estén instaladas y se evitarán interrupciones en la experiencia del usuario final.

Requisitos del entorno de ejecución para aplicaciones empaquetadas con ubicación externa o sin empaquetar

Las aplicaciones empaquetadas con ubicación externa o sin empaquetar tienen requisitos adicionales de tiempo de ejecución para usar el entorno de ejecución de Windows App SDK. Esto implica hacer referencia e inicializar el paquete de Windows App SDK Framework en tiempo de ejecución. Además, la API de dependencias dinámicas se puede usar para hacer referencia a otros paquetes de marcos fuera del Windows App SDK.

Uso del entorno de ejecución de Windows App SDK

Las aplicaciones empaquetadas con una ubicación externa y las aplicaciones sin empaquetar deben llamar a la API Bootstrapper para usar el Windows App SDK en tiempo de ejecución. Esto es necesario para que la aplicación pueda usar Windows App SDK características como WinUI, Ciclo de vida de la aplicación, MRT Core y DWriteCore. Un componente de arranque permite que las aplicaciones empaquetadas desde una fuente externa y las aplicaciones sin empaquetar realicen estas tareas importantes:

  • Busque y cargue el paquete de marco de Windows App SDK en el gráfico de paquetes de la aplicación.
  • Inicialice el Administrador de Duración de Dependencia Dinámica (DDLM) para el paquete del framework de Windows App SDK. El propósito de la DDLM es evitar la actualización del paquete de la plataforma Windows App SDK mientras está siendo utilizado por una aplicación empaquetada con ubicación externa o una aplicación desempaquetada.

La manera más sencilla de cargar el entorno de ejecución de Windows App SDK para aplicaciones empaquetadas con ubicación externa y aplicaciones sin empaquetar es establecer la propiedad <WindowsPackageType>None</WindowsPackageType> en el archivo de proyecto (.csproj o .vcxproj). También puede llamar a la API Bootstrapper directamente en el código de inicio de la aplicación para tener más control sobre la inicialización. Para obtener más información, consulte Use el entorno de ejecución de Windows App SDK para aplicaciones empaquetadas con ubicación externa o sin empaquetar y Tutorial: Use la API de arranque en una aplicación empaquetada con ubicación externa o sin empaquetar que use el Windows App SDK.

La compatibilidad con dependencias dinámicas permite a las aplicaciones empaquetadas con ubicaciones externas y a las aplicaciones sin empaquetar mantener su mecanismo de implementación existente, como MSI o cualquier instalador, y poder utilizar el Windows App SDK en su aplicación. Las aplicaciones empaquetadas, empaquetadas con ubicación externa y sin empaquetar pueden usar dependencias dinámicas; aunque esto está pensado principalmente para aplicaciones empaquetadas con ubicación externa y sin empaquetar.

Hay un DDLM para cada versión y arquitectura del paquete de marco de Windows App SDK. Es decir, en una computadora x64, es posible que tenga tanto una versión x86 como una versión x64 de DDLM para admitir aplicaciones de ambas arquitecturas.

Referencia a otros paquetes de marco mediante la API Dynamic Dependencies

Si desea usar características en otros paquetes de marcos fuera del Windows App SDK (por ejemplo, DirectX), las aplicaciones empaquetadas que se encuentren en una ubicación externa y las aplicaciones sin empaquetar pueden llamar a la API de Dependencias Dinámicas. Además del componente bootstrapper, el Windows App SDK también proporciona un conjunto más amplio de funciones de C/C++ y clases WinRT que implementan la API de dependencia dinámica. Esta API está diseñada para usarse para hacer referencia a cualquier paquete de marco dinámicamente en tiempo de ejecución.

Para obtener más información, consulte Uso dinámico de paquetes de marcos MSIX desde la aplicación de escritorio y el ejemplo de Dynamic Dependencies.

Implementación de archivos .winmd en la máquina de destino

Junto con la aplicación, se recomienda seguir adelante e implementar archivos de metadatos de Windows (.winmd). Los metadatos se pueden usar en varias API y comportamientos en tiempo de ejecución, y su ausencia puede limitar o interrumpir la funcionalidad. Por ejemplo, los metadatos se pueden utilizar para serializar objetos más allá de los límites de apartamentos, y la necesidad de serializar puede depender del rendimiento de la máquina. Dado que no hay ninguna forma determinista de saber si necesita metadatos, debe implementar .winmda menos que le preocupe mucho el tamaño.

  • Last updated on