Partager via

Prise en main de WebView2 dans les applications WinUI 3 (sdk Windows App)

Cet article vous apprend à écrire votre propre code WebView2. Si vous souhaitez d’abord exécuter un exemple d’application, consultez l’exemple d’application Win32 ou un autre exemple d’application, tel que l’exemple d’application WinUI 3 (Windows App SDK).

Cet article explique comment configurer vos outils de développement et créer une application WebView2 initiale pour WinUI 3 (sdk Windows App) et en savoir plus sur les concepts WebView2 en cours de route. Vous utilisez d’abord le modèle de projet Visual Studio Application vide, empaquetée (WinUI 3 dans le bureau), qui utilise windowsAppSDK, qui inclut le Kit de développement logiciel (SDK) WebView2. Vous ajoutez ensuite un contrôle WebView2, une barre d’adresse et un bouton Atteindre , ainsi qu’une logique d’URL pour autoriser uniquement la navigation vers les URL HTTPS.

Dans ce tutoriel, vous procédez comme suit :

  1. Configurez l’environnement de développement.

  2. Utilisez le modèle de projet Visual Studio Application vide, empaquetée (WinUI 3 dans le bureau) pour créer un projet WinUI 3 vide, qui définit une application qui contient un bouton.

  3. Ajoutez un contrôle WebView2 au lieu du bouton et accédez d’abord à la page d’accueil Microsoft. WebView2 est pris en charge, car le modèle de projet utilise le package NuGet Microsoft.WindowsAppSDK , qui inclut le Kit de développement logiciel (SDK) WebView2.

  4. Ajoutez une barre d’adresse comme contrôle de zone de texte, puis utilisez la chaîne HTTPS entrée pour accéder à une nouvelle page web :

    L’application, après avoir accédé à l’adresse HTTPS Bing

  5. Insérez JavaScript dans le contrôle WebView2 pour afficher une alerte d’avertissement (boîte de dialogue) lorsque l’utilisateur tente d’accéder à une URL qui n’a qu’un http:// préfixe au lieu de https://:

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

Projet terminé

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

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

Étape 1 : Installer la dernière version de Visual Studio 2022

Vérifiez que Visual Studio 2022 est installé et à jour.

Pour installer la dernière version de Visual Studio 2022 :

  1. Accédez à Visual Studio : IDE et Éditeur de code pour les développeurs de logiciels et Teams, puis dans la section Visual Studio 2022 , cliquez sur le bouton Télécharger , puis sélectionnez Communauté 2022 ou une autre version.

  2. Dans la fenêtre contextuelle Téléchargements en haut à droite de Microsoft Edge, VisualStudioSetup.exe est répertorié. Cliquez sur Ouvrir le fichier.

    Visual Studio Installer s’ouvre.

  3. Suivez les invites et acceptez les valeurs par défaut. Vous allez installer ou mettre à jour une charge de travail et un composant d’une charge de travail à l’étape suivante.

Étape 2 : Installer la dernière version du KIT de développement logiciel (SDK) Windows App

Assurez-vous que la dernière version du KIT de développement logiciel (SDK) Windows App est installée dans Visual Studio 2022. Le Kit de développement logiciel (SDK) Windows App inclut des modèles de projet Visual Studio et le Kit de développement logiciel (SDK) WebView2. Ces modèles de projet incluent le modèle de projet Application vide, empaquetée (WinUI 3 in Desktop), qui utilise le WindowsAppSDK, y compris le Kit de développement logiciel (SDK) WebView2.

Le SDK Windows App est installé en tant que composant modèles C# du SDK Windows App de la charge de travail Développement .NET Desktop pour Visual Studio. Avant Visual Studio 2022 version 17.1, le Kit de développement logiciel (SDK) Windows App était installé en tant qu’extension Visual Studio, comme expliqué dans Installer les outils pour le Kit de développement logiciel (SDK) Windows App.

