Distribuir una aplicación WinUI 3 sin empaquetar

La distribución sin empaquetar permite enviar una aplicación WinUI 3 sin MSIX, útil para escenarios empresariales en los que la implementación de MSIX no está disponible o para desarrolladores que prefieren una instalación tradicional basada en carpetas.

Importante

Revise estas limitaciones antes de empezar. Las aplicaciones WinUI 3 sin empaquetar tienen restricciones que afectan a la estrategia de distribución:

  • No archivo único EXE: las dependencias SDK de Aplicaciones para Windows runtime y WinUI 3 deben existir como archivos independientes. La .NET característica de publicación de un solo archivo (PublishSingleFile) no puede agruparlas en un archivo ejecutable. Siempre distribuirá una carpeta de archivos (o las encapsulará en un instalador tradicional, como WiX o Inno Setup).
  • Runtime dependency : el entorno de ejecución de SDK de Aplicaciones para Windows debe estar presente en el equipo del usuario. Debe incluir el instalador del entorno de ejecución con la aplicación o utilizar una implementación independiente (lo que incrementa significativamente el tamaño del resultado). Consulte Deploying the SDK de Aplicaciones para Windows runtime a continuación.
  • No identidad del paquete: sin un manifiesto de paquete, la aplicación no puede usar características de Windows basadas en manifiestos: ninguna actualización automática a través del Instalador de aplicaciones o la Tienda, ningún registro de tareas en segundo plano ni asociaciones de tipo de archivo ni personalización del icono del menú Inicio a través del manifiesto del paquete. (Los mecanismos win32 tradicionales, como las entradas del registro escritas por el instalador y los accesos directos siguen funcionando).
  • No envío MSIX/package-identity Store — Este modelo de distribución no tiene identidad de paquete; no es apto como envío MSIX a la Tienda Microsoft. (Puedes enviar un instalador tradicional a la Tienda a través de la ruta de envío del instalador MSI o EXE, pero es un flujo de trabajo independiente de lo que describe este artículo).

Si estas restricciones son un problema, considere la posibilidad de empaquetar la aplicación (recomendada para la mayoría de las aplicaciones) o empaquetar con ubicación externa para agregar la identidad del paquete sin una conversión MSIX completa.

Para obtener más información sobre todas las opciones de empaquetado, consulta Ventajas y desventajas del empaquetado de la aplicación.

Si decide desempaquetar una aplicación winUI nueva o existente, siga estos pasos:

En el .csproj archivo, busque el primer elemento PropertyGroup existente, que también contiene OutputType, TargetFrameworky otras propiedades.

  • Agregue la propiedad WindowsPackageType del proyecto a este elemento PropertyGroup. Establezca su valor en None.
<Project ...>
  ...
  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType><!-- add this -->
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
  </PropertyGroup> 
  ...
</Project>

Para iniciar la aplicación desde Visual Studio (Debugging o Without Debugging), seleccione el perfil de inicio Unpackaged en la lista desplegable Start. Si se selecciona el perfil Package, verá un error de implementación en Visual Studio. Este paso no es necesario si inicia la aplicación (.exe) desde la línea de comandos o desde Windows Explorador de archivos.

Visual Studio - Menú desplegable de Inicio con el perfil de lanzamiento sin empaquetar de la aplicación de C# resaltado

La API de bootstrapper

Al establecer la propiedad de proyecto <WindowsPackageType>None</WindowsPackageType> hace que el auto-initializer busque y cargue una versión del SDK de Aplicaciones para Windows más adecuado para la aplicación.

Si tiene necesidades avanzadas (como el control de errores personalizado o para cargar una versión específica del SDK de Aplicaciones para Windows), puede llamar explícitamente a la API de arranque. 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 y Tutorial: Usar la API de arranque en una aplicación empaquetada con ubicación externa o sin empaquetar que use el SDK de Aplicaciones para Windows.

Para obtener más información sobre el cargador de arranque, consulte Arquitectura de implementación e información general de aplicaciones dependientes del marco.

Implementación del entorno de ejecución de SDK de Aplicaciones para Windows

Las aplicaciones WinUI 3 sin empaquetar dependen del entorno de ejecución de SDK de Aplicaciones para Windows que se instala en el equipo del usuario. Tiene dos opciones para asegurarse de que el entorno de ejecución está presente:

Option 1: instalador en tiempo de ejecución de SDK de Aplicaciones para Windows (.exe) (recomendado)

Incluya el instalador en tiempo de ejecución de SDK de Aplicaciones para Windows junto con la aplicación. El instalador de ejecución es un .exe redistribuible que instala los paquetes de tiempo de ejecución necesarios del SDK de Aplicaciones para Windows. Descárguelo de la página de versiones de SDK de Aplicaciones para Windows e incorpórelo con su propio instalador o script de instalación. Para obtener instrucciones completas, consulte el entorno de ejecución de SDK de Aplicaciones para Windows para aplicaciones empaquetadas con ubicación o emplazamiento externo, o sin empaquetar.

Los usuarios deben ejecutar el instalador en tiempo de ejecución una vez. Las actualizaciones posteriores de la aplicación no requieren la reinstalación del entorno de ejecución a menos que cambie la versión SDK de Aplicaciones para Windows necesaria.

Opción 2: Implementación independiente

Establezca <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained> en el archivo de proyecto para agrupar el entorno de ejecución de SDK de Aplicaciones para Windows directamente en la carpeta de salida de la aplicación. Esto quita la dependencia en tiempo de ejecución: los usuarios no necesitan instalar nada por separado.

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

El equilibrio: la carpeta de salida es significativamente mayor (se incluye el tiempo de ejecución completo) y cada actualización de la aplicación lleva la carga completa del entorno de ejecución. Use esta opción para escenarios de distribución simples o cuando no pueda controlar lo que está instalado en la máquina de destino.

→ Implementar aplicaciones sin empaquetar que usan el SDK de Aplicaciones para Windows para la referencia completa de implementación en tiempo de ejecución.

Limitación de EXE de un solo archivo

Importante

Las aplicaciones WinUI 3 sin empaquetar no se pueden publicar como EXE de un solo archivo. El entorno de ejecución de SDK de Aplicaciones para Windows y varias dependencias de WinUI 3 deben existir como archivos independientes: la característica de publicación de un solo archivo .NET no puede agruparlas en un archivo ejecutable.

Si una experiencia de distribución de un solo archivo es importante para su escenario, tenga en cuenta estas alternativas:

  • Utilizar el empaquetado MSIX — los usuarios obtienen una única experiencia con el instalador (el instalador de aplicaciones controla todos los archivos), y obtienen la idoneidad de la Tienda, la identidad del paquete y las actualizaciones integradas.
  • Usar un instalador tradicional (WiX, Inno Setup): encapsula la carpeta de salida en un único instalador EXE que extrae e instala todos los archivos necesarios de forma transparente.
  • Use otro framework — WPF y aplicaciones de WinForms con dotnet publish --self-contained -p:PublishSingleFile=truecan producir un archivo ejecutable único, aunque algunas dependencias nativas aún se pueden extraer en tiempo de ejecución

Consideraciones de distribución para aplicaciones sin empaquetar

Las aplicaciones WinUI 3 sin empaquetar carecen de identidad del paquete, lo que significa que no pueden acceder a determinadas características de Windows:

  • Ninguna actualización automática a través del Instalador de aplicaciones ni Windows Store
  • Ningún registro de tareas en segundo plano a través del manifiesto del paquete
  • No hay asociaciones de tipo de archivo ni controladores de protocolo a través del manifiesto del paquete
  • No hay personalización del icono del menú Inicio a través del manifiesto del paquete

Si necesita estas características, considere la posibilidad de empaquetar con ubicación externa como una ruta de acceso intermedia que agrega la identidad del paquete sin necesidad de conversión completa de MSIX.

→ Publicar la primera aplicación de Windows para obtener información general completa de las opciones de distribución para WinUI 3 y otros marcos de aplicaciones de Windows.

  • Last updated on