Prise en main de WebView2 dans les applications WinUI 3 (SDK d'application Windows)

  • Article

Cet article explique comment configurer vos outils de développement et créer une application WebView2 initiale pour WinUI 3 (SDK d'application Windows), et en savoir plus sur les concepts webView2 en cours de route.

Dans ce tutoriel, vous allez utiliser le modèle de projet Visual Studio Application vide, empaqueté (WinUI dans le bureau) pour créer un projet WinUI 3 vide. Ce modèle de projet utilise windowsAppSDK, qui inclut le Kit de développement logiciel (SDK) WebView2. Vous ajoutez un contrôle WebView2. Vous ajoutez ensuite une barre d’adresse et une logique pour afficher une boîte de dialogue d’avertissement lorsque l’utilisateur tente d’accéder à une URL avec un http:// préfixe.

Application affichant le site web Bing

Projet terminé

Une version terminée de ce projet de didacticiel (à compter de 2020) est disponible dans le référentiel WebView2Samples :

  • Exemple de nom : WinUI3_GettingStarted
  • Répertoire du référentiel : WinUI3_GettingStarted
  • Fichier de solution : WinUI_Sample.sln

Le présent tutoriel est mis à jour et ne crée qu’un seul projet, et non un deuxième projet, « (Package) », comme en 2020.

Étape 1 : Installer Visual Studio et le SDK d'application Windows

Même si Visual Studio est installé, lisez la page suivante et éventuellement mettez à jour vos logiciels et installez des modèles de projet.

  1. Dans une nouvelle fenêtre ou un nouvel onglet, ouvrez la page Outils d’installation pour le SDK d'application Windows, puis suivez les étapes de cette page pour installer Microsoft Visual Studio, par exemple Visual Studio 2022.
  1. Si nécessaire, dans une nouvelle fenêtre ou un nouvel onglet, consultez Installer Visual Studio dans Configurer votre environnement de développement pour WebView2.

Revenez à partir de cette page et poursuivez les étapes ci-dessous.

Pour cet exemple, vous n’avez pas besoin d’installer séparément le Kit de développement logiciel (SDK) WebView2. Ci-dessous, vous allez sélectionner le modèle de projet Application vide, empaquetée (WinUI dans Desktop) qui utilise windowsAppSDK, qui inclut le Kit de développement logiciel (SDK) WebView2.

Étape 2 : Installer un canal en préversion de Microsoft Edge

  1. Installez le runtime WebView2 sur les appareils qui ont Windows 10 version 1803 (build 17134) ou ultérieure, en installant à partir de l’un ou l’autre emplacement :
  • Pour télécharger directement uniquement le runtime, utilisez la section Télécharger le runtime WebView2 de la page Microsoft Edge WebView2 à l’adresse developer.microsoft.com.
  • Pour télécharger et installer un canal microsoft Edge en préversion (bêta, dev ou canary), accédez à Devenir un Microsoft Edge Insider. Les canaux d’aperçu sont également appelés canaux Insider. Les canaux d’aperçu incluent le runtime WebView2.

Passez ensuite aux étapes ci-dessous.

Étape 3 : Create un projet WinUI 3 vide

Pour créer une application WebView2, commencez par créer un projet de bureau de base, afin de créer une application de bureau qui contient une seule fenêtre main :

  1. Si Visual Studio n’est pas en cours d’exécution, démarrez Visual Studio (et non Visual Studio Code). Dans la fenêtre de démarrage de Visual Studio, cliquez sur le Create un nouveau projet carte. La fenêtre Create un nouveau projet s’ouvre.

    Ou, si Visual Studio est en cours d’exécution, sélectionnez Fichier>Nouveau>projet. La boîte de dialogue Create un nouveau projet s’ouvre.

    Activation du mode développeur : Lorsque Visual Studio s’ouvre à un moment donné au cours des étapes du présent article, vous pouvez être invité à activer le mode développeur pour votre ordinateur. Pour plus d’informations, si nécessaire, consultez Activer votre appareil pour le développement dans Créer des applications de bureau pour Windows.

  2. Dans la boîte de dialogue Create un nouveau projet, dans le champ Recherche pour les modèles, entrez WinUI 3 dans Desktop :

    Recherche sur « WinUI 3 dans Desktop » pour créer un projet

  3. Cliquez sur le carte Application vide, Empaquetée (WinUI dans desktop) pour la sélectionner, puis cliquez sur le bouton Suivant.

    Si les modèles WinUI ne sont pas répertoriés, vous devez installer des modèles de projet comme mentionné ci-dessus, à partir des outils d’installation pour le SDK d'application Windows. Conseils supplémentaires pour faire apparaître le modèle :

    Après avoir installé les options « par défaut » pour Visual Studio 2022 Community Edition, dans Visual Studio Installer, cliquez sur le carte .NET, puis sur la droite, cochez la case SDK d'application Windows Modèles C#.

    Si le modèle de projet approprié n’apparaît toujours pas : dans le Visual Studio Installer, cliquez sur le carte UWP pour le sélectionner, cochez la case Outils C++ v143 à droite, puis cliquez sur le bouton Modifier.

    La boîte de dialogue Configurer votre nouveau projet s’affiche.

  4. Dans la zone de texte Nom du projet, entrez un nom de projet, tel que MyWebView2WinUI3 :

    Boîte de dialogue « Configurer votre nouveau projet »

  5. Dans la zone de texte Emplacement , entrez ou accédez à un emplacement, tel que C:\Users\username\Documents\WebView2.

  6. Cliquez sur le bouton Créer.

    Le nouveau projet WinUI 3 s’ouvre dans Explorateur de solutions dans Visual Studio :

    Nouveau projet WinUI 3 dans Explorateur de solutions

    • Le App.xaml.cs fichier définit une Application classe qui représente votre instance d’application.

    • Le MainWindow.xaml.cs fichier définit une MainWindow classe qui représente la fenêtre main affichée par votre instance d’application. Les classes dérivent des types dans l’espace Microsoft.UI.Xaml de noms de WinUI.

  7. Dans la liste déroulante Configurations de solution (au milieu de la partie supérieure de la fenêtre), sélectionnez Déboguer.

  8. Dans la liste déroulante Plateformes de solutions, sélectionnez une plateforme, telle que x64.

  9. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S) pour enregistrer le projet.

  10. Appuyez sur F5 pour générer et exécuter le projet. L’application WinUI Desktop vide s’ouvre, sans contrôle WebView2 ajouté :

    Nouvelle application WinUI 3 vide

  11. Fermez l’application.

Mise à jour des numéros de version cible

Pour l’étape de génération ci-dessus : si vous mettez à jour un projet précédent, vous devrez peut-être mettre à jour les numéros de version pour Version cible et Version minimale. Pour ce faire, dans Solution, cliquez avec le bouton droit sur le projet, puis sélectionnez Modifier le fichier projet. Votre .csproj fichier s’ouvre. Vérifiez que les valeurs sont mises à jour comme suit, puis enregistrez les modifications et générez le projet.

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

Les valeurs ci-dessus représentent :

  • Version cible : Windows 10, version 2004 (build 19041) ou ultérieure.
  • Version minimale : Windows 10, version 1809 (build 17763).

Étape 4 : Ajouter un contrôle WebView2

Ce projet de didacticiel est basé sur le modèle de projet Application vide, empaquetée (WinUI dans desktop) . Ce modèle de projet utilise windowsAppSDK, qui inclut le Kit de développement logiciel (SDK) WebView2.

Modifiez les MainWindow.xaml fichiers et MainWindow.xaml.cs pour ajouter un contrôle WebView2 au projet d’application WinUI 3 vide, comme suit :

  1. Dans Visual Studio, dans Explorateur de solutions, double-cliquez pour MainWindow.xaml l’ouvrir dans l’éditeur de code.

  2. Ajoutez l’espace de noms XAML WebView2 en insérant l’attribut suivant dans la balise de <Window> démarrage :

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

    Assurez-vous que votre code dans MainWindow.xaml est similaire à ce qui suit :

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

  3. Pour ajouter le contrôle WebView2, remplacez l’élément entier <StackPanel> par le code suivant <Grid> . La Source propriété, située en bas, définit l’URI initial affiché dans le contrôle 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>

  4. Dans Explorateur de solutions, développezMainWindow.xaml, puis ouvrez MainWindow.xaml.cs.

  5. Dans MainWindow.xaml.cs, commentez la ligne suivante, comme indiqué :

        // myButton.Content = "Clicked";

  6. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S) pour enregistrer le projet.

  7. Appuyez sur F5 pour générer et exécuter le projet.

  8. L’application est une application hôte WebView2 qui inclut le contrôle WebView2. Le contrôle WebView2 affiche le site web https://www.microsoft.com:

    Contrôle WebView2 affichant la page web microsoft.com

  9. Fermez l’application.

WinAppSDK prend en charge les environnements WebView2 personnalisés

WinAppSDK prend en charge les environnements WebView2 personnalisés, en commençant par WinAppSDK 1.5 (1.5.0-experimental2). Pour plus d’informations, consultez WinUI3 WebView2 avec un CoreWebView2Environment personnalisé.

Pour instancier un environnement WebView2 personnalisé, initialisez WebView2 avec l’un des remplacements de WebView2.EnsureCoreWebView2Async (répertoriés ci-dessous) et transmettez votre personnalisé CoreWebView2Environment (et éventuellement personnalisé CoreWebView2ControllerOptions) :

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

Consultez également l’exemple de code dans Désactivation de la navigation SmartScreen ci-dessous.

Informations de référence sur l’API :

Étape 5 : Ajouter des contrôles de navigation

Pour permettre aux utilisateurs de contrôler la page web affichée dans le contrôle WebView2, ajoutez une barre d’adresses à l’application, comme suit :

  1. Dans MainWindow.xaml, collez le code suivant dans l’élément <Grid> qui contient l’élément <controls:WebView2> :

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

    Assurez-vous que l’élément résultant <Grid> dans le MainWindow.xaml fichier correspond à ce qui suit :

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

  2. Dans MainWindow.xaml.cs, collez le code suivant dans myButton_Click, en remplaçant la méthode existante myButton_Click (qui est presque vide). Ce code permet d’accéder au contrôle WebView2 jusqu’à l’URL entrée dans la barre d’adresses.

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

  3. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S) pour enregistrer le projet.

  4. Appuyez sur F5 pour générer et exécuter le projet.

  5. Entrez une nouvelle URL complète dans la barre d’adresses, par https://www.bing.comexemple , puis cliquez sur le bouton Aller .

    Le contrôle WebView2 dans l’application affiche le site web Bing. La barre d’adresses affiche l’URL, par https://www.bing.comexemple :

    L’application affiche le site web Bing

  6. Entrez une URL incomplète dans la barre d’adresses, par bing.comexemple , puis cliquez sur le bouton Go .

    Une ArgumentException exception est levée et apparaît après la fermeture de l’application, car l’URL ne commence pas par http:// ou https://.

  7. Fermez l’application.

