Compartir a través de

Uso del SDK de Aplicaciones para Windows en una aplicación de Windows Forms (WinForms)

  • Artículo

El SDK de Aplicaciones para Windows es la siguiente evolución en la plataforma de desarrollo de aplicaciones de Windows. Pero en este tema se muestra cómo puede usar las API del SDK de Aplicaciones para Windows (y las API de Windows Runtime) en una aplicación de Windows Forms (WinForms).

  • En muchos casos, querrá volver a crear la aplicación de WinForms en forma de una aplicación de WinUI 3. Una de las ventajas de pasar a WinUI 3 es tener acceso al Sistema Fluent Design (consulte también Diseño y programación de aplicaciones de Windows). Y WinUI 3 forma parte del SDK de Aplicaciones para Windows, por lo que, naturalmente, una aplicación WinUI 3 también puede usar las otras características y API del SDK de aplicaciones para Windows. En este tema no se trata el proceso de migración de la aplicación de WinForms a WinUI 3.
  • Pero si cree que usa características de WinForms que aún no están disponibles en WinUI 3, puede seguir usando las características del SDK de Aplicaciones para Windows (como el ciclo de vida de la aplicación, MRT Core, DWriteCore, entre otras) en la aplicación de 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 seguirlo y configurarlo para llamar a las API del SDK de Aplicaciones para Windows.

Requisitos previos

  1. Instalación de herramientas para el SDK de Aplicaciones para Windows.
  2. En este tema se tratan aplicaciones de WinForms empaquetadas y sin empaquetar. Si la aplicación de WinForms está desempaquetada (las aplicaciones de WinForms lo están de forma predeterminada), asegúrese de que todas las dependencias de las aplicaciones sin empaquetar están instaladas (consulte Guía de implementación del SDK de Aplicaciones para Windows para aplicaciones dependientes del marco de trabajo empaquetadas con ubicación externa o sin empaquetar). Una forma rápida de hacerlo es consultar las Descargas más recientes del SDK de Aplicaciones para Windows y luego descargar, descomprimir y ejecutar una de las descargas en tiempo de ejecución estables de la versió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 nuevo proyecto de WinForms si aún no ha creado ninguno.

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

  1. En Visual Studio, cree un nuevo proyecto de Aplicación de Windows Forms de C# (que es un proyecto .NET). Tenga cuidado de elegir la plantilla de proyecto con el nombre exacto de Aplicación de Windows Forms, y no la de Windows Forms (.NET Framework).
  2. Asigne un nombre al proyecto y acepte las opciones predeterminadas.

Ahora tiene un proyecto que permite compilar una aplicación de WinForms sin empaquetar.

Configuración del proyecto de WinForms para la compatibilidad con el SDK de Aplicaciones para Windows

En primer lugar, editaremos el archivo del proyecto.

  1. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Editar archivo del proyecto.

  2. Este paso le permite llamar a las API de Windows Runtime (WinRT) (incluidas las API del SDK de Aplicaciones para Windows). Dentro del elemento PropertyGroup se encuentra el elemento TargetFramework, que se establece en un valor como net6.0. Anexe al valor de la plataforma de destino un moniker (en concreto, un Moniker de la plataforma de destino). Por ejemplo, use lo siguiente si la aplicación tiene como destino Windows 10, versión 2004:

    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>

  3. También dentro del elemento PropertyGroup, agregue un elemento RuntimeIdentifiers, de esta manera:

    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>

  4. 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 del SDK de Aplicaciones para Windows antes de usar cualquier otra característica del SDK de Aplicaciones para Windows. Puede hacerlo automáticamente cuando la aplicación se inicie a través de la inicialización automática. Acaba de establecer (también dentro del elemento PropertyGroup) la propiedad WindowsPackageType del proyecto adecuadamente, de la siguiente manera:

    <WindowsPackageType>None</WindowsPackageType>

    Si tiene necesidades avanzadas (como el control de errores personalizado o para cargar una versión específica del SDK de Aplicaciones para Windows), en lugar de la inicialización automática, puede llamar explícitamente a la API del cargador de arranque; para obtener más información, consulte Uso del entorno de ejecución del SDK de Aplicaciones para Windows para aplicaciones empaquetadas con ubicación externa o sin empaquetar.

  5. Guarda y cierra el archivo de proyecto.

A continuación, instalaremos el paquete NuGet del SDK de Aplicaciones para Windows en el proyecto.

  1. En el Explorador de soluciones, haga clic con el botón derecho en el nodo Dependencias del proyecto y elija Administrar paquetes NuGet...
  2. En la ventana Administrador de paquetes NuGet, seleccione la pestaña Examinar e instale el paquete Estable Microsoft.WindowsAppSDK más reciente.

Uso de algunas características del SDK de Aplicaciones para Windows en la aplicación de WinForms

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

  1. 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.

  2. Haga doble clic en button1 para generar un controlador de eventos.

  3. Ahora agregaremos código que usa la clase ResourceManager en el SDK de Aplicaciones para Windows para cargar un recurso de cadena.

    1. Agregue un nuevo elemento Resources File (.resw) al proyecto (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;
}

  4. Compile el proyecto 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 de Windows App Runtime y le pregunta si quiere instalarla ahora, haga clic en Sí. Eso le llevará a las Descargas más recientes para el SDK de Aplicaciones para Windows. Para obtener más información, consulte la sección Requisitos previos anterior.

Consulte también Arquitectura en tiempo de ejecución para obtener más información sobre la dependencia del paquete Framework que toma la aplicación cuando usa el SDK de Aplicaciones para Windows y los componentes adicionales necesarios para trabajar 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 de notificaciones del SDK de Aplicaciones para Windows) requieren que la aplicación tenga la identidad del paquete en tiempo de ejecución (es decir, la aplicación debe estar empaquetada). Para más información, consulte Características que requieren identidad del paquete.

  1. En el Explorador de soluciones de Visual Studio, haga clic con el botón derecho en la solución y elija Agreagr>Nuevo proyecto....
  2. En el cuadro de diálogo Agregar un nuevo proyecto, busque empaquetado, elija la plantilla de proyecto Proyecto de paquete de aplicación de Windows C# y haga clic en Siguiente.
  3. Proporcione un nombre al proyecto y haga clic en Crear.
  4. Queremos especificar qué aplicaciones de la solución se incluirán en el paquete. Por lo tanto, en el proyecto de empaquetado (no en el proyecto de WinForms), haga clic con el botón derecho en el nodo Dependencias y elija Agregar referencia de proyecto....
  5. En la lista de proyectos de la solución, elija su proyecto de WinForms y haga clic en Aceptar.
  6. Expanda el nodo Dependencias>Aplicaciones del proyecto de empaquetado y confirme que se hace referencia al proyecto de WinForms y aparece resaltado en negrita. Esto significa que se usará como punto de partida para el paquete.
  7. Haga clic con el botón derecho en el proyecto de empaquetado y seleccione Establecer como proyecto de inicio.
  8. Haga clic con el botón derecho en el proyecto de WinForms y elija Editar archivo del proyecto.
  9. Elimine <WindowsPackageType>None</WindowsPackageType>, guarde y cierre.
  10. En la lista desplegable Plataformas de solución, elija x64 (en lugar de Cualquier CPU).
  11. 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 del sistema. 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.