Introducción a WebView2 en aplicaciones winUI 3 (SDK de Aplicaciones para Windows)

Artículo
04/13/2024

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

En este tutorial, usará la plantilla de proyecto de Visual Studio Aplicación en blanco, empaquetada (WinUI en el escritorio) para crear un proyecto winUI 3 en blanco. Esa plantilla de proyecto usa WindowsAppSDK, que incluye el SDK de WebView2. Agregue un control WebView2. A continuación, agregue una barra de direcciones y una lógica para mostrar un cuadro de diálogo de advertencia cuando el usuario intente navegar a una dirección URL con un http:// prefijo.

Aplicación que muestra el sitio web de Bing

Proyecto completado

Hay disponible una versión completa de este proyecto de tutorial (a partir de 2020) en el repositorio WebView2Samples :

Nombre de ejemplo: WinUI3_GettingStarted
Directorio del repositorio: WinUI3_GettingStarted
Archivo de solución: WinUI_Sample.sln

El tutorial actual se actualiza y solo crea un proyecto único, no un segundo, "(Package)" como en 2020.

Paso 1: Instalar Visual Studio y el SDK de Aplicaciones para Windows

Incluso si tiene instalado Visual Studio, lea la página siguiente y, posiblemente, actualice el software e instale las plantillas de proyecto.

En una nueva ventana o pestaña, abra la página Instalar herramientas para el SDK de Aplicaciones para Windows y, a continuación, siga los pasos de esa página para instalar Microsoft Visual Studio, como Visual Studio 2022.

Si es necesario, en una nueva ventana o pestaña, vea Instalar Visual Studio en Configurar el entorno de desarrollo para WebView2.

Vuelva desde esa página y continúe con los pasos que se indican a continuación.

En este ejemplo, no es necesario instalar por separado el SDK de WebView2. A continuación, seleccionará la plantilla de proyecto Aplicación en blanco, empaquetada (WinUI en el escritorio), que usa WindowsAppSDK, que incluye el SDK de WebView2.

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

Instale el entorno de ejecución de WebView2 en dispositivos que tengan Windows 10 versión 1803 (compilación 17134) o posterior, mediante la instalación desde cualquiera de las ubicaciones:

Para descargar directamente solo el entorno de ejecución, use la sección Descargar el entorno de ejecución de WebView2 de la página WebView2 de Microsoft Edge en developer.microsoft.com.
Para descargar e instalar un canal de versión preliminar de Microsoft Edge (Beta, Desarrollo o Canary), vaya a Convertirse en microsoft edge insider. Los canales de vista previa también se denominan canales Insider. Los canales de vista previa incluyen el entorno de ejecución WebView2.

A continuación, continúe con los pasos que se indican a continuación.

Paso 3: Create un proyecto de WinUI 3 en blanco

Para crear una aplicación WebView2, empiece por crear un proyecto de escritorio básico para crear una aplicación de escritorio que contenga una sola ventana principal:

Si Visual Studio no se está ejecutando, inicie Visual Studio (no Visual Studio Code). En la ventana de inicio de Visual Studio, haga clic en el Create una nueva tarjeta de proyecto. Se abre el Create una nueva ventana del proyecto.

O bien, si Visual Studio se está ejecutando, seleccione Archivo>nuevo>proyecto. Se abre el cuadro de diálogo Create un nuevo proyecto.

Activar el modo de desarrollador: Cuando Visual Studio se abre en algún momento durante los pasos del artículo actual, es posible que se le pida que active el Modo de desarrollador para el equipo. Para obtener más información, si es necesario, consulte Habilitación del dispositivo para el desarrollo en Compilación de aplicaciones de escritorio para Windows.
En el cuadro de diálogo Create un nuevo proyecto, en el campo Búsqueda para plantillas, escriba WinUI 3 en Escritorio:
Haga clic en la tarjeta Aplicación en blanco, Empaquetada (WinUI en escritorio) para seleccionarla y, a continuación, haga clic en el botón Siguiente .

Si las plantillas de WinUI no aparecen en la lista, debe instalar las plantillas de proyecto como se mencionó anteriormente, desde Instalar herramientas para el SDK de Aplicaciones para Windows. Sugerencias adicionales para que aparezca la plantilla:

Después de instalar las opciones "predeterminadas" para Visual Studio 2022 Community Edition, en Instalador de Visual Studio, haga clic en la tarjeta .NET y, a continuación, a la derecha, active la casilla SDK de Aplicaciones para Windows Plantillas de C#.

Si la plantilla de proyecto correcta sigue sin aparecer: en el Instalador de Visual Studio, haga clic en la tarjeta de UWP para seleccionarla, active la casilla herramientas de C++ v143 de la derecha y, a continuación, haga clic en el botón Modificar.

Aparece el cuadro de diálogo Configurar el nuevo proyecto .
En el cuadro de texto Nombre del proyecto, escriba un nombre de proyecto, como MyWebView2WinUI3:
En el cuadro de texto Ubicación , escriba o vaya a una ubicación, como C:\Users\username\Documents\WebView2.
Haga clic en el botón Crear.

El nuevo proyecto de WinUI 3 se abre en Explorador de soluciones en Visual Studio:
- El App.xaml.cs archivo define una Application clase que representa la instancia de la aplicación.
- El MainWindow.xaml.cs archivo define una MainWindow clase que representa la ventana principal que muestra la instancia de la aplicación. Las clases derivan de tipos del Microsoft.UI.Xaml espacio de nombres de WinUI.
En la lista desplegable Configuraciones de solución (en el centro de la parte superior de la ventana), seleccione Depurar.
En la lista desplegable Plataformas de solución, seleccione una plataforma, como x64.
SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.
Pulse F5 para compilar y ejecutar el proyecto. Se abre la aplicación winUI Desktop en blanco, sin ningún control WebView2 agregado todavía:
Cierre la aplicación.

Actualización de los números de versión de destino

Para el paso de compilación anterior: si va a actualizar un proyecto anterior, es posible que tenga que actualizar los números de versión de Versión de destino y Versión mínima. Para ello, en Solución, haga clic con el botón derecho en el proyecto y, a continuación, seleccione Editar archivo de proyecto. Se .csproj abre el archivo. Asegúrese de que los valores se actualizan de la siguiente manera y, a continuación, guarde los cambios y compile el proyecto.

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

Los valores anteriores representan:

Versión de destino: Windows 10, versión 2004 (compilación 19041) o posterior.
Versión mínima: Windows 10, versión 1809 (compilación 17763).

Paso 4: Agregar un control WebView2

Este proyecto de tutorial se basa en la plantilla de proyecto Aplicación en blanco, empaquetada (WinUI en escritorio). Esta plantilla de proyecto usa WindowsAppSDK, que incluye el SDK de WebView2.

Edite los MainWindow.xaml archivos y MainWindow.xaml.cs para agregar un control WebView2 al proyecto de aplicación winUI 3 en blanco, como se indica a continuación:

En Visual Studio, en Explorador de soluciones, haga doble clic MainWindow.xaml para abrirlo en el editor de código.

Agregue el espacio de nombres XAML WebView2 insertando el siguiente atributo dentro de la <Window> etiqueta de inicio:

xmlns:controls="using:Microsoft.UI.Xaml.Controls"

Asegúrese de que el código de MainWindow.xaml es similar al siguiente:

<Window
    x:Class="MyWebView2WinUI3.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MyWebView2WinUI3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
        <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
    </StackPanel>
</Window>

Para agregar el control WebView2, reemplace todo <StackPanel> el elemento por el código siguiente <Grid> . La Source propiedad, cerca de la parte inferior, establece el URI inicial que se muestra en el control WebView2 (https://www.microsoft.com):

<Grid>

    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
        Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

En Explorador de soluciones, expanda MainWindow.xaml y abra MainWindow.xaml.cs.
En MainWindow.xaml.cs, comente la línea siguiente, como se muestra:
```
    // myButton.Content = "Clicked";
```
SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.
Presione F5 para compilar y ejecutar el proyecto.
La aplicación es una aplicación host WebView2 que incluye el control WebView2. El control WebView2 muestra el sitio web https://www.microsoft.com:
Cierre la aplicación.

WinAppSDK admite entornos WebView2 personalizados

WinAppSDK admite entornos WebView2 personalizados, a partir de WinAppSDK 1.5 (1.5.0-experimental2). Para obtener más información, vea WinUI3 WebView2 con un CoreWebView2Environment personalizado.

Para crear una instancia de un entorno WebView2 personalizado, inicialice WebView2 con una de las invalidaciones de WebView2.EnsureCoreWebView2Async (que se enumeran a continuación) y pase su personalizado CoreWebView2Environment (y, opcionalmente, personalizado CoreWebView2ControllerOptions):

public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment)
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions)

Vea también el código de ejemplo en Deshabilitación de la navegación smartscreen, a continuación.

Referencia de API:

Para permitir que los usuarios controlen qué página web se muestra en el control WebView2, agregue una barra de direcciones a la aplicación, como se indica a continuación:

En MainWindow.xaml, pegue el código siguiente dentro del <Grid> elemento que contiene el <controls:WebView2> elemento :

   <TextBox Name="addressBar" Grid.Column="0"/>
   <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

Asegúrese de que el elemento resultante <Grid> del MainWindow.xaml archivo coincide con lo siguiente:

<Grid>

    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <TextBox Name="addressBar" Grid.Column="0"/>
    <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
    Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

En MainWindow.xaml.cs, pegue el código siguiente en myButton_Click, sobrescribiendo el método existente myButton_Click (que está casi vacío). Este código navega por el control WebView2 hasta la dirección URL especificada en la barra de direcciones.

private void myButton_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri targetUri = new Uri(addressBar.Text);
        MyWebView.Source = targetUri;
    }
    catch (FormatException ex)
    {
        // Incorrect address entered.
    }
}

SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.
Pulse F5 para compilar y ejecutar el proyecto.
Escriba una nueva dirección URL completa en la barra de direcciones, como https://www.bing.com, y, a continuación, haga clic en el botón Ir .

El control WebView2 de la aplicación muestra el sitio web de Bing. La barra de direcciones muestra la dirección URL, como https://www.bing.com:
Escriba una dirección URL incompleta en la barra de direcciones, como bing.com, y, a continuación, haga clic en el botón Ir .

Se produce una ArgumentException excepción y aparece después de cerrar la aplicación, porque la dirección URL no comienza con http:// o https://.
Cierre la aplicación.

En esta sección, agregará código para importar la biblioteca WebView2 Core.

En MainWindow.xaml.cs, agregue la siguiente línea en la parte superior, encima de las demás using instrucciones:
```
using Microsoft.Web.WebView2.Core;
```
Las aplicaciones que hospedan controles WebView2 escuchan los siguientes eventos generados por los controles WebView2 durante la navegación por la página web:
- NavigationStarting
- SourceChanged
- ContentLoading
- HistoryChanged
- NavigationCompleted
Si se produce una redirección HTTP, hay varios NavigationStarting eventos en una fila.

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

Cuando se producen errores, se generan los siguientes eventos y se puede mostrar una página web de error:
- SourceChanged
- ContentLoading
- HistoryChanged
Como ejemplo de cómo usar los eventos, registre un controlador para NavigationStarting que cancele las solicitudes que no sean HTTPS, como se indica a continuación:
En MainWindow.xaml.cs, en el constructor, agregue la línea siguiente NavigationStarting para registrar el EnsureHttps método :
```
public MainWindow()
{
    this.InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}
```

En MainWindow.xaml.cs, debajo del constructor, agregue el siguiente EnsureHttps método:

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

SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.
Pulse F5 para compilar y ejecutar el proyecto.
En la aplicación, en la barra Dirección, escriba una dirección URL HTTP, como http://bing.com, y, a continuación, haga clic en el botón Ir .

No ocurre nada, porque la navegación está bloqueada en sitios HTTP y aún no hemos agregado un cuadro de diálogo para proporcionar comentarios.
Escriba una dirección URL HTTPS, como https://bing.com, y, a continuación, haga clic en el botón Ir .

La aplicación navega a la página especificada, ya que se permite la navegación para los sitios HTTPS.
Cierre la aplicación.

Paso 7: 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 tiempo específico para:

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

Por ejemplo, a continuación, agrega scripts que envían una alerta cuando un usuario intenta abrir sitios que no son HTTPS. Para ello, inserta un script en el contenido web que usa ExecuteScriptAsync.

En el EnsureHttps método , agregue la línea siguiente ExecuteScriptAsync :

private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S) para guardar el proyecto.
Pulse F5 para compilar y ejecutar el proyecto.
En la barra de direcciones de la aplicación, escriba una dirección URL que no sea HTTPS, como http://www.bing.comy, a continuación, haga clic en el botón Ir .

El control WebView2 de la aplicación muestra un cuadro de diálogo de alerta para sitios web que no son HTTPS, que indica que no uri es seguro:
Cierre la aplicación.

Enhorabuena, ha creado su primera aplicación WebView2.

Consideraciones especiales de WinUI 3 WebView2

WebView2 envía las direcciones URL a las que se navega en la aplicación al servicio SmartScreen para asegurarse de que los clientes permanecen seguros. Si desea deshabilitar esta navegación, use un elemento personalizado CoreWebView2Environment, como se indica a continuación:

CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions();
environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection";

string browserFolder = null; // Use null to get default browser folder
string userDataFolder = null; // Use null to get default user data folder
CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync(
    browserFolder, userDataFolder, environmentOptions);

// ...

this.WebView2.EnsureCoreWebView2Async(environment);

Deshabilitación de SmartScreen mediante una variable de entorno

Ya no se recomienda usar una variable de entorno. En su lugar, use el enfoque basado en código de API anterior.

Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");

Esta variable de entorno debe establecerse antes de CoreWebView2 la creación, que se produce cuando se establece inicialmente la propiedad WebView2.Source o se llama inicialmente al método WebView2.EnsureCoreWebView2Async .

Establecer DefaultBackgroundColor

En WebView2 para WinUI 3, la DefaultBackgroundColor configuración existe en el objeto XAML WebView2. Por ejemplo:

public MainWindow()
{
    this.InitializeComponent();
    MyWebView.DefaultBackgroundColor = Colors.LightBlue;
}

Transparencia

WinUI 3 no admite fondos transparentes. Consulte Compatibilidad en segundo plano transparente con WebView2? · Problema n.º 2992.

Compatibilidad con WinAppSDK para entornos WebView2 personalizados

Consulte WinAppSDK admite entornos WebView2 personalizados, anteriormente.

Consulte también

Referencia de api de WebView2
Introducción a Microsoft Edge WebView2: introducción a las características.
Administrar carpetas de datos de usuario
Código de ejemplo para WebView2 : una guía para el WebView2Samples repositorio.
Procedimientos recomendados de desarrollo para aplicaciones WebView2Administración recomendada de desarrollo

developer.microsoft.com:

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

Github:

Introducción con WebView2 en WinUI3
Especificación: control Xaml WebView2 : la versión WinUI 3.0 del control WebView2.
repositorio > microsoft-ui-xaml Problemas : para especificar errores o solicitudes de características específicas de WinUI.