Étape 6 : événements de navigation

Dans cette section, vous ajoutez du code pour importer la bibliothèque WebView2 Core.

  1. Dans MainWindow.xaml.cs, ajoutez la ligne suivante en haut, au-dessus des autres using instructions :

    using Microsoft.Web.WebView2.Core;

    Les applications qui hébergent des contrôles WebView2 écoutent les événements suivants déclenchés par les contrôles WebView2 pendant la navigation sur la page web :

    • NavigationStarting
    • SourceChanged
    • ContentLoading
    • HistoryChanged
    • NavigationCompleted

    Si une redirection HTTP se produit, il y a plusieurs NavigationStarting événements dans une ligne.

    Pour plus d’informations, consultez Événements de navigation pour les applications WebView2.

    Lorsque des erreurs se produisent, les événements suivants sont déclenchés et une page web d’erreur peut s’afficher :

    • SourceChanged
    • ContentLoading
    • HistoryChanged

    À titre d’exemple d’utilisation des événements, inscrivez un gestionnaire pour NavigationStarting qui annule toutes les requêtes non HTTPS, comme suit :

  2. Dans MainWindow.xaml.cs, dans le constructeur, ajoutez la ligne suivante NavigationStarting pour inscrire la EnsureHttps méthode :

    public MainWindow()
{
    this.InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}

  3. Dans MainWindow.xaml.cs, sous le constructeur, ajoutez la méthode suivante EnsureHttps :

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

  4. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S) pour enregistrer le projet.

  5. Appuyez sur F5 pour générer et exécuter le projet.

  6. Dans l’application, dans la barre d’adresse, entrez une URL HTTP, telle que http://bing.com, puis cliquez sur le bouton Go .

    Rien ne se passe, car la navigation vers les sites HTTP est bloquée et nous n’avons pas encore ajouté de boîte de dialogue pour fournir des commentaires.

  7. Entrez une URL HTTPS, telle que https://bing.com, puis cliquez sur le bouton Go .

    L’application accède à la page spécifiée, car la navigation est autorisée pour les sites HTTPS.

  8. Fermez l’application.