Pour installer la dernière version de Visual Studio 2022, la dernière Windows App SDK :

  1. Dans Windows, appuyez sur la touche Démarrer , puis tapez Visual Studio 2022.

    L’application Visual Studio 2022 est répertoriée.

  2. Cliquez sur Ouvrir.

    La boîte de dialogue Visual Studio 2022 s’ouvre, avec des sections, notamment Ouvrir récent et Bien démarrer.

  3. Cliquez sur Continuer sans code.

    Visual Studio s’ouvre.

  4. Dans le menu Outils , sélectionnez Obtenir des outils et des fonctionnalités.

    La fenêtre Visual Studio Installer s’ouvre.

  5. Vérifiez que l’onglet Charges de travail est sélectionné.

  6. Dans la section Desktop & Mobile, sélectionnez le carte pour la charge de travail développement .NET Desktop, afin qu’une coche s’affiche :

    Case à cocher du composant « modèles C# du SDK Windows App » de la charge de travail développement .NET Desktop dans Visual Studio Installer

  7. Dans l’arborescence Détails de l’installation à droite, dans Développement> .NET DesktopFacultatif, cochez la case pour le composant Modèles C# du SDK Windows App, en bas de l’arborescence.

  8. Cliquez sur le bouton Modifier .

    La boîte de dialogue Contrôle de compte d’utilisateur s’ouvre.

  9. Cliquez sur le bouton Oui .

    Vous êtes invité à fermer Visual Studio.

  10. Cliquez sur le bouton Continuer (en supposant que vous n’avez pas de travail non enregistré).

    Visual Studio télécharge et installe le dernier composant modèles C# du SDK Windows App. Dans la fenêtre Visual Studio Installer, un message indique Que toutes les installations sont à jour et Visual Studio 2022 s’ouvre.

Étape 3 : Créer un projet WinUI 3 vide

Ensuite, créez un projet qui est une application WebView2 de base pour WinUI 3 (sdk Windows App). Cette application de bureau contient une seule fenêtre principale. Le projet ne contiendra pas encore de code WebView2.

Pour créer une application WebView2 pour WinUI 3 (Windows App SDK) :

  1. Si Visual Studio est en cours d’exécution, sélectionnez Fichier>Nouveau>projet. La boîte de dialogue Créer un projet s’ouvre.

  2. Si Visual Studio 2022 n’est pas en cours d’exécution :

    1. Dans Windows, appuyez sur la touche Démarrer , puis tapez Visual Studio 2022.

      L’application Visual Studio 2022 est répertoriée.

    2. Cliquez sur Ouvrir.

      La boîte de dialogue de démarrage de Visual Studio 2022 s’ouvre, avec des sections, notamment Ouvrir récent et Prise en main.

    3. Dans la section Prise en main, cliquez sur l’carte Créer un projet. La fenêtre Créer un projet s’ouvre.

  3. Dans la fenêtre Créer un projet , dans le champ Rechercher des modèles , entrez WinUI 3 dans Desktop :

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

    Les modèles de projet qui ont été installés à l’étape principale précédente sont répertoriés.

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

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

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

    Boîte de dialogue « Configurer votre nouveau projet »

  6. Dans la zone de texte Emplacement , entrez ou accédez à un répertoire, tel que C:\Users\myUsername\source\.

  7. Cliquez sur le bouton Créer.

    Le projet est créé :

Nouveau projet WinUI 3 dans Explorateur de solutions

  1. Si une boîte de dialogue s’affiche, indiquant « Échec de l’installation du package Microsoft.WindowsAppSDK », cliquez sur le bouton OK .

Étape 4 : Mettre à jour ou installer le Kit de développement logiciel (SDK) Windows App

Lorsque vous créez un projet dans Visual Studio, case activée la status des packages NuGet de la solution. Assurez-vous que les packages NuGet nécessaires ont été installés par le modèle de projet et assurez-vous que les packages ont été mis à jour afin que le projet dispose des dernières fonctionnalités et correctifs.

Pour mettre à jour ou installer la dernière Windows App package NuGet du SDK pour votre projet :

  1. Dans Visual Studio, dans Explorateur de solutions, cliquez avec le bouton droit sur le projet WinUI3GetStarted, puis sélectionnez Gérer les packages NuGet.

    Dans Visual Studio, l’onglet NuGet : WinUI3GetStarted s’ouvre . Si le package Microsoft.WindowsAppSDK a été installé lors de la création du projet à l’aide du modèle de projet, l’onglet Installé est sélectionné et ce package est répertorié :

    Packages attendus répertoriés sous l’onglet Installé de l’onglet NuGet

    Si le package Microsoft.WindowsAppSDK n’est pas répertorié dans l’onglet Installé :

  2. Cliquez sur l’onglet Parcourir , puis dans la zone de texte Rechercher , entrez Microsoft.WindowsAppSDK.

  3. Sélectionnez le carte Microsoft.WindowsAppSDK :

    Installation du package sdk

  4. Cliquez sur le bouton Installer , à droite.

    La boîte de dialogue Aperçu des modifications s’ouvre.

  5. Cliquez sur le bouton Appliquer , puis acceptez les termes du contrat de licence.

    Le package NuGet Microsoft.WindowsAppSDK est installé.

  6. Sous l’onglet NuGet - Solution, cliquez sur l’onglet Mises à jour, puis mettez éventuellement à jour tous les packages qui y sont répertoriés.

  7. Fermez l’onglet NuGet - Solution .

