Aplicación de ejemplo WinUI 3 (SDK de Aplicaciones para Windows)

Artículo
11/07/2024

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

En este ejemplo se muestra cómo usar un control WebView2 en una aplicación empaquetada winUI 3 (SDK de Aplicaciones para Windows).

Aplicación de ejemplo

Este ejemplo también permite enviar la aplicación con un entorno de ejecución WebView2 de versión fija, en lugar de usar cualquier versión del runtime de WebView2 instalada y en ejecución en el equipo del usuario.

Paquetes NuGet y componentes de carga de trabajo

Antes de compilar, haremos lo siguiente:

Actualice el paquete NuGet Microsoft.Windows.SDK.BuildTools para el proyecto y para el proyecto (paquete).
Actualice el paquete NuGet Microsoft.WindowsAppSDK para el proyecto y para el proyecto (paquete).
Instale el componente "WINDOWS 10 SDK" de la carga de trabajo "Desarrollo de aplicaciones de Windows", si aún no está instalado.

Directorios

Directorio	Contenido
WebView2_WinUI3_Sample	Código del proyecto
WebView2_WinUI3_Sample (paquete)	Proyecto de empaquetado y distribución
WebView2_WinUI3_Sample (paquete)\FixedRuntime	(Opcional) Tiempo de ejecución de WebView2 corregido
WebView2_WinUI3_Sample (paquete)\FixedRuntime\130.0.2849.39	(Opcional) Ejemplo de tiempo de ejecución de WebView2 corregido

Paso 1: Instalar la versión más reciente de Visual Studio 2022

Asegúrese de que Visual Studio 2022 está instalado y actualizado.

Para instalar la versión más reciente de Visual Studio 2022:

Vaya a Visual Studio: IDE y Code Editor para desarrolladores de software y Teams y, a continuación, en la sección Visual Studio 2022, haga clic en el botón Descargar y, a continuación, seleccione Community 2022 u otra versión.
En el menú emergente Descargas de la esquina superior derecha de Microsoft Edge, VisualStudioSetup.exe aparece. Haga clic en Abrir archivo.

Instalador de Visual Studio se abre.
Siga las indicaciones y acepte los valores predeterminados.

Paso 2: Clonar o descargar el repositorio WebView2Samples

Si aún no lo ha hecho, clone o descargue el repositorio en la WebView2Samples unidad local. En una ventana o pestaña independiente, consulte Descarga del repositorio WebView2Samples en Configuración del entorno de desarrollo para WebView2. Siga los pasos de esa sección y vuelva a esta página y continúe a continuación.

Paso 3: Abrir la solución en Visual Studio

Estos pasos iniciales sobre el repositorio y la rama no son necesarios, pero son una buena práctica para evitar cambiar el código que se encuentra en la rama "principal" de la copia clonada del repositorio WebView2Samples. Esto le permite modificar los archivos del proyecto (para compilar y ejecutar el ejemplo), a la vez que mantiene el código que está en la rama "principal" idéntico al repositorio.

Puede realizar estos pasos en cualquier herramienta para operaciones de Git, como:

Escritorio de GitHub.
La pestaña Cambios de Git junto a la pestaña Explorador de soluciones, en la esquina inferior derecha de Visual Studio.
Símbolo del sistema de Git Bash.

Para abrir el archivo de solución del ejemplo en una rama de trabajo:

En GitHub Desktop, en la lista Repositorio actual de la esquina superior izquierda, seleccione el repositorio WebView2Samples .
Haga clic en Capturar origen en la parte superior central de la ventana.
En el menú Rama actual , cree una rama de trabajo como user/myGithubUsername/winui3-sample y cambie a ella.

Ahora se encuentra de forma segura en una rama de trabajo en lugar de en la rama "principal" y puede empezar a modificar los archivos del ejemplo.
En la unidad local, abra el .sln archivo en Visual Studio.

Ubicaciones de ejemplo del .sln archivo: si ha clonado el repositorio, el nombre del directorio del repositorio es /WebView2Samples/:

<your-repos-directory>/WebView2Samples/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln

Si descargó el repositorio, el nombre del directorio del repositorio es /WebView2Samples-main/, que representa la rama "principal":

<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln

Paso 4: Actualización de los paquetes NuGet

En Explorador de soluciones, haga clic con el botón derecho en el proyecto de WebView2_WinUI3_Sample y, a continuación, seleccione Administrar paquetes NuGet.

En Visual Studio, se abre el Administrador de paquetes NuGet :

