Prise en main de WebView2 dans les applications WPF

  • Article

Cet article explique comment configurer vos outils de développement et créer une application WebView2 initiale pour Windows Presentation Foundation (WPF) et en savoir plus sur les concepts WebView2 en cours de route.

Dans ce tutoriel, vous allez utiliser le modèle de projet Application WPF ou Application WPF (.NET Framework) pour créer une application WPF, puis installer le Kit de développement logiciel (SDK) WebView2 pour le projet afin d’ajouter WebView2.

Projet terminé

Une version terminée de ce projet de didacticiel est disponible dans le référentiel WebView2Samples :

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

Étape 1 : Installer Visual Studio avec la prise en charge de .NET

Ce didacticiel nécessite Microsoft Visual Studio, et non Microsoft Visual Studio Code. Cet article décrit principalement l’utilisation de Visual Studio 2022.

  1. Installez Visual Studio. Installez la prise en charge du développement .NET Desktop pour obtenir les modèles de projet nécessaires, comme suit.

  2. Si vous êtes sur l’écran de démarrage de Visual Studio, faites défiler vers le bas de la boîte de dialogue Créer un projet et cliquez sur le lien Ouvrir sans code. Visual Studio s’ouvre.

  3. Dans Visual Studio, sélectionnez Outils>Obtenir des outils et des fonctionnalités. La fenêtre Visual Studio Installer s’ouvre et la boîte de dialogue Modifier s’ouvre dessus.

  4. Sélectionnez la charge de travail développement .NET Desktop pour y placer une coche.

  5. Dans la section Détails >de l’installation.Développement>de bureau NETInclus à droite, assurez-vous que les outils de développement .NET Desktop et les outils de développement .NET Framework 4.7.2 sont répertoriés, avec une coche en regard d’eux.

  6. Dans la section Détails >de l’installation.NETDesktop development> Optional sur la droite :

    • Si vous utilisez Visual Studio 2022, vérifiez que Outils de développement pour .NET est sélectionné :

    Boîte de dialogue « Modification » de Visual Studio 2022 pour installer des modèles pour « Développement de bureau .NET »

    • Si vous utilisez Visual Studio 2019, vérifiez que les outils de développement .NET sont sélectionnés :

    Boîte de dialogue « Modification » de Visual Studio 2019 pour installer des modèles pour « Développement de bureau .NET »

  7. Cliquez sur le bouton Modifier .

Ce didacticiel fonctionne également avec Visual Studio 2017. Consultez Téléchargements plus anciens de Visual Studio. Installez la prise en charge de .NET pour obtenir les modèles de projet nécessaires, comme pour les étapes ci-dessus.

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

  1. Téléchargez n’importe quel canal Microsoft Edge Insider (préversion) (bêta, dev ou canary) sur un système d’exploitation pris en charge :

    • Windows 10
    • Windows 11

    Nous vous recommandons d’utiliser le canal Canary de Microsoft Edge. La version minimale requise est 82.0.488.0.

Étape 3 : Créer une application WebView2 à fenêtre unique

Commencez par créer un projet de bureau de base qui contient une fenêtre main unique.

  1. Décidez si vous souhaitez créer un projet .NET Core/5/6 (plus récent) ou un projet d’application WPF (.NET Framework) (plus ancien). Pour plus d’informations, consultez l’article suivant :

    • Historique .NET dans Qu’est-ce que .NET ? Présentation et vue d’ensemble.
    • .NET sur Wikipédia.

  2. Suivez la section applicable ci-dessous.

Création d’un projet .NET Core/5/6

Si vous créez un projet .NET Core/5/6, procédez comme suit. Sinon, passez à Création d’un projet d’application WPF (.NET Framework).

  1. Ouvrez Microsoft Visual Studio, par exemple Visual Studio 2022.

  2. Dans le volet d’ouverture, cliquez sur Créer un projet. Ou, dans la fenêtre main Visual Studio, sélectionnez Fichier>Nouveau>projet. La boîte de dialogue Créer un projet s’ouvre.

  3. Dans la zone de texte Rechercher des modèles , tapez WPF Application. Le panneau Créer un projet affiche les modèles de projet installés qui correspondent au texte que vous avez entré. Cet article présente les boîtes de dialogue C# plutôt que VB ; Les deux langues sont prises en charge pour WebView2.

  4. Si vous utilisez Visual Studio 2022, cliquez sur un modèle de projet avec le titre Application WPF et le texte de description Un projet pour créer une application WPF .NET :

    Sélection du modèle « Application WPF : application WPF .NET Core » dans la boîte de dialogue « Créer un projet » 2022

    Si vous utilisez Visual Studio 2019, cliquez sur un modèle de projet portant le titre Application WPF et le texte de description Un projet pour la création d’une application WPF .NET Core :

    Sélection du modèle « Application WPF : application WPF .NET Core » dans la boîte de dialogue « Créer un projet » 2019

    Si le modèle de projet ci-dessus n’est pas répertorié, consultez Étape 1 - Installer Visual Studio avec la prise en charge de .NET ci-dessus, pour installer les outils de développement de bureau .NET.

  5. Cliquez sur le bouton Suivant .

    La boîte de dialogue Configurer votre nouveau projet : Application WPF s’ouvre :

    Boîte de dialogue « Configurer votre nouveau projet : application WPF » pour un projet .NET Core/5/6

  6. Dans la zone de texte Nom du projet, entrez un nom de projet, tel que MyWpfDotnetCoreWv2App.

  7. Dans la zone de texte Emplacement , sélectionnez un chemin d’accès sur votre lecteur local, par C:\Users\myusername\Documents\MyProjectsexemple , puis cliquez sur le bouton Suivant .

    La boîte de dialogue Informations supplémentaires s’affiche, avec une liste déroulante Framework cible :

    Boîte de dialogue « Informations supplémentaires » avec une liste déroulante « Infrastructure cible »

  8. Sélectionnez .NET Core 3.1 ou version ultérieure, par exemple .NET 6.0. (Ne sélectionnez pas .NET Core 3.0.) Cliquez ensuite sur le bouton Créer .

    Le projet d’application WPF .NET Core initial s’ouvre dans Visual Studio :

    Projet initial dans Visual Studio 2022 à l’aide du modèle d’application WPF .NET Core

Passez à l’étape 4 - Générer et exécuter le projet initial sans WebView2 ci-dessous.

Création d’un projet d’application WPF (.NET Framework)

Si vous créez un projet d’application WPF (.NET Framework), procédez comme suit. Sinon, passez à l’étape 4 - Générer et exécuter le projet initial sans WebView2.

  1. Ouvrez Microsoft Visual Studio, par exemple Visual Studio 2022.

  2. Dans le volet d’ouverture, cliquez sur Créer un projet. Ou, dans la fenêtre main Visual Studio, sélectionnez Fichier>Nouveau>projet. La boîte de dialogue Créer un projet s’ouvre.

  3. Dans la zone de texte Rechercher des modèles , tapez WPF App. Le panneau Créer un projet affiche les modèles de projet installés qui correspondent au texte que vous avez entré. Cet article présente les boîtes de dialogue C# plutôt que VB ; Les deux langues sont prises en charge pour WebView2.

  4. Cliquez sur un modèle de projet avec le titre Application WPF (.NET Framework) et le texte de description Windows Presentation Foundation application cliente :

    Sélection du modèle « Application WPF » dans la boîte de dialogue « Créer un projet » 2022

    Si le modèle de projet ci-dessus n’est pas répertorié, consultez Étape 1 - Installer Visual Studio avec la prise en charge de .NET ci-dessus, pour installer les outils de développement de bureau .NET.

  5. Cliquez sur le bouton Suivant .

    La boîte de dialogue Configurer votre nouveau projet : Application WPF (.NET Framework) s’ouvre :

    Boîte de dialogue « Configurer votre nouveau projet : application WPF (.NET Framework) »

  6. Dans la zone de texte Nom du projet, entrez un nom de projet, tel que MyWpfDotnetFwkWv2App.

  7. Dans la zone de texte Emplacement , sélectionnez un chemin d’accès sur votre lecteur local, par C:\Users\myusername\Documents\MyProjectsexemple .

  8. Dans la liste déroulante Framework , sélectionnez .NET Framework 4.6.2 ou version ultérieure.

  9. Cliquez sur le bouton Créer.

    Le projet d’application WPF initial (.NET Framework) s’ouvre dans Visual Studio :

    Projet initial dans Visual Studio 2022 à l’aide du modèle Application WPF (.NET Framework)

Étape 4 : Générer et exécuter le projet initial sans WebView2

  1. Sélectionnez Fichier>Enregistrer tout pour enregistrer le projet.

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

    Le projet s’exécute et affiche une fenêtre vide :

    Fenêtre d’application vide sans WebView2

    Vous devrez peut-être installer la version sélectionnée du .NET Framework, comme suit.

  3. Si l’application ne s’ouvre pas, sélectionnez Déboguer>Démarrer sans débogage.

    Si vous n’avez pas installé la version sélectionnée du .NET Framework, vous pouvez obtenir la boîte de dialogue suivante : « Cette application n’a pas pu être démarrée. L’application nécessite l’une des versions suivantes du .NET Framework : . NETFramework,Version=v4.8.1 : voulez-vous installer cette version du .NET Framework maintenant ? »

  4. Si vous obtenez une telle boîte de dialogue, accédez à Télécharger .NET Framework et téléchargez, puis installez la version nécessaire du Pack de développement (et non le runtime). Par exemple, téléchargez sur ndp481-devpack-enu.exeC:\Users\username\Downloads, puis double-cliquez sur le fichier pour l’installer.

  5. Si vous y êtes invité, redémarrez votre ordinateur :

    Redémarrer pour installer .NET Framework

  6. Accédez au fichier téléchargé, par ndp481-devpack-enu.exe exemple dans C:\Users\username\Downloads, puis double-cliquez à nouveau sur le fichier téléchargé pour installer le Kit de développement .NET Framework. Une boîte de dialogue Réussite s’affiche :

    Installation réussie pour l’installation du .NET Framework

  7. Si vous y êtes invité, redémarrez l’ordinateur.

  8. Ouvrez Visual Studio, puis ouvrez la solution que vous avez créée.

  9. Appuyez sur F5 pour exécuter l’application initiale (illustrée ci-dessus), sans inclure le Kit de développement logiciel (SDK) WebView2.

  10. Fermez l’application initiale.

Étape 5 : Installer le Kit de développement logiciel (SDK) WebView2

Dans Visual Studio, utilisez le Gestionnaire de package NuGet pour ajouter le Kit de développement logiciel (SDK) WebView2 au projet, comme suit :

  1. Dans Explorateur de solutions, cliquez avec le bouton droit sur le nom du projet (en fonction du modèle de projet .NET (Core) ou .NET Framework), puis sélectionnez Gérer les packages NuGet :

    Commande « Gérer les packages NuGet » dans le menu contextuel

  2. En haut à gauche, cliquez sur l’onglet Parcourir . Dans la barre de recherche, tapez Microsoft.Web.WebView2, puis cliquez sur le package Microsoft.Web.WebView2 .

    La boîte de dialogue gestionnaire de package NuGet affiche les résultats de la recherche, y compris un package Microsoft.Web.WebView2 . La boîte de dialogue a un numéro de version et un bouton Installer .

    La boîte de dialogue gestionnaire de package NuGet affiche le package Microsoft.Web.WebView2

  3. Acceptez la version par défaut, puis cliquez sur le bouton Installer .

  4. Dans la boîte de dialogue Aperçu des modifications , cliquez sur le bouton OK .

  5. Sélectionnez Fichier>Enregistrer tout pour enregistrer le projet.

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

    Le projet s’exécute et affiche une fenêtre vide. Cela vérifie que WebView2 est installé et fonctionne, bien que WebView2 n’ait pas encore de contenu à afficher :

    Fenêtre d’application vide avec le Kit de développement logiciel (SDK) WebView2

  7. Fermez l’application.

