Introducción a WebView2 en aplicaciones de WinForms

Artículo
05/20/2022
15 minutos para leer

En este artículo se explica cómo configurar las herramientas de desarrollo y crear una aplicación WebView2 inicial para la plataforma WinForms y cómo aprender sobre los conceptos de WebView2 a lo largo del proceso.

Paso 1: Opcionalmente, descargue o clone el repositorio WebView2Samples.

Realice una de las siguientes acciones:

Cree un nuevo proyecto en Visual Studio, siguiendo los pasos que se indican a continuación. Si desea ver el proyecto completado, puede ver el directorio WinForms_GettingStarted en el WebView2Samples repositorio.
Descargue o clone el WebView2Samples repositorio, abra el proyecto completado en Visual Studio y siga los pasos de este artículo para comprender cómo crear el proyecto WinForms y comprender el código WebView2 agregado.

El ejemplo de Introducción correspondiente en GitHub: WinForms_GettingStarted/WinForms_GettingStarted.sln (sin archivo léame).

Paso 2: Instalar Visual Studio

Microsoft Visual Studio es necesario. Microsoft Visual Studio código no se admite en este tutorial.

Si Visual Studio aún no está instalado, abra la página Microsoft Visual Studio en una nueva ventana o pestaña e instale Visual Studio 2017 o posterior, como Visual Studio 2022 Professional.

A continuación, vuelva aquí y continúe a continuación.

Paso 3: Instalar un canal de vista previa de Microsoft Edge

Instale cualquier canal Microsoft Edge Insider (versión preliminar) (Beta, Dev o Canary) en un sistema operativo (SO) compatible:
- Windows7
- Windows 8.1
- Windows10
- Windows11
Se recomienda usar el canal Canary. La versión mínima necesaria es 82.0.488.0.

Paso 4: Instalación del entorno de ejecución de WebView2 (opcional)

Opcionalmente, instale el entorno de ejecución webView2. Consulte Microsoft Edge WebView2.

Si no está seguro, omita este paso; en su lugar, puede usar el canal de vista previa de Microsoft Edge del paso anterior.

Si quiere obtener más información ahora, consulte Descripción de las distintas versiones del SDK de WebView2.

En un paso posterior, instalará el SDK de WebView2 en el equipo, si aún no está instalado.

Continúe con los pasos siguientes.

Paso 5: Creación de una aplicación de ventana única

Comience con un proyecto de escritorio básico que contenga una sola ventana principal.

Abra Visual Studio.
Seleccione ArchivoNuevo > **** > Project.

Aparece la ventana Abrir reciente Visual Studio:
A la derecha, haga clic en la tarjeta Crear un nuevo proyecto .

Aparece la ventana crear un proyecto Visual Studio:
En el cuadro de texto Buscar , pegue o empiece a escribir lo siguiente:
```
C# Windows Forms App (.NET Framework)
```
Aparecen los resultados de la búsqueda y se enumeran los tipos de proyecto.
Seleccione la tarjeta C# Windows Forms App (.NET Framework) y, a continuación, haga clic en el botón Siguiente:
En el cuadro de texto Project nombre, escriba un nombre de proyecto. En este artículo del tutorial se usa el nombre WinForms_GettingStarted, como el nombre del directorio del repositorio para el proyecto completado.
En el cuadro de texto Ubicación , escriba una ruta de acceso, como "C:\Users\username\Documents\MyWebView2Projects".
En la lista desplegable Marco, seleccione .NET Framework 4.7.2 o posterior, como .NET Framework 4.8:
Haga clic en el botón Crear .

Se abre la ventana Visual Studio, que muestra el proyecto de línea base WinForms en el Explorador de soluciones y muestra una ventana del Diseñador de formularios:
Seleccione ArchivoGuardar **** > todo (Ctrl+Shift+S).
Seleccione DepurarIniciar **** > depuración (F5).

Se abre una ventana vacía de Form1 desde el nuevo proyecto WinForms:
Cierre la ventana Form1 .

Ahora tiene un proyecto de WinForms vacío que se ejecuta. A continuación, configure el proyecto para agregar contenido WebView2.

Paso 6: Instalación del SDK de WebView2

Para cada proyecto WebView2, use el administrador de paquetes de NuGet dentro de Visual Studio para agregar el SDK de WebView2 al proyecto. Instale el paquete de NuGet sdk de Microsoft.Web.WebView2 para que lo use el proyecto actual.

Use NuGet para agregar el SDK de WebView2 al proyecto, como se indica a continuación:

En Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto (no en el nombre de la solución anterior) y, a continuación, seleccione Administrar paquetes de NuGet:

El NuGet Administrador de paquetes se abre en Visual Studio.
Haga clic en la pestaña Examinar en la esquina superior izquierda.
Desactive la casilla Incluir versión preliminar .
En la barra de búsqueda, escriba WebView2 y, debajo de la barra de búsqueda, haga clic en Microsoft.Web.WebView2 para seleccionarlo:

Para hacer zoom, haga clic con el botón derecho en > Abrir imagen en la nueva pestaña.
Haga clic en el botón Instalar (o Actualizar). Se abre el cuadro de diálogo Vista previa de cambios :
Haga clic en el botón Aceptar .
Seleccione ArchivoGuardar **** > todo (Ctrl++Shift``S) para guardar el proyecto.
Cierre la ventana NuGet Administrador de paquetes.
Seleccione DepurarIniciar **** > depuración (F5) para compilar y ejecutar el proyecto.

El proyecto en ejecución muestra la misma ventana vacía que antes:
Cierre la ventana Form1 .

Ha agregado el SDK de WebView2 al proyecto, pero aún no ha agregado ningún código WebView2 al proyecto.

Paso 7: Creación de un único control WebView2

Ahora que el SDK de WebView2 está instalado para el proyecto WinForms, agregue un control WebView2 a la aplicación, como se indica a continuación:

El proyecto de inicio ya tiene un Form1.cs formulario, pero agregaremos otro, como Form2.cs, para ver cómo hacerlo.

Seleccione Project > Agregar formulario (Windows Forms).
En la ventana Agregar nuevo elemento, a la izquierda, seleccione Elementos > de Visual C#Windows Forms.
A la derecha, seleccione Formulario (Windows Forms) y, a continuación, haga clic en el botón Agregar:

El proyecto ahora tiene un formulario adicional, con nombre de archivo Form2.cs, que se muestra en el Diseñador de formularios y en Explorador de soluciones:
Haga clic en el lienzo Form1 . No usaremos Form2.
Seleccione ViewToolbox**** > .

Aquí es donde agrega contenido específico de WebView2 a la aplicación:
En el cuadro de herramientas, haga clic en WebView2 Windows Forms Control para expandir las opciones.

En Visual Studio 2017, de forma predeterminada, WebView2 no se muestra en el cuadro de herramientas. Para permitir que WebView2 se muestre en el cuadro de herramientas, seleccione HerramientasOpcionesGeneral > **** > > y establezca la opción Rellenar automáticamente el cuadro de herramientas en True.****
En el cuadro de herramientas, haga clic o arrastre el control WebView2 al lienzo del Diseñador de formularios del control que agregó, como Form2.cs:
Arrastre los lados del control WebView2 para que rellene casi todo el lienzo.
Asegúrese de que el nuevo control WebView2 del formulario está seleccionado. En el panel Propiedades , en la sección Diseño , establezca la propiedad (Name) en webView (minúscula 'w', mayúscula 'V', sin sufijo numérico). El control podría denominarse inicialmente algo más, como webView21. Use los botones de opción Clasificación por categorías y Orden alfabético según sea necesario para buscar propiedades:
En el panel Propiedades, en la sección Misc, establezca la propiedad https://www.microsoft.comSource en . La propiedad Source establece la dirección URL inicial que se mostrará en el control WebView2.
Seleccione ArchivoGuardar **** > todo (Ctrl++Shift``S) para guardar el proyecto.
Presione F5 para compilar y ejecutar el proyecto.

El control WebView2 muestra el contenido de https://www.microsoft.com, en un control WebView2 en el formulario Windows Forms, con un vínculo Omitir al contenido principal si presiona Alt+Tab para cambiar a la ventana:
Si es necesario, haga clic en el vínculo Omitir al contenido principal .

El control WebView2 muestra el contenido de https://www.microsoft.com, en un control WebView2 en el formulario Windows Forms:
Cierre la ventana Form1 .

Si está trabajando en un monitor de alta resolución, es posible que tenga que configurar la aplicación de Windows Forms para que admita valores altos de PPP.

Paso 8: Agregar controles y eventos de cambio de tamaño de ventana de proceso

Agregue más controles al formulario de Windows Forms desde el cuadro de herramientas y, a continuación, procese eventos de cambio de tamaño de ventana, como se indica a continuación.

Seleccione ViewToolbox**** > o haga clic en la pestaña Cuadro de herramientas de la izquierda.
En el cuadro de herramientas, haga clic en Controles comunes.

Agregue un control de cuadro de texto, como se indica a continuación:
Arrastre el control TextBox al lienzo del Diseñador de formularios Form1.cs .
Asegúrese de que el control TextBox tiene el foco.
En el panel Propiedades , en la sección Diseño , cambie (Nombre) (probablemente de textBox1) a addressBar.

Agregue un control de botón, como se indica a continuación:
Arrastre un control Button al lienzo del Diseñador de formularios Form1.cs .
Asegúrese de que el control de botón tiene el foco.
En el panel Propiedades , en la sección Diseño , cambie (Nombre) (probablemente de button1) a goButton.
En el panel Propiedades , en la sección Apariencia en negrita (alrededor de 15 propiedades hacia abajo), cambie la propiedad Text (probablemente de button1) a Go!

Alinee el cuadro de texto y el botón existente, como se indica a continuación:
Coloque el cuadro de texto en el lado izquierdo del formulario, alineado verticalmente con el botón, como se muestra a continuación:
Cambie el tamaño del cuadro de texto como se muestra:
Haga clic en VerCódigo **** > para abrir Form1.cs.

Defina Form_Resize para mantener los controles en su lugar cuando se cambie el tamaño de la ventana de la aplicación, como se indica a continuación.

Elimine el código siguiente:

   public Form1()
{
   InitializeComponent();
}

Pegue este código en la misma ubicación:

public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
}

private void Form_Resize(object sender, EventArgs e)
{
   webView.Size = this.ClientSize - new System.Drawing.Size(webView.Location);
   goButton.Left = this.ClientSize.Width - goButton.Width;
   addressBar.Width = goButton.Left - addressBar.Left;
}

Form_Resize código agregado.

Seleccione ArchivoGuardar **** > todo (Ctrl++Shift``S) para guardar el proyecto.
Presione F5 para compilar y ejecutar el proyecto.

Aparece una ventana de Form1 que muestra el contenido de la página web desde https://www.microsoft.com:

Si presiona Alt+Tab para cambiar a la ventana Form1 , es posible que tenga que hacer clic en el vínculo Omitir al contenido principal que se agrega.
Desplácese la ventana hacia arriba y hacia abajo con la rueda del mouse. Los controles de entrada permanecen en su lugar.
Arrastre la esquina de la ventana para cambiar su tamaño. El cuadro de texto cambia el ancho.
Cierre la ventana Form1 .

Permitir que los usuarios cambien la dirección URL que muestra el control WebView2; para ello, lea el texto especificado en el cuadro de texto para que actúe como una barra de direcciones.

Seleccione ViewCode > para**** que Form1.cs esté abierto en el editor de código.
En Form1.cs, agregue el CoreWebView2 espacio de nombres insertando el código siguiente en la parte superior del archivo como línea 1:
```
using Microsoft.Web.WebView2.Core;
```
Seleccione la pestaña Form1.cs [Diseño] y haga doble clic en el Go! botón. El goButton_Click método se agrega en el Form1.cs archivo.
Pegue el código siguiente en el archivo para reemplazar el método vacío goButton_Click , de modo que el cuerpo del método sea el siguiente:
```
private void goButton_Click(object sender, EventArgs e)
{
   if (webView != null && webView.CoreWebView2 != null)
   {
      webView.CoreWebView2.Navigate(addressBar.Text);
   }
}
```
Ahora, la goButton_Click función navegará por el control WebView2 hasta la dirección URL especificada en el cuadro de texto de la barra de direcciones.
Seleccione ArchivoGuardar **** > todo (Ctrl++Shift``S) para guardar el proyecto.
Presione F5 para compilar y ejecutar el proyecto.
En la barra de direcciones, escriba una dirección URL que comience por https, como https://www.bing.com, y, a continuación, haga clic en Go! Botón:

El control WebView2 muestra el contenido de la página web de la dirección URL.
En la barra de direcciones, escriba una cadena que no empiece por http, como www.bing.com, y, a continuación, haga clic en Go! de puntos suspensivos (...).

Se ArgumentException produce un si la dirección URL no comienza con http:// o https://.
Seleccione DepurarIniciar**** > depuración o haga clic en Continuar. Se cierra la ventana Form1 .

Durante la navegación por la página web, el control WebView2 genera eventos. La aplicación que hospeda controles WebView2 escucha los eventos siguientes:

NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted

Para obtener más información, vea Eventos de navegación para aplicaciones WebView2.

Eventos de navegación.

Cuando se produce un error, se generan los siguientes eventos y pueden depender de la navegación a una página web de error:

SourceChanged
ContentLoading
HistoryChanged

Nota

Si se produce una redirección HTTP, hay varios NavigationStarting eventos en una fila.

Para demostrar cómo usar los eventos, empiece por registrar un controlador para NavigationStarting que cancele las solicitudes que no usen HTTPS.

En Form1.cs, actualice el Form1() constructor para que coincida con el código siguiente y agregue también la EnsureHttps(sender, args) función debajo del constructor, como se indica a continuación:

public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);

   webView.NavigationStarting += EnsureHttps;
}

void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      args.Cancel = true;
   }
}

En el constructor, EnsureHttps se registra como controlador de eventos en el NavigationStarting evento en el control WebView2.

Seleccione ArchivoGuardar **** > todo (Ctrl++Shift``S) para guardar el proyecto.
Presione F5 para compilar y ejecutar el proyecto.
En la barra de direcciones, escriba una dirección URL que comience por https, como https://www.bing.com, y, a continuación, haga clic en Go! de puntos suspensivos (...).

Se carga la dirección URL https; el contenido web cambia del valor predeterminado, Microsoft.com, a Bing.com.
En la barra de direcciones, escriba una dirección URL que comience por http, como http://www.microsoft.com, y, a continuación, haga clic en Go! de puntos suspensivos (...).

La dirección URL http no se carga; se muestra la página web Bing.com. Por el contrario, entrar http://www.microsoft.com en Microsoft Edge funciona; redirige al sitio https para Microsoft.com.
En la barra de direcciones, escriba una dirección URL que comience por https, como https://www.microsoft.com, y, a continuación, haga clic en Go! de puntos suspensivos (...).

Se carga la dirección URL https; ahora aparece la página web de Microsoft.com, ya que ha agregado los "s" después de "http".

Paso 11: Scripting

Puede usar aplicaciones host para insertar código JavaScript en controles WebView2 en tiempo de ejecución. Puede realizar una tarea en WebView2 para ejecutar JavaScript arbitrario o agregar scripts de inicialización. JavaScript insertado se aplica a todos los nuevos documentos de nivel superior y a los marcos secundarios hasta que se quita JavaScript. El Código JavaScript insertado se ejecuta con un tiempo específico.

Ejecute el Código JavaScript insertado después de la creación del objeto global.
Ejecute el Código JavaScript insertado antes de que se ejecute cualquier otro script incluido en el documento HTML.

Por ejemplo, agregue un script que envíe una alerta cuando un usuario navegue a un sitio que no sea HTTPS, como se indica a continuación:

Modifique la EnsureHttps función para agregar la siguiente línea que contiene ExecuteScriptAsync:

void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      webView.CoreWebView2.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
      args.Cancel = true;
   }
}

La línea agregada inserta un script en el contenido web que usa el método ExecuteScriptAsync . El script agregado es:

alert('{uri} is not safe, try an https link')

Seleccione ArchivoGuardar > todo (Ctrl+Mayús+S) para guardar el proyecto.
Presione F5 para compilar y ejecutar el proyecto.
Intente ir a http://www.bing.com (con http en lugar de https prefijo).

La aplicación muestra una alerta:

Paso 12: Comunicación entre el host y el contenido web

El host y el contenido web pueden usarse postMessage para comunicarse entre sí de la siguiente manera:

El contenido web de un control WebView2 puede usarse window.chrome.webview.postMessage para publicar un mensaje en el host. El host controla el mensaje mediante cualquier registro WebMessageReceived en el host.
Hospeda mensajes de publicación en contenido web en un control WebView2 mediante CoreWebView2.PostWebMessageAsString o CoreWebView2.PostWebMessageAsJSON. Estos mensajes los detectan los controladores agregados a window.chrome.webview.addEventListener.

El mecanismo de comunicación pasa mensajes del contenido web al host mediante funcionalidades nativas.

En el proyecto, cuando el control WebView2 navega a una dirección URL, muestra la dirección URL en la barra de direcciones y alerta al usuario de la dirección URL que se muestra en el control WebView2.

En Form1.cs, actualice el Form1() constructor y cree una InitializeAsync() función debajo de él, que coincida con el código siguiente:
```
public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
}
```
La InitializeAsync función espera a EnsureCoreWebView2Async, porque la inicialización de CoreWebView2 es asincrónica.

A continuación, registre un controlador de eventos para responder a WebMessageReceived. Este controlador de eventos se registrará después de CoreWebView2 inicializarse.

En Form1.cs, actualice InitializeAsyncy agréguelo UpdateAddressBar a continuación, como se indica a continuación:

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
}

void UpdateAddressBar(object sender, CoreWebView2WebMessageReceivedEventArgs args)
{
   String uri = args.TryGetWebMessageAsString();
   addressBar.Text = uri;
   webView.CoreWebView2.PostWebMessageAsString(uri);
}

A continuación, para que WebView2 envíe y responda al mensaje web, después CoreWebView2 de inicializarse, el host insertará un script en el contenido web para:

Envíe la dirección URL al host mediante postMessage.
Registre un controlador de eventos para mostrar un mensaje enviado desde el host, en un cuadro de alerta, antes de mostrar el contenido de la página web.

En Form1.cs, actualice InitializeAsync para que coincida con el código siguiente:

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;

   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.postMessage(window.document.URL);");
   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.addEventListener(\'message\', event => alert(event.data));");
}

Seleccione ArchivoGuardar **** > todo (Ctrl++Shift``S) para guardar los cambios.
Presione F5 para compilar y ejecutar el proyecto.
Escriba una dirección URL, como https://www.bing.com:

Inicialmente aparece una alerta que muestra la dirección URL resultante que se envía desde el sitio web host.
Haga clic en el botón Aceptar .

El control WebView2 ahora muestra la nueva dirección URL en la barra de direcciones y el contenido de la página web de la dirección URL se muestra en el control WebView2 de la ventana WinForms:
- Cuando se inicia la aplicación, la dirección URL predeterminada es https://www.microsoft.comy la dirección mostrada resultante muestra la configuración regional, como https://www.microsoft.com/en-us/.
- Si escribe https://www.bing.com, la dirección resultante es una variante, como https://www4.bing.com/?form=DCDN.

Enhorabuena, ha creado su primera aplicación WebView2.

Consulte también

developer.microsoft.com:

Microsoft Edge WebView2: introducción inicial a las características de WebView2 en developer.microsoft.com.

Páginas locales:

Ejemplo de WebView2: aplicación de explorador WinForms : muestra más API de WebView2 que el tutorial actual.
Administrar las carpetas de datos de usuario
Código de ejemplo para WebView2 : una guía para el WebView2Samples repositorio.
Procedimientos recomendados de desarrollo para aplicaciones WebView2
Consulte también en Introducción a Microsoft Edge WebView2: artículos conceptuales y de procedimientos sobre la compilación e implementación de aplicaciones WebView2.

GitHub:

Repositorio WebView2Samples : un ejemplo completo de las funcionalidades de WebView2.

Referencia de API:

NuGet:

SDK de Microsoft.Web.WebView2 en nuget.org