La pestaña Instalado está seleccionada y enumera los paquetes NuGet:
- Microsoft.Windows.SDK.BuildTools
- Microsoft.WindowsAppSDK
- Microsoft.Web.WebView2
Seleccione la pestaña Novedades.
En la parte superior izquierda, active la casilla Seleccionar todos los paquetes .
A la derecha de esa casilla, haga clic en el botón Actualizar .

Se abre el cuadro de diálogo Vista previa de cambios .
Haga clic en el botón Aplicar .

Se abre el cuadro de diálogo Aceptación de licencia .
Haga clic en el botón Acepto .

Los paquetes NuGet se actualizan y se quita el número situado junto a la pestaña Novedades.

Haga clic en el menú Ver y, a continuación, haga clic en el elemento de menú Salida .

En la pestaña Salida , en la lista desplegable Mostrar salida de , se selecciona Administrador de paquetes. La salida incluye líneas como:

Installing NuGet package Microsoft.Windows.SDK.BuildTools
Installing NuGet package Microsoft.WindowsAppSDK

Successfully uninstalled 'Microsoft.Windows.SDK.BuildTools
Successfully uninstalled 'Microsoft.WindowsAppSDK

Successfully installed 'Microsoft.Web.WebView2
Successfully installed 'Microsoft.Windows.SDK.BuildTools
Successfully installed 'Microsoft.WindowsAppSDK

Actualización de paquetes NuGet en el proyecto (paquete)

En Explorador de soluciones, haga clic con el botón derecho en el proyecto de WebView2_WinUI3_Sample (paquete) y, a continuación, seleccione Administrar paquetes NuGet.
Seleccione la pestaña Novedades.
En la parte superior izquierda, active la casilla Seleccionar todos los paquetes .
A la derecha de esa casilla, haga clic en el botón Actualizar .

Se abre el cuadro de diálogo Vista previa de cambios .
Haga clic en el botón Aplicar .

Se abre el cuadro de diálogo Aceptación de licencia .
Haga clic en el botón Acepto .

Los paquetes NuGet se actualizan y se quita el número situado junto a la pestaña Novedades.
Haga clic en el menú Ver y, a continuación, haga clic en el elemento de menú Salida .

En la pestaña Salida , en la lista desplegable Mostrar salida de , se selecciona Administrador de paquetes. La salida incluye líneas como se muestra anteriormente.
Cierre la ventana Administrador de paquetes NuGet .

Paso 5: Instalación del SDK de Windows 10 u otros componentes de carga de trabajo

En función de lo que haya instalado, es posible que tenga que instalar una carga de trabajo de Visual Studio o un componente de una carga de trabajo, como la siguiente, para compilar el ejemplo.

Para instalar el componente Windows 10 SDK de la carga de trabajo desarrollo de aplicaciones de Windows:

En Visual Studio, haga clic en el menú Herramientas y, a continuación, haga clic en el elemento de menú Obtener herramientas y características .

Se abre la ventana Instalador de Visual Studio.
Seleccione la tarjeta de desarrollo de aplicaciones de Windows para que aparezca una marca de verificación.
En el árbol Detalles de instalación de la derecha, active la casilla del componente Windows 10 SDK 10.0.19041.0.
Haga clic en el botón Modificar .

Se abre el cuadro de diálogo Control de cuentas de usuario .
Haga clic en el botón Sí .

Se abre el cuadro de diálogo Antes de empezar (del Instalador de Visual Studio), que le pide que guarde el trabajo en Visual Studio.
Cierre la ventana principal de Visual Studio y guarde si es necesario.
En el cuadro de diálogo Antes de empezar , haga clic en el botón Reintentar .

Después de unos minutos, el componente de carga de trabajo Windows 10 SDK 10.0.19041.0 se descarga e instala. Instalador de Visual Studio dice "Todas las instalaciones están actualizadas".

Paso 6: Compilación y ejecución de la aplicación

Abra la solución en Visual Studio 2022. Por ejemplo, en Instalador de Visual Studio, en la sección Visual Studio 2022, haga clic en el botón Iniciar.

Se abre el iniciador de Visual Studio, con las secciones Abrir reciente y Introducción.
En la sección Abrir reciente , seleccione WebView2_WinUI3_Sample.sln.

La solución se abre en Visual Studio 2022.
Pulse F5.

En Explorador de soluciones, el proyecto (Paquete) está en negrita, lo que indica que es el proyecto predeterminado. La aplicación se compila y, a continuación, se abre la ventana de la aplicación WebView2_WinUI3_Sample (paquete ):

