Compartir a través de

Creación de una aplicación de WinUI 3 que use el canal de Versión preliminar y Experimental del SDK de Aplicaciones para Windows

El SDK de Aplicaciones para Windows incluye plantillas de proyecto de WinUI 3 que le permiten crear aplicaciones de escritorio con una interfaz de usuario completamente basada en WinUI. Cuando se crean aplicaciones utilizando estas plantillas de proyecto, toda la interfaz de usuario de la aplicación se implementa mediante ventanas, controles y otros tipos de interfaz de usuario proporcionados por WinUI 3. Para obtener una lista completa de las plantillas de proyecto, consulte Plantillas de WinUI 3 en Visual Studio.

Uso de la versión estable del SDK de Aplicaciones para Windows: para compilar una aplicación de WinUI 3 con la versión estable del SDK de Aplicaciones para Windows, consulte Creación del primer proyecto de WinUI 3.

Requisitos previos

Para usar las plantillas de proyecto de WinUI 3 descritas en este artículo, configure el equipo de desarrollo e instale la extensión del SDK para aplicaciones de Windows para Visual Studio. Para más información, consulte Instalación de herramientas para canales experimentales y de versión preliminar del SDK de Aplicaciones para Windows.

Nota:

Algunos tipos fundamentales de WinRT, como CoreWindow, ApplicationView, CoreApplicationView,CoreDispatcher y sus dependencias, no están disponibles en aplicaciones de escritorio. Estos tipos se diseñaron específicamente para escenarios de interfaz de usuario en aplicaciones para UWP y no se comportan correctamente en las aplicaciones de escritorio debido a modelos de subprocesos y otras diferencias de la plataforma. Para obtener más información, incluidas las API alternativas recomendadas, consulte API de Windows Runtime no admitidas en aplicaciones de escritorio.

Instrucciones para aplicaciones de escritorio empaquetadas de WinUI 3

Para crear una aplicación de WinUI 3 con empaquetado MSIX, elija uno de los siguientes conjuntos de instrucciones en función del idioma del proyecto y la versión del SDK de Aplicaciones para Windows.

Para crear una aplicación de escritorio de WinUI 3 con C# mediante el SDK de Aplicaciones para Windows 1.0 (versión preliminar 3):

  1. En Visual Studio, seleccione File ->Nuevo ->Proyecto.

  2. En los filtros desplegables del proyecto, selecciona C# , Windows y WinUI, respectivamente.

  3. Seleccione uno de los siguientes tipos de proyecto y, a continuación, haga clic en Siguiente.

    • Blank App, Packaged (WinUI 3 in Desktop) (Aplicación vacía, empaquetada [WinUI 3 en el Escritorio]): crea una aplicación de escritorio de C# .NET con una interfaz de usuario basada en WinUI. El proyecto generado se configura con el manifiesto de paquete y otra compatibilidad necesaria para compilar la aplicación en un paquete MSIX sin el uso de un proyecto de empaquetado independiente. Para más información, consulte Empaquetado de la aplicación mediante MSIX de un solo proyecto.

      Nota:

      Si instaló Windows App SDK 1.0 versión preliminar 2 con Visual Studio 2019, esta plantilla de proyecto tiene un problema conocido que produce un error de compilación. Para resolver este problema, instale la extensión VSIX de herramientas de empaquetado MSIX de proyecto único para Visual Studio 2019 después de instalar Windows App SDK 1.0 versión preliminar 2.

    • Blank App, Packaged with WAP (WinUI 3 in Desktop) (Aplicación vacía, empaquetada con WAP [WinUI 3 en el Escritorio]): crea una aplicación de escritorio de C# .NET con una interfaz de usuario basada en WinUI. La solución generada incluye un Proyecto de paquete de aplicación de Windows independiente configurado para compilar la aplicación en un paquete MSIX.

    Captura de pantalla del asistente para crear un nuevo proyecto con la opción Aplicación vacía, empaquetada (WinUI en escritorio) resaltada.

  4. Escribe un nombre de proyecto, elige todas las opciones que quieras y haz clic en Crear.

  5. En el siguiente cuadro de diálogo, establezca Versión de destino en Windows 10, versión 2004 (compilación 19041), y Versión mínima en Windows 10, versión 1809 (compilación 17763) y, a continuación, haga clic en Aceptar.

    Versión de destino y mínima

  6. En este momento, Visual Studio genera uno o varios proyectos:

    • Nombre de proyecto (Desktop) : Este proyecto contiene el código de la aplicación. El archivo App.xaml y el archivo de código subyacente App.xaml.cs definen una clase Application que representa la instancia de la aplicación. El archivo MainWindow.xaml y el archivo de código subyacente MainWindow.xaml.cs definen una clase MainWindow que representa la ventana principal que muestra la aplicación. Estas clases se derivan de los tipos del espacio de nombres Microsoft.UI.Xaml proporcionados por WinUI.

      Si usó la plantilla de proyecto Blank App, Packaged (WinUI 3 in Desktop) (Aplicación vacía, empaquetada [WinUI 3 en el Escritorio]), este proyecto también incluye el manifiesto de paquete para compilar la aplicación en un paquete MSIX.

      Captura de pantalla de Visual Studio en la que se muestra el panel Explorador de soluciones y el contenido del archivo X A M L punto C S de las ventanas principales para un solo proyecto M S I X.

    • Nombre de proyecto (paquete) : este proyecto solo se genera si usa la plantilla de proyecto Blank App, Packaged with WAP (WinUI 3 in Desktop) (Aplicación vacía, empaquetada con WAP [WinUI 3 en el Escritorio]). Se trata de un Proyecto de paquete de aplicación de Windows que está configurado para compilar la aplicación en un paquete MSIX. Este proyecto contiene el manifiesto de paquete para la aplicación y es el proyecto de inicio de la solución de forma predeterminada.

      Captura de pantalla de Visual Studio en la que se muestra el panel Explorador de soluciones y el contenido del archivo Package app x manifest.

  7. Habilite la implementación del proyecto en el Administrador de configuración. Si no sigue estos pasos para habilitar la implementación, se producirá el siguiente error al intentar ejecutar o depurar el proyecto en el equipo de desarrollo: "Es necesario implementar el proyecto antes de que se pueda depurar. Please enable Deploy in the Configuration Manager" (Habilite Implementar en el 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.

      Habilitación de Implementar en el Administrador de configuración

  8. Para agregar un nuevo elemento al proyecto de aplicación, haga clic con el botón derecho en el nodo del proyecto nombre del proyecto (Escritorio) en el Explorador de soluciones y seleccione Agregar>Nuevo elemento. En el cuadro de diálogo Agregar nuevo elemento, selecciona la pestaña WinUI, elige el elemento que deseas agregar y, a continuación, haz clic en Agregar. Para obtener más detalles sobre los elementos disponibles, consulte Plantillas de WinUI 3 en Visual Studio.

    Captura de pantalla del cuadro de diálogo Agregar nuevo elemento con las opciones Instalado > Elementos de Visual C > WinUI seleccionadas y la opción Página en blanco resaltada.

  9. Compile y ejecute la solución en el equipo de desarrollo para confirmar que la aplicación se ejecuta sin errores.

Localización de la aplicación de escritorio de WinUI

A fin de admitir varios idiomas en una aplicación de escritorio de WinUI y garantizar la localización correcta del proyecto empaquetado, agregue los recursos adecuados al proyecto (consulte Recursos de la aplicación y el sistema de administración de recursos) y declare cada idioma compatible en el archivo package.appxmanifest del proyecto. Al compilar el proyecto, los idiomas especificados se agregan al manifiesto de la aplicación generado (AppxManifest.xml) y se usan los recursos correspondientes.

  1. Abra el archivo package.appxmanifest de .wapproj en un editor de texto y busque la sección siguiente:

    <Resources>
    <Resource Language="x-generate"/>
</Resources>

  2. Reemplace <Resource Language="x-generate"> por <Resource /> elementos de cada uno de los idiomas admitidos. Por ejemplo, el marcado siguiente especifica que los recursos localizados "en-US" y "es-ES" están disponibles:

    <Resources>
    <Resource Language="en-US"/>
    <Resource Language="es-ES"/>
</Resources>

Instrucciones para aplicaciones de escritorio sin empaquetar de WinUI 3

Nota:

La compatibilidad de WinUI 3 con aplicaciones sin empaquetar se encuentra actualmente en versión preliminar y no está lista para producción. Debe descargar la extensión en versión preliminar del SDK de Aplicaciones para Windows para Visual Studio a fin de obtener las plantillas de proyecto y compilar las aplicaciones de escritorio sin empaquetar con WinUI 3. Para obtener una lista de los problemas conocidos, consulte Notas de la versión del SDK de Aplicaciones para Windows 1.0, versión preliminar 3.

Para crear una aplicación de WinUI 3 sin empaquetado MSIX, elija uno de los siguientes conjuntos de instrucciones en función del idioma del proyecto y la versión del SDK de Aplicaciones para Windows.

Para crear una aplicación de escritorio de WinUI 3 con C# mediante el SDK de Aplicaciones para Windows 1.0 (versión preliminar 3):

  1. Instale Single-project MSIX Packaging Tools.

  2. Instale la extensión de Visual Studio 2019 C# o la extensión de Visual Studio 2022 C#, en función de la versión de Visual Studio.

  3. Instale el entorno del SDK de Aplicaciones para Windows y los paquetes MSIX. Son necesarios para ejecutar e implementar la aplicación.

  4. Cree una nueva aplicación mediante la plantilla de proyecto "Blank App, Packaged (WinUI 3 in Desktop)" (Aplicación vacía, empaquetada [WinUI 3 en el Escritorio]). Cuando se empieza con una aplicación empaquetada, es necesario usar los diagnósticos de XAML.

  5. Agregue la siguiente propiedad al archivo de proyecto, ya sea el archivo .csproj (C#) o .vcxproj (C++):

    <Project ...>
  ...
  <PropertyGroup>
    ...
    <WindowsPackageType>None</WindowsPackageType>
  </PropertyGroup> 
  ...
</Project>

  6. Elimine package.appxmanifest del proyecto.

    De lo contrario, verá este error: Improper project configuration: WindowsPackageType is set to None, but AppxManifest is specified (Configuración incorrecta del proyecto: WindowsPackageType se ha establecido en None, pero se ha especificado AppxManifest).

    Nota:

    Es posible que tenga que cerrar la solución de Visual Studio para eliminar manualmente este archivo del sistema de archivos. Visual Studio 2019: explorador de soluciones abierto con el archivo appxmanifest resaltado

  7. Para depurar en Visual Studio, cambie las propiedades de depuración de "MsixPackage" a "Project". De lo contrario, verá el error: "The project doesn't know how to run the profile…" (El proyecto no sabe cómo ejecutar el perfil...)"

    Nota:

    No es necesario si ejecuta la aplicación (.exe) desde la línea de comandos o el explorador de archivos de Windows.

    • En Visual Studio 2022: abra launchSettings.json y cambie "MsixPackage" a "Project" en el perfil.

      {
    "profiles": {
        "Preview3": {
            "commandName": "Project"
        }
    }
}

    • En Visual Studio 2019 y Visual Studio 2022: puede usar la interfaz de usuario de Visual Studio para cambiar la configuración de inicio:

      Abra las propiedades de depuración y cambie el perfil de inicio a "Project".

      Visual Studio 2019: lista desplegable de inicio con las propiedades de depuración de aplicaciones de C# resaltadas

      Visual Studio 2019: página de propiedades de la aplicación de C# con el depurador para iniciar la propiedad del depurador de Windows local resaltada.

  8. Si aún no lo ha hecho, instale el entorno de ejecución del SDK de Aplicaciones para Windows y los paquetes MSIX, que son necesarios para ejecutar e implementar la aplicación.

    Descargar el instalador más reciente y los paquetes MSIX

  9. Compile y ejecute. Para obtener información adicional sobre la implementación, consulte el tutorial de SDK de Aplicaciones para Windows para implementar paquetes con ubicación externa y aplicaciones sin empaquetar (Tutorial: Uso de la API de arranque en una aplicación empaquetada con ubicación externa o desempaquetada que usa el SDK de Aplicaciones para Windows). Este tutorial le guiará por el uso de 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 inicializar el entorno de ejecución de SDK de Aplicaciones para Windows para que la aplicación pueda usar SDK de Aplicaciones para Windows y las API de WinUI 3.

Modelo de subprocesos de ASTA a STA

Si va a migrar código de una aplicación para UWP existente a un nuevo proyecto de WinUI 3 que use el SDK de Aplicaciones para Windows, tenga en cuenta que el nuevo proyecto usa el modelo de subprocesos de contenedor de subproceso único (STA), en lugar del modelo de subprocesos de STA de aplicación (ASTA) que usan las aplicaciones para UWP. Si el código asume el comportamiento no reentrante del modelo de subprocesos de ASTA, es posible que el código no se comporte según lo esperado.

Consulte también