Étape 5 : Générer et exécuter le projet

Le nouveau projet WinUI 3 reste ouvert 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 principale affichée par votre application instance. Les classes dérivent des types dans l’espace Microsoft.UI.Xaml de noms de WinUI.

Pour générer et exécuter le projet :

  1. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S).

  2. Sélectionnez Déboguer>Démarrer (F5).

    La boîte de dialogue Activer le mode développeur pour Windows peut s’ouvrir :

    Boîte de dialogue : Activer le mode développeur pour Windows

  3. Si cette boîte de dialogue s’affiche, cliquez sur Paramètres pour les développeurs, activez le bouton bascule Mode développeur , cliquez sur le bouton Oui , puis sur le bouton Fermer de la boîte de dialogue Visual Studio. Pour plus d’informations sur le mode développeur, consultez Activer votre appareil pour le développement dans Créer des applications de bureau pour Windows.

    Le projet est généré. L’application WinUI Desktop vide s’ouvre, sans contrôle WebView2 ajouté :

    Nouvelle application WinUI 3 vide

  4. Cliquez sur le bouton Cliquez sur moi .

    L’étiquette du bouton devient Clicked.

  5. Fermez l’application.

Étape 6 : Ajouter un contrôle WebView2

Le projet est basé sur le modèle de projet Application vide, empaquetée (WinUI 3 dans Desktop) qui utilise le package NuGet Microsoft.WindowsAppSDK , qui inclut le Kit de développement logiciel (SDK) WebView2. Nous pouvons donc ajouter du code WebView2. Vous allez modifier les MainWindow.xaml fichiers et MainWindow.xaml.cs pour ajouter un contrôle WebView2 au projet d’application WinUI 3 vide, en chargeant initialement la page d’accueil Microsoft. Dans le fichier XAML, le contrôle WebView est étiqueté comme suit :

<controls:WebView2 x:Name="MyWebView" Source="https://www.microsoft.com">

Pour ajouter un contrôle WebView2 qui accède initialement à la page d’accueil De Microsoft :

  1. Dans Visual Studio, dans Explorateur de solutions, double-cliquez sur MainWindow.xaml.

    Le fichier s’ouvre dans l’éditeur de code.

  2. Copiez et collez l’attribut suivant dans la <Window> balise de début, à la fin de la liste des espaces de noms XML :

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

    Ce code ajoute l’espace de noms XAML WebView2. Assurez-vous que votre code dans MainWindow.xaml est similaire à ce qui suit :

    <?xml version="1.0" encoding="utf-8"?>
<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"
    xmlns:controls="using:Microsoft.UI.Xaml.Controls"
    mc:Ignorable="d">

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

  3. Supprimez l’élément <StackPanel> (trois lignes).

  4. Au-dessus de la </Window> balise de fin, collez l’élément suivant <Grid> :

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

    Cet <Grid> élément contient un <controls:WebView2> élément nommé MyWebView, qui a un Source attribut qui définit l’URI initial affiché dans le contrôle WebView2 (https://www.microsoft.com). Lorsque l’application s’ouvre, elle affiche initialement la page d’accueil Microsoft.com, dans le contrôle WebView2.

  5. Dans Explorateur de solutions, développezMainWindow.xaml, puis double-cliquez sur MainWindow.xaml.cs.

  6. Dans MainWindow.xaml.cs, supprimez la ligne suivante de code C# dans la myButton_Click méthode :

    myButton.Content = "Clicked";

    La méthode est vide pour l’instant. Nous l’utiliserons pour le bouton Go de la barre d’adresses ultérieurement.

  7. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S).

  8. Appuyez sur la touche F5.

    Le projet est généré et l’application s’ouvre :

    Contrôle WebView2 affichant la page web microsoft.com

    L’application est une application hôte WebView2 qui inclut le contrôle WebView2. Le contrôle WebView2 affiche initialement le site web https://www.microsoft.com. Il n’y a pas encore de zone de texte de barre d’adresse ou de bouton Aller .

  9. Fermez l’application.

Étape 7 : 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 à l’intérieur de l’élément <Grid> , au-dessus de 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 bloc suivant try/catch dans le corps de la myButton_Click méthode :

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

    Ce code navigue dans le contrôle WebView2 jusqu’à l’URL que l’utilisateur entre dans la barre d’adresse, lorsque l’utilisateur clique sur le bouton Atteindre , en définissant à nouveau la valeur de la MyWebView.Source propriété, qui est équivalente à l’attribut Source de l’élément <controls:WebView2 x:Name="MyWebView"> .

  3. Sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S).

  4. Appuyez sur la touche F5.

    Le projet est généré et l’application s’ouvre, affichant initialement la page d’accueil Microsoft. Il y a maintenant une barre d’adresse et un bouton Aller .

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

    L’application affiche le site web Bing

    Le contrôle WebView2 dans l’application affiche le site web Bing. La barre d’adresse affiche l’URL, telle que https://www.bing.com.

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

    Le contrôle WebView2 ne tente pas d’accéder à cette URL. Une exception est levée, car l’URL ne commence pas par http:// ou https://. Dans la try section , la addressBar.Text chaîne ne commence pas par http:// ou https://, mais la chaîne non URI est passée au Uri constructeur, ce qui lève une System.UriFormatException exception. Dans Visual Studio, le volet Sortie affiche « Exception levée : 'System.UriFormatException' dans System.Private.Uri.dll ». L’application continue de s’exécuter.

  7. Fermez l’application.

Étape 8 : Gérer les événements de navigation

Une application qui héberge un contrôle WebView2 écoute les événements suivants :

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Ces événements sont déclenchés par un contrôle WebView2 pendant la navigation sur la page web. 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.

Lorsqu’une erreur se produit, les événements suivants sont déclenchés et une page web d’erreur peut s’afficher :

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Dans cette section, vous ajoutez du code pour importer la bibliothèque WebView2 Core, qui gère les événements de navigation pour accéder à différents types d’URL.

Pour gérer les événements de navigation :

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

    using Microsoft.Web.WebView2.Core;

    Inscrire un gestionnaire pour NavigationStarting qui annule toutes les requêtes non-HTTPS :

  2. Dans MainWindow.xaml.cs, dans le constructeur, ajoutez la ligne suivante NavigationStarting :

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

    Cette ligne inscrit la EnsureHttps méthode (ajoutée ci-dessous) en tant qu’écouteur de l’événement NavigationStarting .

  3. 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).

  5. Appuyez sur la touche F5.

    Le projet est généré et l’application s’ouvre.

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

    L’application n’accède pas à cette page, car la navigation vers les sites HTTP est bloquée. Nous n’avons pas encore ajouté de boîte de dialogue pour indiquer à l’utilisateur pourquoi le site affiché n’a pas changé.

  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. Dans l’application, dans la barre d’adresse, entrez une chaîne sans préfixe, telle que bing.com, puis cliquez sur le bouton Aller .

    L’application n’accède pas à cette page. Une UriFormatException exception est levée, comme précédemment, et apparaît dans le volet Sortie de Visual Studio.

  9. Fermez l’application.

Étape 9 : Insérer JavaScript pour avertir l’utilisateur d’une adresse non HTTPS

Vous pouvez utiliser l’application hôte pour injecter du code JavaScript dans le contrôle 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 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.

Ci-dessous, vous ajoutez JavaScript qui affiche une alerte lorsqu’un utilisateur tente d’ouvrir un site non HTTPS. Pour ce faire, vous injectez un script dans le contenu web qui utilise ExecuteScriptAsync.

Pour afficher une alerte lorsque l’utilisateur tente d’accéder à un site non HTTPS :

  1. Dans MainWindow.xaml.cs, 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).

  3. Appuyez sur la touche F5.

    Le projet est généré et l’application s’ouvre.

  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éé une application WebView2 WinUI 3 (sdk Windows App) !

Voir aussi

developer.microsoft.com :

GitHub :

  • Last updated on