Étape 7 : Script

Vous pouvez utiliser des applications hôtes pour injecter du code JavaScript dans des contrôles WebView2 au moment de l’exécution. Vous pouvez tâcher WebView2 pour exécuter des scripts JavaScript arbitraires ou ajouter des scripts d’initialisation. Le code JavaScript injecté s’applique à tous les nouveaux documents de niveau supérieur et aux images enfants jusqu’à ce que le Code JavaScript soit supprimé. Le code JavaScript injecté est exécuté avec un minutage spécifique, pour :

  • Exécutez le Code JavaScript injecté après la création de l’objet global.

  • Exécutez le code JavaScript injecté avant d’exécuter tout autre script inclus dans le document HTML.

Par exemple, vous ajoutez ensuite des scripts qui envoient une alerte lorsqu’un utilisateur tente d’ouvrir des sites non HTTPS. Pour ce faire, vous injectez un script dans le contenu web qui utilise ExecuteScriptAsync.

  1. Dans la EnsureHttps méthode , ajoutez la ligne suivante 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;
    }
}

  2. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S) pour enregistrer le projet.

  3. Appuyez sur F5 pour générer et exécuter le projet.

  4. Dans la barre d’adresse de l’application, entrez une URL non HTTPS, telle que http://www.bing.com, puis cliquez sur le bouton Go .

    Le contrôle WebView2 de l’application affiche une boîte de dialogue d’alerte pour les sites web non HTTPS, indiquant que le non-HTTPS uri n’est pas sécurisé :

    Le contrôle WebView2 de l’application affiche une boîte de dialogue d’alerte pour les sites web non HTTPS

  5. Fermez l’application.

Félicitations, vous avez créé votre première application WebView2 !

Considérations spéciales pour WinUI 3 WebView2

Désactivation de la navigation SmartScreen

WebView2 envoie les URL auxquelles vous accédez dans votre application au service SmartScreen pour garantir la sécurité de vos clients. Si vous souhaitez désactiver cette navigation, utilisez un personnalisé CoreWebView2Environment, comme suit :

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);
Désactivation de SmartScreen à l’aide d’une variable d’environnement

Nous vous déconseillons d’utiliser une variable d’environnement. Utilisez plutôt l’approche basée sur le code de l’API ci-dessus.

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

Cette variable d’environnement doit être définie avant CoreWebView2 la création, ce qui se produit lorsque la propriété WebView2.Source est initialement définie ou que la méthode WebView2.EnsureCoreWebView2Async est initialement appelée.

Définition de DefaultBackgroundColor

Dans WebView2 pour WinUI 3, le DefaultBackgroundColor paramètre existe sur l’objet XAML WebView2. Par exemple :

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

Transparence

WinUI 3 ne prend pas en charge les arrière-plans transparents. Consultez Prise en charge de l’arrière-plan transparent pour WebView2 ? · Problème #2992.

Prise en charge de WinAppSDK pour les environnements WebView2 personnalisés

Consultez WinAppSDK prend en charge les environnements WebView2 personnalisés, ci-dessus.

Voir aussi

developer.microsoft.com :

Github: