Introducción a WebView2 en aplicaciones WPF

  • Artículo

En este artículo se explica cómo configurar las herramientas de desarrollo y crear una aplicación WebView2 inicial para Windows Presentation Foundation (WPF) y obtener información sobre los conceptos de WebView2 en el camino.

En este tutorial, usará la plantilla de proyecto Aplicación WPF o Aplicación WPF (.NET Framework) para crear una aplicación WPF y, a continuación, instalará el SDK de WebView2 para que el proyecto agregue WebView2.

Proyecto completado

Hay disponible una versión completa de este proyecto de tutorial en el repositorio WebView2Samples :

  • Nombre de ejemplo: WPF_GettingStarted
  • Directorio del repositorio: WPF_GettingStarted
  • Archivo de solución: WPFSample.sln

Paso 1: Instalación de Visual Studio con compatibilidad con .NET

Este tutorial requiere Microsoft Visual Studio, no Microsoft Visual Studio Code. En este artículo se describe principalmente el uso de Visual Studio 2022.

  1. Instale Visual Studio. Instale la compatibilidad con el desarrollo de escritorio de .NET para obtener las plantillas de proyecto necesarias, como se indica a continuación.

  2. Si está en la pantalla de inicio de Visual Studio, desplácese hasta la parte inferior del Create un nuevo cuadro de diálogo de proyecto y haga clic en el vínculo Abrir sin código. Se abre Visual Studio.

  3. En Visual Studio, seleccione Herramientas>Obtener herramientas y características. Se abre la ventana Instalador de Visual Studio y se abre el cuadro de diálogo Modificar.

  4. Seleccione la carga de trabajo desarrollo de escritorio de .NET para que haya una marca de verificación en ella.

  5. En la sección Detalles> de instalación.Desarrollo> de escritorio de NETincluido a la derecha, asegúrese de que aparecen las herramientas de desarrollo de escritorio de .NET y las herramientas de desarrollo de .NET Framework 4.7.2, con una marca de verificación junto a ellas.

  6. En la sección Detalles> de instalación. Desarrollo> de escritorio de NETOpcional a la derecha:

    • Si usa Visual Studio 2022, asegúrese de que las herramientas de desarrollo para .NET estén seleccionadas:

    Cuadro de diálogo

    • Si usa Visual Studio 2019, asegúrese de que las herramientas de desarrollo de .NET están seleccionadas:

    Cuadro de diálogo

  7. Haga clic en el botón Modificar .

Este tutorial también funciona con Visual Studio 2017. Consulte Descargas anteriores de Visual Studio. Instale la compatibilidad con .NET para obtener las plantillas de proyecto necesarias, de forma similar a los pasos anteriores.

Paso 2: Instalación de un canal de versión preliminar de Microsoft Edge

  1. Descargue cualquier canal de versión preliminar de Microsoft Edge (Beta, Desarrollo o Canary) en un sistema operativo compatible:

    • Windows 10
    • Windows 11

    Para ello, vaya a Convertirse en microsoft edge insider. Los canales de vista previa también se denominan canales Insider.

    Se recomienda usar el canal Canary de Microsoft Edge. La versión mínima necesaria es 82.0.488.0.

Paso 3: Create una aplicación WebView2 de una sola ventana

Empiece por crear un proyecto de escritorio básico que contenga una sola ventana principal.

  1. Decida si desea crear un proyecto de .NET Core/5/6 (más reciente) o un proyecto de aplicación de WPF (.NET Framework) (anterior). Para obtener más información, consulte:

  2. Siga la sección correspondiente a continuación.

Creación de un proyecto de .NET Core/5/6