Étape 6 : Créer un seul contrôle WebView2

Ajoutez un contrôle WebView2 à votre application.

  1. Dans le MainWindow.xaml fichier, pour ajouter l’espace de noms XAML WebView2, insérez la ligne suivante à l’intérieur de la <Window/> balise :

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

  2. Vérifiez que le code dans MainWindow.xaml ressemble au code suivant :

    <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. Pour ajouter le contrôle WebView2, remplacez les <Grid> balises par le code suivant. La Source propriété définit l’URI initial affiché dans le contrôle WebView2.

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

  4. Sélectionnez Fichier>Enregistrer tout pour enregistrer le projet.

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

  6. Vérifiez que votre contrôle WebView2 affiche https://www.microsoft.com:

    Le contrôle WebView2, qui affiche le contenu de la page web à partir de microsoft.com

Étape 7 : Navigation

Permettre aux utilisateurs de modifier l’URL affichée par le contrôle WebView2 en ajoutant une barre d’adresses à l’application.

  1. Dans le MainWindow.xaml fichier, ajoutez une barre d’adresses en copiant et collant le code suivant dans le <DockPanel> qui contient le contrôle WebView2. Conservez le code existant sous le nouvel extrait de code.

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

  2. Vérifiez que la <DockPanel> section du MainWindow.xaml fichier correspond au code suivant :

    <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. Dans MainWindow.xaml.cs, pour ajouter l’espace CoreWebView2 de noms, insérez le code suivant en haut du fichier :

    using Microsoft.Web.WebView2.Core;

  4. Dans le MainWindow.xaml.csfichier , copiez le code suivant pour créer la ButtonGo_Click méthode . Ce code permet d’accéder au contrôle WebView2 jusqu’à l’URL entrée dans la barre d’adresses.

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

  5. Collez le code directement après la Public MainWIndow déclaration, comme indiqué dans le code suivant :

    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. Sélectionnez Fichier>Enregistrer tout pour enregistrer le projet.

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

  8. Tapez une nouvelle URL dans la barre d’adresses, puis choisissez Go. Par exemple, tapez https://www.bing.com.

  9. Assurez-vous que le contrôle WebView2 ouvre l’URL que vous avez entrée.

    Veillez à entrer une URL complète dans la barre d’adresse. L’application génère un ArgumentException si l’URL ne commence pas par http:// ou https://.

    L’exemple d’application affiche le site web Bing avec l’URL https://www.bing.com dans la barre d’adresse :

    L’application affiche le site web Bing

Étape 8 - Événements de navigation

Pendant la navigation sur la page web, le contrôle WebView2 déclenche des événements. L’application qui héberge les contrôles WebView2 écoute les événements suivants :

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Événements de navigation, du nouveau document au démarrage de la navigation, en passant par la navigation terminée

Le diagramme ci-dessus montre la séquence d’événements. Les événements de navigation commencent par un nouveau document.

Chemin de réussite

Un chemin d’accès réussi inclut la séquence complète d’événements :

  1. Démarrage de la navigation.
  2. Source modifiée, avec une entrée possible à partir du même document.
  3. Chargement de contenu.
  4. Modifications de l’historique.
  5. Navigation terminée.

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

Chemin d’accès de l’échec

En cas d’échec, le chemin d’accès de l’échec passe directement du démarrage de la navigation à la navigation terminée, en ignorant les événements intermédiaires.

Lorsqu’une erreur se produit, les événements suivants sont déclenchés et peuvent dépendre de la navigation vers une page web d’erreur :

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Redirection

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

Exemple illustrant des événements de navigation

Pour montrer comment utiliser les événements, inscrivez un gestionnaire pour NavigationStarting qui annule toutes les requêtes non HTTPS, comme suit.

  1. Dans le MainWindow.xaml.cs fichier , modifiez le constructeur pour qu’il corresponde à la partie supérieure du code suivant. Sous le constructeur, ajoutez la EnsureHttps fonction :

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

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

    Dans le constructeur, EnsureHttps est inscrit en tant que gestionnaire d’événements sur l’événement NavigationStarting sur le contrôle WebView2.

  2. Sélectionnez Fichier>Enregistrer tout pour enregistrer le projet.

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

  4. Essayez d’ouvrir un site HTTP. Assurez-vous que le contrôle WebView2 reste inchangé.

  5. Essayez d’ouvrir un site HTTPS. Le contrôle WebView2 vous permet d’ouvrir des sites HTTPS.

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

  • Exécutez-le après la création de l’objet global.
  • Exécutez-le avant l’exécution de tout autre script inclus dans le document HTML.

Par exemple, ajoutez des scripts qui envoient une alerte lorsqu’un utilisateur navigue vers des sites non HTTPS, comme suit :

  1. Modifiez la EnsureHttps fonction pour injecter un script dans le contenu web qui utilise la méthode 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. Sélectionnez Fichier>Enregistrer tout pour enregistrer le projet.

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

  4. Assurez-vous que l’application affiche une alerte lorsque vous accédez à un site web qui n’utilise pas HTTPS.

    Message montrant qu’une URL http: n’est pas sécurisée et recommande d’essayer une URL https: à la place

Étape 10 : Communication entre le contenu hôte et le contenu web

Le contenu hôte et le contenu web peuvent communiquer des manières suivantes à l’aide postMessagede :

  • Le contenu web d’un contrôle WebView2 peut publier un message sur l’hôte à l’aide window.chrome.webview.postMessagede . L’hôte gère le message à l’aide de n’importe quel inscrit WebMessageReceived sur l’hôte.

  • Les hôtes publient des messages sur du contenu web dans un contrôle WebView2 à l’aide de CoreWebView2.PostWebMessageAsString ou CoreWebView2.PostWebMessageAsJSON. Les messages sont interceptés par des gestionnaires ajoutés à window.chrome.webview.addEventListener.

Le mécanisme de communication transmet les messages du contenu web à l’hôte à l’aide de fonctionnalités natives.

Dans votre projet, lorsque le contrôle WebView2 accède à une URL, il affiche l’URL dans la barre d’adresses et avertit l’utilisateur de l’URL affichée dans le contrôle WebView2.

  1. Dans MainWindow.xaml.cs, mettez à jour votre constructeur et créez une InitializeAsync fonction pour qu’elle corresponde au code suivant. La InitializeAsync fonction attend EnsureCoreWebView2Async, car l’initialisation de CoreWebView2 est asynchrone.

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

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

  2. Une fois CoreWebView2 initialisé, inscrivez un gestionnaire d’événements pour répondre à WebMessageReceived. Dans MainWindow.xaml.cs, mettez à jour InitializeAsync et ajoutez UpdateAddressBar à l’aide du code suivant :

    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. Pour que le contrôle WebView2 envoie et réponde au message web, une fois CoreWebView2 initialisé, l’hôte effectue les opérations suivantes :

    1. Injecte un script dans le contenu web qui inscrit un gestionnaire pour imprimer le message de l’hôte.
    2. Injecte un script dans le contenu web qui publie l’URL sur l’hôte.

  4. Dans MainWindow.xaml.cs, mettez à jour InitializeAsync pour correspondre au code suivant :

    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. Sélectionnez Fichier>Enregistrer tout pour enregistrer le projet.

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

  7. Lorsque vous ouvrez un nouvel URI, le contrôle WebView2 affiche l’URI dans la barre d’adresses.

    L’exemple d’application affiche l’URI dans la barre d’adresses et le site web Microsoft, https://www.microsoft.com:

    L’exemple d’application affiche l’URI dans la barre d’adresses et le site web Microsoft

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

Voir aussi

developer.microsoft.com :

Pages locales :

Github: