Introducción a WebView2 en aplicaciones WinForms

  • Artículo

Este tutorial le ayuda a:

  • Configure las herramientas de desarrollo.
  • Use la plantilla de proyecto de Visual Studio de C# Windows Forms App (.NET Framework) para crear un proyecto de WinForms.
  • Instale el paquete del SDK Microsoft.Web.WebView2 para el proyecto WinForms.
  • Obtenga información sobre los conceptos de WebView2 en el camino.

Paso 1: Clonar o descargar opcionalmente el repositorio WebView2Samples

Realice cualquiera de las siguientes acciones:

  • Cree un nuevo proyecto en Visual Studio a partir de una plantilla de proyecto, siguiendo los pasos descritos en las secciones siguientes. Esto le proporcionará el código y la estructura del proyecto más recientes.

  • Clone o descargue 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. Consulte Descarga del repositorio WebView2Samples en Configuración del entorno de desarrollo para WebView2. Una versión completa de este proyecto de tutorial está disponible en el directorio del repositorio WebView2Samples WinForms_GettingStarted.

    • Nombre de ejemplo: Win32_GettingStarted
    • Directorio del repositorio: Win32_GettingStarted
    • Archivo de solución: WebView2GettingStarted.sln

Es posible que el ejemplo del repositorio no esté tan actualizado como un proyecto que cree mediante las plantillas de proyecto de Visual Studio más recientes.

Paso 2: Instalación de Visual Studio

Se requiere Microsoft Visual Studio. Microsoft Visual Studio Code no se admite en este tutorial.

  1. 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: Creación de una aplicación de ventana única

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

  1. Abra Visual Studio.

  2. Seleccione Archivo>Nuevo>Proyecto.

    Aparece la ventana Abrir reciente de Visual Studio:

    El panel de apertura de Visual Studio muestra la tarjeta Crear un nuevo proyecto

  3. A la derecha, haga clic en la tarjeta Crear un nuevo proyecto . Se abre la ventana Crear un proyecto de Visual Studio.

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

  5. Seleccione la tarjeta C# Windows Forms App (.NET Framework). Asegúrese de que el nombre coincide, con un icono de C# y, a continuación, el nombre Windows Forms App (.NET Framework). A continuación, haga clic en el botón Siguiente :

    En el panel

  6. En el cuadro de texto Nombre del proyecto, 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.

  7. En el cuadro de texto Ubicación , escriba una ruta de acceso, como "C:\Users\username\Documents\MyWebView2Projects".

  8. En la lista desplegable Marco , seleccione .NET Framework 4.7.2 o posterior, como .NET Framework 4.8:

    Rellenar la ventana

  9. Haga clic en el botón Crear.

    Se abre la ventana de Visual Studio, que muestra el proyecto de línea base WinForms en el Explorador de soluciones y muestra una ventana Formulario Designer:

    La ventana de Visual Studio, que muestra el proyecto de línea base WinForms y un Designer De formularios

  10. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

  11. Seleccione Depurar>iniciar depuración (F5).

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

    Ventana Form1 vacía del nuevo proyecto WinForms

  12. 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 4: Instalación del SDK de WebView2

Para cada proyecto WebView2, use el administrador de paquetes NuGet en Visual Studio para agregar el SDK de WebView2 al proyecto. Instale el paquete NuGet del 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:

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

    Administración de paquetes NuGet

    El Administrador de paquetes NuGet se abre en Visual Studio.

  2. Haga clic en la pestaña Examinar en la esquina superior izquierda.

  3. Desactive la casilla Incluir versión preliminar .

  4. En la barra de búsqueda, escriba WebView2 y, debajo de la barra de búsqueda, haga clic en Microsoft.Web.WebView2 para seleccionarlo:

    Administrador de paquetes NuGet en Visual Studio, instalando el paquete NuGet del SDK de Microsoft.Web.WebView2 para el proyecto actual

    Para hacer zoom, haga clic con el botón derecho en >Abrir imagen en la nueva pestaña.

  5. Haga clic en el botón Instalar (o Actualizar). Se abre el cuadro de diálogo Vista previa de cambios :

    Cuadro de diálogo Vista previa de cambios

  6. Haga clic en el botón Aceptar .

  7. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.

  8. Cierre la ventana Administrador de paquetes NuGet.

  9. Seleccione Depurar>iniciar depuración (F5) para compilar y ejecutar el proyecto.

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

    Ventana Form1 vacía del nuevo proyecto WinForms

  10. 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 5: 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.

  1. Seleccione Project>Add Form (Windows Forms).

  2. En la ventana Agregar nuevo elemento, a la izquierda, seleccione Elementos> de Visual C#Windows Forms.

  3. A la derecha, seleccione Formulario (Windows Forms) y, a continuación, haga clic en el botón Agregar:

    La ventana

    El proyecto ahora tiene un formulario adicional, con el nombre Form2.csde archivo , que se muestra en el Designer Formulario y en Explorador de soluciones:

    El formulario agregado, Form2.cs, en el Designer Formulario y en Explorador de soluciones

  4. Haga clic en el lienzo Form1 . No usaremos Form2.

  5. Seleccione Ver>cuadro de herramientas.

    Aquí es donde agrega contenido específico de WebView2 a la aplicación:

  6. 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, seleccioneOpciones>de herramientas>General> y establezca la opción Rellenar automáticamente el cuadro de herramientas en True.

  7. En el cuadro de herramientas, haga clic o arrastre el control WebView2 hasta el lienzo Forms Designer del control que agregó, como Form2.cs:

    Cuadro de herramientas que muestra WebView2

  8. Arrastre los lados del control WebView2 para que rellene casi todo el lienzo.

  9. 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:

    Propiedades del control WebView2

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

  11. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.

  12. Pulse 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 ha presionado Alt+Pestaña para cambiar a la ventana:

    Alt+Pestaña hace que la aplicación de ejemplo muestre inicialmente un vínculo

  13. 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:

    La aplicación de ejemplo muestra el sitio web de Microsoft

  14. 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 6: Agregar controles y procesar eventos de cambio de tamaño de ventana

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.

  1. Seleccione Ver>cuadro de herramientas o haga clic en la pestaña Cuadro de herramientas de la izquierda.

  2. En el cuadro de herramientas, haga clic en Controles comunes.

    Agregue un control de cuadro de texto, como se indica a continuación:

  3. Arrastre el control TextBox al lienzo Designer Form1.cs Formulario.

  4. Asegúrese de que el control TextBox tiene el foco.

  5. 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:

  6. Arrastre un control Button al lienzo Designer Form1.cs Formulario.

  7. Asegúrese de que el control de botón tiene el foco.

  1. En el panel Propiedades , en la sección Apariencia en negrita (aproximadamente 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:

  2. Coloque el cuadro de texto en el lado izquierdo del formulario, alineado verticalmente con el botón, como se muestra a continuación:

    Diseñador de WinForms

  3. Cambie el tamaño del cuadro de texto como se muestra:

    Cuadro de texto y botón del diseñador de WinForms

  4. Haga clic en Ver>có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.

  5. Elimine el código siguiente:

       public Form1()
{
   InitializeComponent();
}

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

  7. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.

  8. Pulse F5 para compilar y ejecutar el proyecto.

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

    Ventana de Formulario1 WinForm que muestra el contenido de la página web de 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 ha agregado.

  9. Desplácese la ventana hacia arriba y hacia abajo con la rueda del mouse. Los controles de entrada permanecen en su lugar.

  10. Arrastre la esquina de la ventana para cambiar su tamaño. El cuadro de texto cambia el ancho.

  11. Cierre la ventana Form1 .

Paso 7: Navegación

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.

  1. Seleccione Ver>código para que Form1.cs esté abierto en el editor de código.

  2. 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;

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

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

  5. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.

  6. Pulse F5 para compilar y ejecutar el proyecto.

  7. 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 el botón Go! :

    bing.com

    El control WebView2 muestra el contenido de la página web de la dirección URL.

  8. En la barra de direcciones, escriba una cadena que no empiece por http, como www.bing.com, y, a continuación, haga clic en el botón Ir!

    Excepción de argumento debido a la entrada de una dirección URL que no es

    Se ArgumentException produce un si la dirección URL no comienza con http:// o https://.

  9. Seleccione Depurar>Detener depuración o haga clic en Continuar. Se cierra la ventana Form1 .

Paso 8: Eventos de navegación

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.

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

  2. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.

  3. Pulse F5 para compilar y ejecutar el proyecto.

  4. 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 el botón Go! .

    Se carga la dirección URL https; el contenido web cambia del valor predeterminado, Microsoft.com, a Bing.com.

  5. 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 el botón Go! .

    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.

  6. 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 el botón Go! .

    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 9: 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:

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

  2. Seleccione Guardartodo en archivo > (Ctrl+Mayús+S) para guardar el proyecto.

  3. Pulse F5 para compilar y ejecutar el proyecto.

  4. Intente ir a http://www.bing.com (con http en lugar de https prefijo).

    La aplicación muestra una alerta:

    Una alerta HTTP, que indica try https en su lugar

Paso 10: 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.

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

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

  3. 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));");
}

  4. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar los cambios.

  5. Pulse F5 para compilar y ejecutar el proyecto.

  6. Escriba una dirección URL, como https://www.bing.com:

    La dirección URL de la barra de direcciones actualizada se muestra inicialmente en un cuadro de alerta

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

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

    La aplicación muestra la dirección URL en la barra de direcciones.

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

Distribución de una aplicación WebView2

Si tuviera que distribuir la aplicación que resulta de este tutorial, tendría que distribuir el entorno de ejecución de WebView2 junto con la aplicación. El entorno de ejecución de WebView2 se instalaría automáticamente en las máquinas del usuario. Para obtener más información, consulte Distribución de la aplicación y el entorno de ejecución de WebView2.

Vea también