guía de implementación de SDK de Aplicaciones para Windows para aplicaciones empaquetadas dependientes del marco

En este artículo se proporcionan instrucciones sobre la implementación de aplicaciones empaquetadas dependientes del marco (consulte ¿Qué es MSIX?) que usan el SDK de Aplicaciones para Windows. El tema equivalente para otras opciones de empaquetado dependientes del marco es SDK de Aplicaciones para Windows guía de implementación para aplicaciones dependientes del marco empaquetadas con ubicación externa o sin empaquetar.

Overview

De forma predeterminada, al crear un proyecto con una de las plantillas de WinUI 3 en Visual Studio, el proyecto está configurado para compilar la aplicación en un paquete MSIX mediante MSIX de un solo proyecto (consulte Empaquetar la aplicación con MSIX de un solo proyecto) o un proyecto de empaquetado de aplicaciones de Windows (consulte Configuración de la aplicación de escritorio para el empaquetado msix en Visual Studio). A continuación, puedes compilar un paquete MSIX para tu aplicación mediante las instrucciones de Paquete una aplicación de escritorio o UWP en Visual Studio. Después de compilar un paquete MSIX para tu aplicación, tienes varias opciones para Administrar tu implementación de MSIX.

Para obtener más información sobre los paquetes que la aplicación empaquetada podría necesitar cuando usa el SDK de Aplicaciones para Windows, consulte Arquitectura de implementación para la SDK de Aplicaciones para Windows. Entre ellos se incluyen los paquetes Framework, Main y Singleton ; todos firmados y publicados por Microsoft. Hay dos requisitos principales para implementar una aplicación empaquetada:

  1. Implemente el paquete de marco del SDK de aplicaciones de Windows.
  2. Llama a Recurrir a la API de implementación.

Prerequisites

Implementación del paquete de marco de SDK de Aplicaciones para Windows

El paquete de marco de SDK de Aplicaciones para Windows contiene los archivos binarios SDK de Aplicaciones para Windows usados en tiempo de ejecución y se instala con la aplicación. El marco tiene diferentes requisitos de implementación para distintos canales del SDK de Aplicaciones para Windows.

Versión estable

Al instalar una versión estable del paquete NuGet de SDK de Aplicaciones para Windows en el equipo de desarrollo y se crea un proyecto con una de las plantillas de proyecto winUI proporcionadas, el manifiesto del paquete generado contiene un PackageDependency elemento que especifica una dependencia en el paquete de marco.

Sin embargo, si compilas manualmente el paquete de la aplicación mediante un proyecto de empaquetado de aplicaciones de Windows independiente, debes declarar un PackageReference en el archivo /> 

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

Esa dependencia de paquete garantiza que el paquete framework se instala cuando la aplicación se implementa en otro equipo.

Versión preliminar

Al instalar una versión preliminar del paquete NuGet de SDK de Aplicaciones para Windows en el equipo de desarrollo, se implementa una versión preliminar del paquete de marco de SDK de Aplicaciones para Windows durante el tiempo de compilación como dependencia de paquete NuGet.

Llamada a la API de implementación

Consulte también Initialize the SDK de Aplicaciones para Windows.

El paquete de framework de SDK de Aplicaciones para Windows proporciona la API de implementación y está disponible en el espacio de nombres Microsoft.Windows.ApplicationModel.WindowsAppRuntime. El modelo de aplicación Windows no admite la declaración de una dependencia en los paquetes Main y Singleton. Por lo tanto, la API de implementación es necesaria por estos motivos:

  1. Para implementar el paquete Singleton para características que no están en el paquete framework (por ejemplo, notificaciones push).
  2. Para implementar el paquete Main, que permite las actualizaciones automáticas del paquete framework desde Microsoft Store.

En el caso de las aplicaciones empaquetadas que no se distribuyen a través de la Tienda, usted, como el desarrollador, es responsable de distribuir el paquete Framework. Se recomienda llamar a la API de implementación para que se entreguen las actualizaciones de mantenimiento críticas. Tenga en cuenta que, para usar características fuera del paquete de Framework (por ejemplo, notificaciones push), se debe implementar el paquete Singleton (esto se puede hacer con la API de implementación o redistribuyendo los paquetes MSIX mediante su propio método de instalación).

Important

Solo las aplicaciones empaquetadas que son de plena confianza o que tienen la funcionalidad restringida packageManagement tienen permiso para usar la API de implementación para instalar las dependencias del paquete Main y Singleton.

Debes llamar a la API de implementación después de que se haya inicializado el proceso de la aplicación, pero antes de que la aplicación use funciones de tiempo de ejecución de SDK de Aplicaciones para Windows que utilizan el paquete Singleton (por ejemplo, notificaciones push). Los métodos principales de la API de implementación son los métodos estáticos GetStatus y Initialize de la clase DeploymentManager.

  • El método GetStatus devuelve el estado de implementación actual del entorno de ejecución de SDK de Aplicaciones para Windows que está cargado actualmente. Utilice este método para identificar si es necesario instalar paquetes de tiempo de ejecución de SDK de Aplicaciones para Windows antes de que la aplicación actual pueda usar las funciones de SDK de Aplicaciones para Windows.
  • El método Initialize comprueba si todos los paquetes necesarios están presentes en una versión mínima necesaria para el entorno de ejecución de SDK de Aplicaciones para Windows que está cargado actualmente. Si faltan dependencias de paquetes, el método intenta registrar esos paquetes que faltan. A partir de SDK de Aplicaciones para Windows 1.1, el método Initialize también admite la opción de forzar la implementación de los paquetes en tiempo de ejecución de SDK de Aplicaciones para Windows. Esto cierra los procesos de los paquetes en tiempo de ejecución main y singleton y, por tanto, interrumpe sus servicios (por ejemplo, las notificaciones push no entregarán notificaciones durante este tiempo). Debe llamar a Initialize solo una vez. No es necesario llamar a Initialize para las aplicaciones implementadas a través de los comandos Iniciar sin depuración y Iniciar depuración en Visual Studio.

Important

El valor predeterminado de la propiedad Visual Studio <WindowsAppSdkDeploymentManagerInitialize> es true. Por lo tanto, si desea llamar a DeploymentManager.Initialize explícitamente, establezca <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize> en el archivo de proyecto de Visual Studio.

Aplicación de ejemplo de API de implementación

Para obtener instrucciones adicionales sobre cómo usar los métodos GetStatus e Initialize de la clase DeploymentManager , explore la aplicación de ejemplo disponible.

Explore la aplicación de ejemplo de API de implementación

Solucionar errores de instalación

Si la API de implementación encuentra un error durante la instalación de los paquetes en tiempo de ejecución de SDK de Aplicaciones para Windows, devuelve un código de error que describe el problema.

En la tabla siguiente se enumeran los códigos de error comunes de la API de implementación y sus causas típicas:

Código de error Name Causa común
0x80070005 ACCESS_DENIED La aplicación no es de plena confianza o no tiene la funcionalidad restringida packageManagement . Ejecute con privilegios elevados o agregue la funcionalidad necesaria.
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED El paquete MSIX está dañado o inaccesible. Compruebe que el archivo de paquete está intacto y que la ruta de acceso es correcta.
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED Falta un paquete de dependencia necesario o no es compatible. Asegúrese de que se instala el paquete de marco VCLibs y cualquier otro requisito previo.
0x80073D06 ERROR_PACKAGES_IN_USE (Paquetes en uso) Uno o varios paquetes están en uso y no se pueden actualizar. Cierre todas las aplicaciones mediante el entorno de ejecución de SDK de Aplicaciones para Windows y vuelva a intentarlo.
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS La versión del paquete ya está registrada. Esto es informativo: la aplicación puede continuar.
0x80073CF9 ERROR_INSTALL_FAILED Error general de instalación. Compruebe los registros de eventos para obtener más detalles (consulte a continuación).

Sugerencia

Para obtener la lista completa de códigos de error de instalación de paquetes MSIX, consulte Solución de problemas de empaquetado, implementación y consulta de aplicaciones de Windows.

Si el código de error no proporciona suficiente información, puede encontrar más información de diagnóstico en los registros de eventos detallados (consulte Obtener información de diagnóstico). Los registros de eventos se encuentran en Visor de eventos en Registros de >Microsoft>Windows>AppxDeployment-Server.

Si encuentra errores que no se pueden diagnosticar, registre un problema en el repositorio WindowsAppSDK GitHub repo con el código de error y los registros de eventos para que podamos investigar el problema.

  • Last updated on