Si va a crear un proyecto de .NET Core/5/6, siga estos pasos. De lo contrario, vaya a Creación de un proyecto de aplicación wpf (.NET Framework).

  1. Abra Microsoft Visual Studio, como Visual Studio 2022.

  2. En el panel de apertura, haga clic en Create nuevo proyecto. O bien, en la ventana principal de Visual Studio, seleccione Archivo>nuevo>proyecto. Se abre el cuadro de diálogo Create un nuevo proyecto.

  3. En el cuadro de texto Búsqueda para plantillas, escriba WPF Application. El Create un nuevo panel de proyecto muestra las plantillas de proyecto instaladas que coinciden con el texto especificado. En este artículo se muestran los diálogos de C# en lugar de VB; Ambos lenguajes son compatibles con WebView2.

  4. Si usa Visual Studio 2022, haga clic en una plantilla de proyecto que tenga el título Aplicación WPF y el texto de descripción Un proyecto para crear una aplicación wpf de .NET:

    Selección de la plantilla

    Si usa Visual Studio 2019, haga clic en una plantilla de proyecto que tenga el título Aplicación WPF y el texto de descripción Un proyecto para crear una aplicación WPF de .NET Core:

    Selección de la plantilla

    Si la plantilla de proyecto anterior no aparece en la lista, consulte Paso 1: Instalación de Visual Studio con compatibilidad con .NET anterior para instalar herramientas de desarrollo de escritorio de .NET.

  5. Haga clic en el botón Siguiente .

    Se abre el cuadro de diálogo Configurar el nuevo proyecto: Aplicación WPF :

    Cuadro de diálogo

  6. En el cuadro de texto Nombre del proyecto, escriba un nombre de proyecto, como MyWpfDotnetCoreWv2App.

  7. En el cuadro de texto Ubicación , seleccione una ruta de acceso en la unidad local, como C:\Users\myusername\Documents\MyProjectsy, a continuación, haga clic en el botón Siguiente .

    Aparece el cuadro de diálogo Información adicional , con una lista desplegable Marco de destino :

    Cuadro de diálogo

  8. Seleccione .NET Core 3.1 o posterior, como .NET 6.0. (No seleccione .NET Core 3.0). A continuación, haga clic en el botón Create.

    El proyecto inicial de aplicación WPF de .NET Core se abre en Visual Studio:

    Proyecto inicial en Visual Studio 2022 mediante la plantilla de aplicación WPF de .NET Core

Vaya al paso 4: compilación y ejecución del proyecto inicial sin WebView2 a continuación.

Creación de un proyecto de aplicación de WPF (.NET Framework)

Si va a crear un proyecto de aplicación de WPF (.NET Framework), siga estos pasos. De lo contrario, vaya al Paso 4: Compilación y ejecución del proyecto inicial sin WebView2.

  1. Abra Microsoft Visual Studio, como Visual Studio 2022.

  2. En el panel de apertura, haga clic en Create nuevo proyecto. O bien, en la ventana principal de Visual Studio, seleccione Archivo>nuevo>proyecto. Se abre el cuadro de diálogo Create un nuevo proyecto.

  3. En el cuadro de texto Búsqueda para plantillas, escriba WPF App. El Create un nuevo panel de proyecto muestra las plantillas de proyecto instaladas que coinciden con el texto especificado. En este artículo se muestran los diálogos de C# en lugar de VB; Ambos lenguajes son compatibles con WebView2.

  4. Haga clic en una plantilla de proyecto que tenga el título aplicación WPF (.NET Framework) y el texto de descripción Windows Presentation Foundation aplicación cliente:

    Selección de la plantilla

    Si la plantilla de proyecto anterior no aparece en la lista, consulte Paso 1: Instalación de Visual Studio con compatibilidad con .NET anterior para instalar herramientas de desarrollo de escritorio de .NET.

  5. Haga clic en el botón Siguiente .

    Se abre el cuadro de diálogo Configurar el nuevo proyecto: Aplicación WPF (.NET Framework):

    Cuadro de diálogo

  6. En el cuadro de texto Nombre del proyecto, escriba un nombre de proyecto, como MyWpfDotnetFwkWv2App.

  7. En el cuadro de texto Ubicación , seleccione una ruta de acceso en la unidad local, como C:\Users\myusername\Documents\MyProjects.

  8. En la lista desplegable Marco , seleccione .NET Framework 4.6.2 o posterior.

  9. Haga clic en el botón Crear.

    El proyecto inicial de aplicación wpf (.NET Framework) se abre en Visual Studio:

    Proyecto inicial en Visual Studio 2022 mediante la plantilla aplicación wpf (.NET Framework)

Paso 4: Compilación y ejecución del proyecto inicial sin WebView2

  1. SeleccioneGuardar todo en archivo> para guardar el proyecto.

  2. Pulse F5 para compilar y ejecutar el proyecto.

    El proyecto se ejecuta y muestra una ventana vacía:

    Ventana de aplicación vacía sin WebView2

    Es posible que tenga que instalar la versión de .NET Framework seleccionada, como se indica a continuación.

  3. Si la aplicación no se abre, seleccione Depurar>inicio sin depuración.

    Si no ha instalado la versión seleccionada de .NET Framework, puede obtener el siguiente cuadro de diálogo: "No se pudo iniciar esta aplicación. La aplicación requiere una de las siguientes versiones de .NET Framework: . NETFramework,Version=v4.8.1: ¿Desea instalar esta versión de .NET Framework ahora?"

  4. Si obtiene este tipo de cuadro de diálogo, vaya a Descargar .NET Framework y descargue e instale la versión necesaria del paquete para desarrolladores (no el runtime). Por ejemplo, descargue ndp481-devpack-enu.exe en C:\Users\username\Downloadsy haga doble clic en el archivo para instalarlo.

  5. Si se le solicita, reinicie el equipo:

    Reinicio para instalar .NET Framework

  6. Vaya al archivo descargado, como ndp481-devpack-enu.exe en C:\Users\username\Downloadsy, de nuevo, haga doble clic en el archivo descargado para instalar el paquete para desarrolladores de .NET Framework. Aparece un cuadro de diálogo Correcto:

    Instalación correcta para instalar .NET Framework

  7. Si se le solicita, reinicie el equipo de nuevo.

  8. Abra Visual Studio y abra la solución que ha creado.

  9. Presione F5 para ejecutar la aplicación inicial (que se muestra anteriormente), sin incluir aún el SDK de WebView2.

  10. Cierre la aplicación inicial.

Paso 5: Instalación del SDK de WebView2

En Visual Studio, use el Administrador de paquetes 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 (en función de la plantilla de proyecto .NET (Core) o .NET Framework) y, a continuación, seleccione Administrar paquetes NuGet:

    El comando

  2. En la parte superior izquierda, haga clic en la pestaña Examinar . En la barra de búsqueda, escriba Microsoft.Web.WebView2y haga clic en el paquete Microsoft.Web.WebView2 .

    El cuadro de diálogo Administrador de paquetes NuGet muestra los resultados de la búsqueda, incluido un paquete Microsoft.Web.WebView2 . El cuadro de diálogo tiene un número de versión y el botón Instalar .

    El cuadro de diálogo administrador de paquetes NuGet muestra el paquete Microsoft.Web.WebView2

  3. Acepte la versión predeterminada y, a continuación, haga clic en el botón Instalar .

  4. En el cuadro de diálogo Vista previa de cambios , haga clic en el botón Aceptar .

  5. SeleccioneGuardar todo en archivo> para guardar el proyecto.

  6. Pulse F5 para compilar y ejecutar el proyecto.

    El proyecto se ejecuta y muestra una ventana vacía. Esto comprueba que WebView2 está instalado y funcionando, aunque WebView2 no tiene contenido que mostrar todavía:

    Ventana de aplicación vacía con el SDK de WebView2

  7. Cierre la aplicación.

Paso 6: Create un único control WebView2

Agregue un control WebView2 a la aplicación.

  1. En el MainWindow.xaml archivo , para agregar el espacio de nombres XAML WebView2, inserte la siguiente línea dentro de la <Window/> etiqueta :

    xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"

  2. Asegúrese de que el código de MainWindow.xaml tenga un aspecto similar al siguiente:

    <Window x:Class="WPF_Getting_Started.MainWindow"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:local="clr-namespace:{YOUR PROJECT NAME}"
      xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"
      mc:Ignorable="d"
      Title="MainWindow"
      Height="450"
      Width="800"
>
   <Grid>

   </Grid>
</Window>

  3. Para agregar el control WebView2, reemplace las <Grid> etiquetas por el código siguiente. La Source propiedad establece el URI inicial que se muestra en el control WebView2.

    <DockPanel>
   <wv2:WebView2 Name="webView"
                  Source="https://www.microsoft.com"
   />
</DockPanel>

  4. SeleccioneGuardar todo en archivo> para guardar el proyecto.

  5. Pulse F5 para compilar y ejecutar el proyecto.

  6. Asegúrese de que el control WebView2 muestra https://www.microsoft.com:

    Control WebView2, que muestra el contenido de la página web de microsoft.com

Paso 7: Navegación

Permitir que los usuarios cambien la dirección URL que muestra el control WebView2 agregando una barra de direcciones a la aplicación.

  1. En el MainWindow.xaml archivo, agregue una barra de direcciones copiando y pegando el código siguiente dentro del <DockPanel> que contiene el control WebView2. Mantenga el código existente debajo del nuevo fragmento de código.

    <DockPanel DockPanel.Dock="Top">
    <Button x:Name="ButtonGo"
              DockPanel.Dock="Right"
              Click="ButtonGo_Click"
              Content="Go"
    />
    <TextBox Name="addressBar"/>
</DockPanel>

  2. Asegúrese de que la <DockPanel> sección del MainWindow.xaml archivo coincide con el código siguiente:

    <DockPanel>
    <DockPanel DockPanel.Dock="Top">
        <Button x:Name="ButtonGo" DockPanel.Dock="Right" Click="ButtonGo_Click" Content="Go"/>
        <TextBox Name = "addressBar"/>
    </DockPanel>
    <wv2:WebView2 Name = "webView"
                  Source = "https://www.microsoft.com"
    />
</DockPanel>

  3. En MainWindow.xaml.cs, para agregar el CoreWebView2 espacio de nombres, inserte el código siguiente en la parte superior del archivo:

    using Microsoft.Web.WebView2.Core;

  4. En el MainWindow.xaml.csarchivo, copie el código siguiente para crear el ButtonGo_Click método . Este código navega por el control WebView2 hasta la dirección URL especificada en la barra de direcciones.

    private void ButtonGo_Click(object sender, RoutedEventArgs e)
{
    if (webView != null && webView.CoreWebView2 != null)
    {
        webView.CoreWebView2.Navigate(addressBar.Text);
    }
}

  5. Pegue el código directamente después de la Public MainWIndow declaración, como se muestra en el código siguiente:

    namespace WpfApp1
{
   /// <summary>
   /// Interaction logic for MainWindow.xaml
   /// </summary>
   public partial class MainWindow : Window
   {
      public MainWindow()
      {
            InitializeComponent();
      }
      void ButtonGo_Click(object sender, RoutedEventArgs e)
      {
            if (webView != null && webView.CoreWebView2 != null)
            {
               webView.CoreWebView2.Navigate(addressBar.Text);
            }
      }
   }
}

  6. SeleccioneGuardar todo en archivo> para guardar el proyecto.

  7. Pulse F5 para compilar y ejecutar el proyecto.

  8. Escriba una nueva dirección URL en la barra de direcciones y elija Ir. Por ejemplo, escriba https://www.bing.com.

  9. Asegúrese de que el control WebView2 abre la dirección URL especificada.

    Asegúrese de escribir una dirección URL completa en la barra de direcciones. La aplicación genera un ArgumentException si la dirección URL no comienza con http:// o https://.

    La aplicación de ejemplo muestra el sitio web de Bing con la dirección URL https://www.bing.com en la barra de direcciones:

    La aplicación muestra el sitio web de Bing

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

Eventos de navegación, desde el nuevo documento hasta el inicio de la navegación, a través de la navegación completada

En el diagrama anterior se muestra la secuencia de eventos. Los eventos de navegación comienzan con un nuevo documento.

Ruta de acceso correcta

Una ruta de acceso correcta incluye la secuencia completa de eventos:

  1. Inicio de la navegación.
  2. Origen cambiado, con posible entrada del mismo documento.
  3. Carga de contenido.
  4. Cambios en el historial.
  5. Navegación completada.

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

Ruta de acceso de error

Si se produce un error, la ruta de acceso de error pasa directamente desde el inicio de la navegación hasta la navegación completada, omitiendo los eventos intermedios.

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

Redireccionamiento

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

Ejemplo que muestra eventos de navegación

Para mostrar cómo usar los eventos, registre un controlador para NavigationStarting que cancele las solicitudes que no sean HTTPS, como se indica a continuación.

  1. En el MainWindow.xaml.cs archivo, modifique el constructor para que coincida con la parte superior del código siguiente. Debajo del constructor, agregue la EnsureHttps función :

    public MainWindow()
{
    InitializeComponent();
    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> para guardar el proyecto.

  3. Pulse F5 para compilar y ejecutar el proyecto.

  4. Intente abrir un sitio HTTP. Asegúrese de que el control WebView2 permanece sin cambios.

  5. Intente abrir un sitio HTTPS. El control WebView2 permite abrir sitios HTTPS.

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:

  • Ejecútelo después de la creación del objeto global.
  • Ejecútelo antes de que se ejecute cualquier otro script incluido en el documento HTML.

Por ejemplo, agregue scripts que envíen una alerta cuando un usuario navegue a sitios que no sean HTTPS, como se indica a continuación:

  1. Modifique la EnsureHttps función para insertar un script en el contenido web que usa el método 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;
   }
}

  2. SeleccioneGuardar todo en archivo> para guardar el proyecto.

  3. Pulse F5 para compilar y ejecutar el proyecto.

  4. Asegúrese de que la aplicación muestra una alerta al navegar a un sitio web que no usa HTTPS.

    Mensaje que muestra que una dirección URL http: no es segura y recomienda probar una dirección URL https: en su lugar

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

El host y el contenido web se pueden comunicar de las siguientes maneras mediante postMessage:

  • El contenido web de un control WebView2 puede publicar un mensaje en el host mediante window.chrome.webview.postMessage. 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. 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 MainWindow.xaml.cs, actualice el constructor y cree una InitializeAsync función para que coincida con el código siguiente. La InitializeAsync función espera a EnsureCoreWebView2Async, porque la inicialización de CoreWebView2 es asincrónica.

    public MainWindow()
{
   InitializeComponent();
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
}

  2. Después de inicializar CoreWebView2 , registre un controlador de eventos para responder a WebMessageReceived. En MainWindow.xaml.cs, actualice InitializeAsync y agregue UpdateAddressBar mediante el código siguiente:

    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);
}

  3. Para que el control WebView2 envíe y responda al mensaje web, después CoreWebView2 de inicializarse, el host hace lo siguiente:

    1. Inserta un script en el contenido web que registra un controlador para imprimir el mensaje desde el host.
    2. Inserta un script en el contenido web que publica la dirección URL en el host.

  4. En MainWindow.xaml.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));");
}

  5. SeleccioneGuardar todo en archivo> para guardar el proyecto.

  6. Pulse F5 para compilar y ejecutar el proyecto.

  7. Al abrir un nuevo URI, el control WebView2 muestra el URI en la barra de direcciones.

    La aplicación de ejemplo muestra el URI en la barra de direcciones y en el sitio web de Microsoft: https://www.microsoft.com

    La aplicación de ejemplo muestra el URI en la barra de direcciones y en el sitio web de Microsoft

Enhorabuena, ha creado su primera aplicación WebView2.

Consulte también

developer.microsoft.com:

Páginas locales:

Github: