Usar el Windows App SDK en una aplicación de Windows Forms (WinForms)

El Windows App SDK es la siguiente evolución en la plataforma de desarrollo de Windows app. Pero en este tema se muestra cómo se pueden usar las API de Windows App SDK (y las API de Windows Runtime) en una aplicación Windows Forms (WinForms)!

En muchos casos, querrás recrear tu aplicación WinForms en forma de una aplicación WinUI 3. Solo una de las ventajas de pasar a WinUI es tener acceso al Sistema de Diseño Fluent (consulte también Diseño y codificación de aplicaciones de Windows). Y WinUI forma parte del Windows App SDK, por lo que, naturalmente, una aplicación winUI también puede usar las otras características y API de Windows App SDK. En este tema no se trata el proceso de migración de la aplicación WinForms a WinUI.
Pero si encuentra que usa características de WinForms que aún no están disponibles en WinUI, puede seguir usando características de Windows App SDK (como Ciclo de vida de la aplicación, MRT Core, DWriteCore y otros) en la aplicación WinForms. En este tema te mostramos cómo.

Y en caso de que aún no tenga un proyecto de WinForms existente o quiera practicar el proceso, este tema incluye pasos para crear un proyecto de WinForms para que pueda seguirlos y configurarlo para llamar a las API de Windows App SDK.

Requisitos previos

Instalar herramientas para el Windows App SDK.
En este tema se tratan aplicaciones de WinForms empaquetadas y sin empaquetar. Si la aplicación WinForms está desempaquetada (que las aplicaciones winForms son de forma predeterminada), asegúrese de que todas las dependencias de las aplicaciones sin empaquetar estén instaladas (consulte Windows App SDK guía de implementación para aplicaciones dependientes del marco empaquetadas con ubicación externa o sin empaquetar). Una forma rápida de hacerlo es visitar Últimas descargas para el SDK de aplicaciones de Windows, luego descargar, descomprimir y ejecutar una de las descargas estables del entorno de ejecución.

Importante

La versión de Runtime que instale debe coincidir con la versión del paquete NuGet Microsoft.WindowsAppSDK que instalará en un paso posterior.

Para obtener más información sobre los términos desempaquetada y empaquetada, consulte Ventajas y desventajas de empaquetar la aplicación.

Cree un proyecto de WinForms si aún no tiene uno.

Si ya tiene un proyecto WinForms, puede pasar a la siguiente sección.

En Visual Studio, cree un nuevo proyecto de Windows Forms App (que es un proyecto .NET). Tenga cuidado de elegir la plantilla de proyecto con el nombre exacto Windows Forms App y no la Windows Forms App (.NET Framework).
Asigne al project un nombre y acepte las opciones predeterminadas.

Ahora tiene un proyecto que compila una aplicación WinForms sin empaquetar.

Configuración del project de WinForms para la compatibilidad con Windows App SDK

En primer lugar, editaremos el archivo project.

En Solution Explorer, haga clic con el botón derecho en el proyecto y elija Editar archivo de proyecto.
Este paso permite llamar a Windows Runtime (WinRT) API (incluidas las API de Windows App SDK). Dentro del elemento PropertyGroup se encuentra el elemento TargetFramework, que se establece en un valor como net6.0. Anexe al valor del framework de destino un identificador (en concreto, un identificador del framework de destino). Por ejemplo, use lo siguiente si la aplicación tiene como destino Windows 10, versión 2004:
```
<TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
```
También dentro del elemento PropertyGroup, agregue un elemento RuntimeIdentifiers de este modo:
```
<RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
```
De forma predeterminada, una aplicación de WinForms está desempaquetada (lo que significa que no está instalada mediante MSIX). Una aplicación sin empaquetar debe inicializar el entorno de ejecución de Windows App SDK antes de usar cualquier otra característica del Windows App SDK. Puede hacerlo automáticamente cuando la aplicación se inicie a través de la inicialización automática. Solo tiene que establecer (también dentro del elemento PropertyGroup) la propiedad del proyecto WindowsPackageType de manera adecuada, como sigue:
```
<WindowsPackageType>None</WindowsPackageType>
```
Si tiene necesidades avanzadas (como el control de errores personalizado o para cargar una versión específica del Windows App SDK), en lugar de auto-initialization puede llamar explícitamente a la API de arranque; 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.
Guarde y cierre el archivo del proyecto.

A continuación, instalaremos el paquete NuGet Windows App SDK en el project.

En Solution Explorer, haga clic con el botón derecho en el nodo Dependencies del project y elija Administrar paquetes Nuget... .
En la ventana NuGet Package Manager, seleccione la pestaña Browse e instale el Latest stableMicrosoft.WindowsAppSDK.

Usar algunas características de Windows App SDK en la aplicación WinForms

En esta sección se ofrece un ejemplo muy sencillo de llamar a las API de Windows App SDK desde una aplicación WinForms. Usa la característica MRT Core (consulte Administración de recursos con MRT Core). Si este ejemplo funciona para el proyecto WinForms (y si ha creado uno nuevo para este recorrido, lo hará), puede seguir estos pasos.

Abra Form1.cs (con el comando Diseñador de vistas) y arrastre un Botón y una Etiqueta fuera del Cuadro de herramientas y sobre el diseñador.
Haga doble clic en button1 para generar un controlador de eventos.
Ahora agregaremos código que usa la clase ResourceManager en el Windows App SDK para cargar un recurso de cadena.
1. Agregue un nuevo elemento Resources File (.resw) al project (déjelo con el nombre predeterminado de Resources.resw).
2. Con el archivo resources abierto en el editor, cree un nuevo recurso de cadena con las siguientes propiedades.
  - Nombre: Message
  - Valor: Hello, resources!
3. Guarde y cierre el archivo resources.
4. Abra Form1.cs (con el comando Ver código) y edite el controlador de eventos para que tenga este aspecto:
```
private void button1_Click(object sender, EventArgs e)
{
    // Construct a resource manager using the resource index generated during build.
    var manager =
        new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();

    // Look up a string in the resources file using the string's name.
    label1.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
}
```
Compile el project y ejecute la aplicación. Haga clic en el botón para ver la cadena Hello, resources! mostrada.

Sugerencia

Si en tiempo de ejecución ve un cuadro de mensaje que indica que la aplicación necesita una versión determinada del entorno de ejecución de Windows App y pregunta si desea instalarla ahora, haga clic en Yes. Eso le llevará a Últimas descargas para el Windows App SDK. Para obtener más información, consulte la sección Requisitos previos anterior.

Consulte también Runtime architecture para obtener más información sobre la Framework dependencia de paquetes que la aplicación toma cuando usa el Windows App SDK y los componentes adicionales necesarios para funcionar en una aplicación sin empaquetar.

Empaquete e implemente su aplicación de WinForms con MSIX

Algunas características y API de Windows (incluidas las API Windows App SDK notifications) requieren que la aplicación tenga package identity en tiempo de ejecución (es decir, la aplicación debe ser packaged). Para más información, consulte Características que requieren identidad del paquete.

En Solution Explorer en Visual Studio, haga clic con el botón derecho en la solución y elija Agregar>Nuevo Project... .
En el cuadro de diálogo Agregar un nuevo project, busque packaging, elija la plantilla C# Windows Application Packaging Project project y haga clic en Next.
Asigne al project el nombre y haga clic en Crear.
Queremos especificar qué aplicaciones de la solución se incluirán en el paquete. Por lo tanto, en el proyecto de empaquetado (no el proyecto de WinForms), haga clic con el botón derecho en el nodo Dependencies y elija Agregar referencia al proyecto... .
En la lista de proyectos de la solución, elija el project WinForms y haga clic en OK.
Expanda el nodo del proyecto Dependencies>Applications y confirme que se hace referencia a su proyecto WinForms y que está resaltado en negrita. Esto significa que se usará como punto de partida para el paquete.
Haga clic con el botón derecho en el proyecto de empaquetado y elija Establecer como Proyecto de Inicio.
Haga clic con el botón derecho en el proyecto WinForms y elija Editar Archivo del Proyecto.
Elimine <WindowsPackageType>None</WindowsPackageType>, guarde y cierre.
En la lista desplegable Plataformas de solución, elija x64 (en lugar de Cualquier CPU).
Confirme que puede compilar y ejecutar.

Ahora que ha empaquetado la aplicación de WinForms, puede llamar a las API que requieren la identidad del paquete. Por lo tanto, abra Form1.cs (con el comando Ver código) y edite el controlador de eventos para que tenga este aspecto:

private void button1_Click(object sender, EventArgs e)
{
    var notification = new AppNotificationBuilder()
        .AddArgument("action", "viewConversation")
        .AddArgument("conversationId", "9813")
        .AddText("Andrew sent you a picture")
        .AddText("Check this out, The Enchantments in Washington!")
        .BuildNotification();

    AppNotificationManager.Default.Show(notification);
}

Compile y vuelva a ejecutar. Haga clic en el botón y confirme que se muestra una notificación emergente. Cuando se llama desde un proceso que carece de identidad de paquete en tiempo de ejecución, las API de notificaciones producen una excepción.

Nota:

En los pasos de esta sección se muestra cómo crear una aplicación empaquetada. Una alternativa es crear una aplicación empaquetada con ubicación externa. Para obtener un recordatorio de todos estos términos, consulte Ventajas y desventajas de empaquetar la aplicación.

Comentarios

Resultoulle útil esta páxina?

Last updated on 2026-03-11