El mensaje "Navegación completa" se muestra en la parte inferior.
En la barra de direcciones (un cuadro de texto), escriba https://bing.com (una dirección URL HTTPS completa) y, a continuación, presione Entrar (equivalente a hacer clic en el botón Ir ).

El control WebView2 navega a Bing y, a continuación, muestra "Navegación completa" en la parte inferior.

En Visual Studio, la ventana Salida muestra mensajes como:
```
AddressBar_KeyDown [Enter]: https://bing.com
TryNavigate
TryCreateUri
Navigation complete
```

Paso 7: Confirmar cambios en la rama de trabajo

En una herramienta de Git como GitHub Desktop, en este momento, puede confirmar los cambios y, opcionalmente, insertarlos en una bifurcación de la rama en GitHub. Estos tipos de operaciones son pertinentes al modificar, experimentar y personalizar el ejemplo. Esto también mantiene la rama de trabajo limpia y mantiene el clon del repositorio organizado, para que pueda cambiar a un ejemplo diferente.

Para confirmar e insertar los cambios realizados en el ejemplo de la rama de trabajo:

En Visual Studio, seleccioneGuardar todo el archivo> (Ctrl+Mayús+S).
En GitHub Desktop, escriba un breve mensaje de confirmación, como "ejemplo actualizado, compilado y ejecutado" y, a continuación, haga clic en el botón Confirmar .
Seleccione Inserción de repositorio>. La rama de trabajo se copia de la unidad local a la rama bifurcada del repositorio WebView2Samples en GitHub.

Visualización de la rama de trabajo en GitHub
En Microsoft Edge, vaya a la bifurcación del repositorio, como https://github.com/myGithubUsername/WebView2Samples/.
Haga clic en el vínculo [#] Ramas y, a continuación, seleccione la nueva rama de trabajo, como user/myGithubUsername/winui3-sample.

Paso 8: Inspeccionar el código

Cierre la aplicación WebView2_WinUI3_Sample (paquete).
En Explorador de soluciones, en el proyecto WebView2_WinUI3_Sample, haga doble clic en cada .xaml archivo y su .cs archivo:
- App.xaml - No hay código WebView2.
  - App.cs - Código para usar un entorno de ejecución WebView2 de versión fija.
- MainWindow.xaml - Elementos WebView2.
  - MainWindow.cs - Código WebView2.

A continuación se muestran las versiones condensadas de estos archivos.

App.xaml

No hay ningún código específico de WebView2 en este archivo.

Lista condensada

<Application
    x:Class="WebView2_WinUI3_Sample.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:WebView2_WinUI3_Sample">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

App.cs

El código específico de WebView2 de este archivo se comenta. Puede anular el comentario de estas líneas para usar un runtime de versión fija; consulte Uso de un entorno de ejecución WebView2 de versión fija, a continuación.

Lista condensada

namespace WebView2_WinUI3_Sample
{
    /// <summary>
    /// Provides application-specific behavior to supplement the default Application class.
    /// </summary>
    public partial class App : Application
    {
        /// <summary>
        /// Initializes the singleton application object.  Equivalent to main() or WinMain().
        /// </summary>
        public App()
        {
            this.InitializeComponent();

            // If you're shipping a fixed-version WebView2 Runtime with your app, un-comment the
            // following lines of code, and change the version number to the version number of the
            // WebView2 Runtime that you're packaging and shipping to users:

            // StorageFolder localFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;
            // String fixedPath = Path.Combine(localFolder.Path, "FixedRuntime\\130.0.2849.39");
            // Debug.WriteLine($"Launch path [{localFolder.Path}]");
            // Debug.WriteLine($"FixedRuntime path [{fixedPath}]");
            // Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", fixedPath);
        }

        /// <summary>
        /// Invoked when the application is launched normally by the end user.
        /// </summary>
        /// <param name="args">Details about the launch request and process.</param>
        protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
        {
            m_window = new MainWindow();
            m_window.Activate();
        }

        private Window m_window;
    }
}

MainWindow.xaml

La ventana principal tiene los siguientes elementos XAML como controles:

<TextBox> - La barra de direcciones.
<Button> - Botón Ir .
<WebView2> - Control WebView2.
<TextBlock> - La barra de estado.

Lista condensada

<Window
    xmlns:local="using:WebView2_WinUI3_Sample">
    <Grid>
        <Grid.RowDefinitions>
        </Grid.RowDefinitions>
        <Grid Grid.Row="0" Background="LightGray">
            <TextBox Grid.Column="0"  x:Name="AddressBar" KeyDown="AddressBar_KeyDown" VerticalAlignment="Center" Margin="10,0,0,0"/>
            <Button Grid.Column="1" x:Name="Go" Content="Go" Click="Go_OnClick" VerticalAlignment="Center" HorizontalAlignment="Center"/>
        </Grid>

        <WebView2 x:Name="WebView2" Grid.Row="1"/>

        <Rectangle Grid.Row="2" Fill="LightGray"/>
        <TextBlock x:Name="StatusBar" Text="WebView2" VerticalAlignment="Center" Grid.Row="2" Margin="10,0,10,0"/>
    </Grid>
</Window>

MainWindow.cs

La clase MainWindow tiene los métodos siguientes:

Constructor
StatusUpdate
WebView2_CoreWebView2Initialized
WebView2_NavigationCompleted
TryCreateUri
TryNavigate
Go_OnClick
AddressBar_KeyDown
SetTitle
GetWebView2Version

A continuación se muestran extractos o versiones condensadas de estos métodos.

MainWindow (clase)

using Microsoft.Web.WebView2.Core;

namespace WebView2_WinUI3_Sample
{
    /// <summary>
    /// An empty window that can be used on its own or navigated to within a Frame.
    /// </summary>
    public sealed partial class MainWindow : Window
    {

Constructor

public MainWindow()
{
    this.InitializeComponent();

    Closed += (obj, eventArgs) =>
    {
        if (WebView2 != null)
        {
            // Ensure that WebView2 resources are released when
            // the MainWindow is closed. 
            // WebView2 lifecycle in WinUI3 and the Close() method:
            // https://github.com/microsoft/microsoft-ui-xaml/issues/4752#issuecomment-819687363
            WebView2.Close();
        }
    };

    AddressBar.Text = "https://developer.microsoft.com/en-us/microsoft-edge/webview2/";

    WebView2.NavigationCompleted += WebView2_NavigationCompleted;
    WebView2.CoreWebView2Initialized += WebView2_CoreWebView2Initialized;

    WebView2.Source = new Uri(AddressBar.Text);
    StatusUpdate("Ready");
    SetTitle();
}

StatusUpdate

private void StatusUpdate(string message)
{
    StatusBar.Text = message;
    Debug.WriteLine(message);
}

WebView2_CoreWebView2Initialized

private void WebView2_CoreWebView2Initialized(WebView2 sender, CoreWebView2InitializedEventArgs args)
{
    if (args.Exception != null)
    {
        StatusUpdate($"Error initializing WebView2: {args.Exception.Message}");
    }
    else
    {
        SetTitle(sender);
    }
}

WebView2_NavigationCompleted

private void WebView2_NavigationCompleted(WebView2 sender, CoreWebView2NavigationCompletedEventArgs args)
{
    StatusUpdate("Navigation complete");

    // Update the address bar with the full URL that was navigated to.
    AddressBar.Text = sender.Source.ToString();
}

TryCreateUri

private bool TryCreateUri(String potentialUri, out Uri result)
{
    StatusUpdate("TryCreateUri");

    Uri uri;
    if ((Uri.TryCreate(potentialUri, UriKind.Absolute, out uri) || Uri.TryCreate("http://" + potentialUri, UriKind.Absolute, out uri)) &&
        (uri.Scheme == Uri.UriSchemeHttp || uri.Scheme == Uri.UriSchemeHttps))
    {
        result = uri;
        return true;
    }
    else
    {
        StatusUpdate("Unable to configure URI");
        result = null;
        return false;
    }
}

TryNavigate

private void TryNavigate()
{
    StatusUpdate("TryNavigate");

    Uri destinationUri;
    if (TryCreateUri(AddressBar.Text, out destinationUri))
    {
        WebView2.Source = destinationUri;
    }
    else
    {
        StatusUpdate("URI couldn't be figured out use it as a bing search term");

        String bingString = $"https://www.bing.com/search?q={Uri.EscapeDataString(AddressBar.Text)}";
        if (TryCreateUri(bingString, out destinationUri))
        {
            AddressBar.Text = destinationUri.AbsoluteUri;
            WebView2.Source = destinationUri;
        }
        else
        {
            StatusUpdate("URI couldn't be configured as bing search term, giving up");
        }
    }
}

Go_OnClick

private void Go_OnClick(object sender, RoutedEventArgs e)
{
    StatusUpdate("Go_OnClick: " + AddressBar.Text);

    TryNavigate();
}

AddressBar_KeyDown

private void AddressBar_KeyDown(object sender, KeyRoutedEventArgs e)
{
    if (e.Key == Windows.System.VirtualKey.Enter)
    {
        StatusUpdate("AddressBar_KeyDown [Enter]: " + AddressBar.Text);

        e.Handled = true;
        TryNavigate();
    }
}

SetTitle

private void SetTitle(WebView2 webView2 = null)
{
    var packageDisplayName = Windows.ApplicationModel.Package.Current.DisplayName;
    var webView2Version = (webView2 != null) ? " - " + GetWebView2Version(webView2) : string.Empty;
    Title = $"{packageDisplayName}{webView2Version}";
}

GetWebView2Version

private string GetWebView2Version(WebView2 webView2)
{
    var runtimeVersion = webView2.CoreWebView2.Environment.BrowserVersionString;

    CoreWebView2EnvironmentOptions options = new CoreWebView2EnvironmentOptions();
    var targetVersionMajorAndRest = options.TargetCompatibleBrowserVersion;
    var versionList = targetVersionMajorAndRest.Split('.');
    if (versionList.Length != 4)
    {
        return "Invalid SDK build version";
    }
    var sdkVersion = versionList[2] + "." + versionList[3];

    return $"{runtimeVersion}; {sdkVersion}";
}

Uso de un entorno de ejecución webView2 de versión fija

Si desea enviar una versión fija del entorno de ejecución de WebView2 con la aplicación, deberá incluirla en el proyecto. Consulte Distribución de la aplicación y el entorno de ejecución de WebView2.

En los pasos siguientes se muestra el número 130.0.2849.39de versión en tiempo de ejecución; cambiará este número a la versión que esté empaquetando y enviando.

Para usar un runtime de versión fija:

Incluya el tiempo de ejecución de WebView2 fijo en el proyecto de paquete:
```
\WebView2_WinUI3_Sample\WebView2_WinUI3_Sample (Package)\FixedRuntime\130.0.2849.39\
```
Anteriormente, use la versión que va a enviar, en lugar de 130.0.2849.39.
Actualice el archivo del proyecto wapproj de paquete para la versión que usa (use la versión en lugar de 130.0.2849.39):
```
< Content Include="FixedRuntime\130.0.2849.39\\**\*.*" >
```

En App.xaml.cs, quite la marca de comentario de las cinco líneas de código comentadas debajo del comentario para habilitar la invalidación en tiempo de ejecución:

public App()
{
   this.InitializeComponent();

   // If you're shipping a fixed-version WebView2 Runtime with your app, un-comment the
   // following lines of code, and change the version number to the version number of the
   // WebView2 Runtime that you're packaging and shipping to users:

   // StorageFolder localFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;
   // String fixedPath = Path.Combine(localFolder.Path, "FixedRuntime\\130.0.2849.39");
   // Debug.WriteLine($"Launch path [{localFolder.Path}]");
   // Debug.WriteLine($"FixedRuntime path [{fixedPath}]");
   // Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", fixedPath);
}

En el código anterior, cambie el número de versión de 130.0.2849.39 a la versión que va a enviar.

Compartir vía

Aplicación de ejemplo WinUI 3 (SDK de Aplicaciones para Windows)

Paquetes NuGet y componentes de carga de trabajo

Directorios

Paso 1: Instalar la versión más reciente de Visual Studio 2022

Paso 2: Clonar o descargar el repositorio WebView2Samples

Paso 3: Abrir la solución en Visual Studio

Paso 4: Actualización de los paquetes NuGet

Paso 5: Instalación del SDK de Windows 10 u otros componentes de carga de trabajo

Paso 6: Compilación y ejecución de la aplicación

Paso 7: Confirmar cambios en la rama de trabajo

Paso 8: Inspeccionar el código

App.xaml

Lista condensada

App.cs

Lista condensada

MainWindow.xaml

Lista condensada

MainWindow.cs

MainWindow (clase)

Constructor

StatusUpdate

WebView2_CoreWebView2Initialized

WebView2_NavigationCompleted

TryCreateUri

TryNavigate

Go_OnClick

AddressBar_KeyDown

SetTitle

GetWebView2Version

Uso de un entorno de ejecución webView2 de versión fija

Recursos adicionales

Comentarios

Recursos adicionales