Empaquetado de la aplicación mediante MSIX de un solo proyecto

  • Artículo

MSIX de un solo proyecto es una característica que le permite crear una aplicación de escritorio WinUI 3 empaquetada sin necesidad de un proyecto de empaquetado independiente. Una aplicación WinUI 3 es una aplicación que se usa en el marco de la biblioteca de interfaz de usuario de Windows (WinUI) 3 para su interfaz de usuario (UI) y usa el SDK de aplicaciones para Windows. Para empaquetar una aplicación de escritorio que no sea una aplicación WinUI 3, consulte Configuración de la aplicación de escritorio para el empaquetado MSIX en Visual Studio.

La característica MSIX de un solo proyecto está disponible como una extensión de Visual Studio que puede usar para estos escenarios:

  • Cree una nueva aplicación de escritorio de WinUI 3 con la plantilla de proyecto de Visual Studio empaquetada (WinUI 3 en escritorio) que viene con la SDK de aplicaciones para Windows. Ese proyecto está configurado para compilar su aplicación en un paquete MSIX sin necesidad de un proyecto de empaquetado independiente.
  • Modifique una aplicación de escritorio de WinUI 3 existente que use un proyecto de empaquetado independiente. La modificación implica quitar el proyecto de empaquetado independiente, como se muestra en la ilustración siguiente.

Comparing packaging project to single project

Información general

En esta sección se presentan algunos detalles importantes sobre la característica MSIX de un solo proyecto.

Ventajas

Antes de la introducción de la característica MSIX de un solo proyecto, si quería compilar una aplicación de escritorio de WinUI 3 empaquetada, necesitaba dos proyectos en la solución: el proyecto de aplicación, además de un proyecto de paquete de aplicaciones de Windows adicional (consulte Configuración de la aplicación de escritorio para el empaquetado MSIX en Visual Studio). La característica MSIX de un solo proyecto permite desarrollar y compilar la aplicación con solo un proyecto para la aplicación. Esto proporciona una estructura de proyecto más limpia y una experiencia de desarrollo más sencilla. Por ejemplo, ya no es necesario seleccionar el proyecto de empaquetado independiente como proyecto de inicio.

Tipos de proyecto compatibles

La característica MSIX de un solo proyecto admite plantillas de WinUI 3 en Visual Studio (C# y C++) para el SDK de Aplicaciones para Windows.

Limitaciones

El MSIX de proyecto único solo admite un único ejecutable en el paquete MSIX generado. Si necesita combinar varios ejecutables en un único paquete MSIX, deberá seguir usando un proyecto de empaquetado de aplicaciones de Windows en la solución.

Instale Single-project MSIX Packaging Tools.

Las herramientas de empaquetado MSIX de un solo proyecto incluyen plantillas de proyecto de Visual Studio que puede usar para crear nuevas aplicaciones de escritorio de WinUI 3 empaquetadas. Esas herramientas se incluyen con la extensión SDK de Aplicaciones para Windows para Visual Studio. Para obtener instrucciones de instalación para el SDK de Aplicaciones para Windows, consulte Instalación de herramientas para el SDK de Aplicaciones para Windows.

SDK de Aplicaciones para Windows versión 0.8 y C# de 1.0 Preview 3: Las herramientas de empaquetado MSIX de un solo proyecto no se incluyen con la extensión de SDK de Aplicaciones para Windows para Visual Studio para SDK de Aplicaciones para Windows versión 0.8 o para proyectos de C# con hasta la versión Preview 3 del SDK de Aplicaciones para Windows 1.0. Por lo tanto, si usa esas versiones, es posible que tenga que instalar explícitamente las herramientas de empaquetado MSIX de un solo proyecto. Consulte la información que figura más abajo:

A continuación, podrá confirmar en Visual Studio que tiene instalada la extensión. Haga clic en Extensiones>Administrar extensiones>Instalado>Todo, y confirme que Herramientas de empaquetado MSIX de proyecto único está en la lista.

Cree un nuevo proyecto

Si usa SDK de Aplicaciones para Windows 1.0 Preview 2 o posterior, puede crear una nueva aplicación basada en WinUI 3 que incluya compatibilidad con MSIX de un solo proyecto simplemente mediante la plantilla Aplicación vacía, Empaquetada (WinUI 3 en escritorio). Para más información, consulte Creación del primer proyecto WinUI 3.

Modificar un proyecto existente

Siga los pasos de esta sección para modificar una aplicación basada en WinUI 3 existente que use un proyecto de empaquetado independiente. Los pasos incluyen mover el manifiesto del paquete (y otra compatibilidad necesaria para compilar un paquete MSIX) en el proyecto de aplicación y, a continuación, quitar el proyecto de empaquetado independiente.

Paso 1: Crear o abrir un proyecto de empaquetado existente

Si ya tiene una solución para una aplicación de escritorio de WinUI 3 (consulte Plantillas de WinUI 3 en Visual Studio) que incluye un proyecto de empaquetado de aplicaciones de Windows (consulte Configurar la aplicación de escritorio para empaquetado MSIX en Visual Studio), abra esa solución ahora en Visual Studio.

Si no es así, cree una nueva aplicación de escritorio WinUI 3 en Visual Studio utilizando la plantilla Aplicación en blanco, empaquetada con el proyecto de empaquetado de aplicaciones de Windows (WinUI 3 en escritorio). Su solución se parecerá a la captura de pantalla siguiente.

A solution using the packaging project

Paso 2: Editar la configuración del proyecto de aplicación

A continuación, edite algunas opciones de configuración para usar la característica MSIX de un solo proyecto. Hay instrucciones diferentes en función del tipo de proyecto y de la versión de Visual Studio.

  1. En el Explorador de soluciones, haga doble clic en el nodo del proyecto de su aplicación para abrir el archivo .csproj en el editor XML. Agregue el siguiente XML dentro del elemento principal <PropertyGroup>.

    <EnableMsixTooling>true</EnableMsixTooling>
<PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>

    Cuando haya terminado, el elemento <PropertyGroup> debe ser similar al siguiente.

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>

  2. Guarde los cambios y cierre el archivo .csproj.

  3. Realice uno de los procedimientos siguientes, en función de la versión de Visual Studio.

    Para Visual Studio 2022 o posterior:

    1. En Explorador de soluciones, haga clic con el botón derecho en la carpeta Propiedades en el nodo del proyecto de la aplicación y seleccione Agregar>Nuevo elemento....

    2. Seleccione Archivo de texto, asigne al nuevo archivo el nombre launchConfiguración.json y haga clic en Agregar. Asegúrese de que el nuevo archivo está en la carpeta Propiedades del proyecto de aplicación.

    3. Copie la siguiente configuración en el nuevo archivo. Puede cambiar los valores según sea necesario para su escenario. El valor MyApp puede ser cualquier cadena; no es necesario que coincida con el nombre de la aplicación.

      {
    "profiles": {
        "MyApp": {
            "commandName": "MsixPackage",
            "commandLineArgs": "", /* Command line arguments to pass to the app. */
            "alwaysReinstallApp": false, /* Uninstall and then reinstall the app. All information about the app state is deleted. */
            "remoteDebugEnabled": false, /* Indicates that the debugger should attach to a process on a remote machine. */
            "allowLocalNetworkLoopbackProperty": true, /* Allow the app to make network calls to the device it is installed on. */
            "authenticationMode": "Windows", /* The authentication scheme to use when connecting to the remote machine. */
            "doNotLaunchApp": false, /* Do not launch the app, but debug my code when it starts. */
            "remoteDebugMachine": "", /* The name of the remote machine. */
            "nativeDebugging": false /* Enable debugging for managed and native code together, also known as mixed-mode debugging. */
        }
    }
}

    4. Guarde y cierre el archivo launchSettings.json.

    Para Visual Studio 2019:

    1. En Explorador de soluciones, haga clic con el botón derecho en el nodo del proyecto de la aplicación y seleccione Propiedades.

    2. Seleccione la pestaña Depurar y establezca la propiedad Launch en MsixPackage. Es posible que tenga que seleccionar esto dos veces si se revierte al primer intento.

      Enabling MsixProject option

    3. Guarde los cambios.

Paso 3: Mover archivos al proyecto de aplicación

A continuación, mueva varios archivos importantes al proyecto de aplicación. Hay instrucciones diferentes en función del tipo de proyecto.

  1. En Explorador de archivos, mueva el archivo Package.appxmanifest y la carpeta Imágenes del proyecto de empaquetado al proyecto de aplicación. Coloque este archivo y carpeta en el nivel superior de la jerarquía de carpetas del proyecto de aplicación.
  2. En Visual Studio, en Explorador de soluciones, seleccione varias imágenes dentro de la carpeta Imágenes. En la ventana Propiedades, establezca Acción de compilación en Contenido.
  3. Quite el proyecto de empaquetado de la solución.

Illustration of moving files to main app

Paso 4: Habilitar la implementación en Administrador de Configuración

  1. Seleccione Compilar>Administrador de configuración.
  2. En Administrador de configuración, haga clic en la casilla Implementar para cada combinación de configuración y plataforma (por ejemplo, Depurar y x86, Depurar y arm64, Versión y x64, etc.).

    Nota

    Asegúrese de usar los menús desplegables Active solution configuration (Configuración de solución activa) y Active solution platform (Plataforma de solución activa) en la parte superior en lugar de los menús desplegables Configuración y Plataforma en la misma fila que la casilla Implementar.

Enabling Deploy in Configuration Manager

Paso 5: Implementación de la aplicación

Compilación e implementación del proyecto de la aplicación Visual Studio compilará la aplicación en un paquete MSIX, instalará el paquete y, a continuación, ejecutará la aplicación.

Paso 6: Empaquetar la aplicación para publicar

Use el comando Empaquetar y publicar en Visual Studio para empaquetar la aplicación para publicarla en Microsoft Store.

Automatización de la compilación y empaquetado de la aplicación MSIX de un solo proyecto

Puede usar msbuild para compilar y empaquetar la aplicación MSIX de un solo proyecto, lo que le permite automatizar el flujo de trabajo. La técnica de una solución de un solo proyecto y la línea de comandos solo es ligeramente diferente de lo que puede que ya esté haciendo si tiene una solución de dos proyectos, una que tiene un Proyecto de paquete de aplicación de Windows (consulte Configuración de la aplicación de escritorio para el empaquetado MSIX en Visual Studio).

La opción de comando de compilación importante para una solución de un solo proyecto es /p:GenerateAppxPackageOnBuild=true. Sin esa opción, el proyecto se compilará, pero no obtendrá un paquete MSIX. Incluya esa opción que hará que se genere el paquete MSIX.

Hay un ejemplo completo en forma de una acción de GitHub que compila una solución de proyecto único de WinUI 3.

Nota:

MSIX de un solo proyecto no admite actualmente la producción de paquetes MSIX (consulte Agrupación de paquetes MSIX). Solo genera un solo MSIX. Sin embargo, puede agrupar archivos .msix en un paquete MSIX mediante la acción de GitHub del agrupador de MSIX.

Cómo se ejecutan las aplicaciones de escritorio empaquetadas en Windows

Para obtener un análisis más detallado sobre lo que sucede con los archivos y entradas del registro cuando se crea un paquete de aplicación de Windows para una aplicación de escritorio, consulte Cómo se ejecutan las aplicaciones de escritorio empaquetadas en Windows.

Envío de comentarios

Para enviarnos sus comentarios, notificar problemas o formular preguntas sobre la característica MSIX de un solo proyecto, publique una discusión o un problema en el repositorio de GitHub de SDK de Aplicaciones para Windows.