Erste Schritte mit WebView2 in WinForms-Apps

Beginnen Sie in diesem Artikel mit dem Erstellen Ihrer ersten WebView2-App, und erfahren Sie mehr über die Hauptfeatures von WebView2. Für weitere Informationen zu einzelnen APIs navigieren Sie zur API-Referenz.

Voraussetzungen

Installieren Sie die folgende Liste der Erforderlichen, bevor Sie fortfahren.

  • WebView2 Runtime oder ein Microsoft Edge Insider (Vorschau)-Kanal (Beta, Dev oder Canary), der auf unterstützten Betriebssystemen installiert ist (derzeit Windows 10, Windows 8.1 und Windows 7).

    Hinweis

    Das WebView2-Team empfiehlt die Verwendung des Canary-Kanals, und die mindestens erforderliche Version ist 82.0.488.0.

  • Visual Studio 2017 oder höher.

Schritt 1: Erstellen einer Einzelfenster-App

Beginnen Sie mit einem einfachen Desktopprojekt, das ein einzelnes Hauptfenster enthält.

  1. Öffnen Sie Visual Studio. Wählen Sie im öffnende Bereich ein neues Projekt erstellenaus.

    Visual Studio öffnende Panel

  2. Wählen Sie C# Windows Forms .NET Framework Appaus, und wählen Sie dann weiter.

    Neues Projekt

  3. Geben Sie Werte für Project Namen und Speicherortein. Wählen Sie .NET Framework 4.7.2 oder höher aus.

    Projekt starten

  4. Wählen Sie Erstellen aus.

Schritt 2: Installieren des WebView2 SDK

Verwenden Sie NuGet, um das WebView2 SDK zum Projekt hinzuzufügen.

  1. Zeigen Sie auf das Projekt, öffnen Sie das Kontextmenü (klicken Sie mit der rechten Maustaste), und wählen Sie dann NuGet Pakete verwaltenaus.

    Verwalten NuGet Pakete

    Verwalten NuGet Pakete

  2. Wählen Sie "Durchsuchen" aus. Geben Sie in der Suchleiste Microsoft.Web.WebView2 Microsoft.Web.WebView2ein, und wählen Sie sie aus.

    NuGet

  3. Akzeptieren Sie die Standardversion, und wählen Sie dann "Installieren" aus.

    Änderungen in der Vorschau anzeigen

  4. Klicken Sie auf "OK", um fortzufahren.

    Beginnen Sie mit der Entwicklung von Apps mithilfe der WebView2-API. Um das Projekt zu erstellen und auszuführen, wählen Sie F5 . Das ausgeführte Projekt zeigt ein leeres Fenster an.

    Leere App

Schritt 3: Erstellen einer einzelnen WebView

Fügen Sie Ihrer App eine WebView hinzu.

  1. Wählen Sie Project > Formular hinzufügen (Windows Formulare) aus.

  2. Wählen Sie im Bereich "Neues Element hinzufügen" die Option Visual C#-Elemente-Web > **** > Windows > Formularformular (Windows Formulare) aus, und wählen Sie dann Hinzufügenaus.

  3. Wählen Sie "Toolbox anzeigen" > aus.

  4. Wählen Sie in der Toolbox WebView2 Windows Forms Control aus, um die Optionen zu erweitern.

    Hinweis

    Wenn Sie Visual Studio 2017 verwenden, wird WebView2 standardmäßig nicht in der Toolboxangezeigt. Um die Anzeige von WebView2 in der Toolboxzu aktivieren, wählen Sie "Extras-Optionen > **** > Allgemein" > aus, und legen Sie die Einstellung "Toolbox automatisch auffüllen" auf True fest.

  5. Drag and drop the WebView2 control into the Windows Forms App.

    Toolbox mit WebView2

  6. Schließen Sie die Toolbox.

  7. Legen Sie im Eigenschaftenbereich die Eigenschaft (Name) auf webViewfest. Verwenden Sie die Kategorisierten und alphabetischen Sortieroptionen nach Bedarf, um Eigenschaften zu finden.

    Eigenschaften des WebView2-Steuerelements

  8. Die Source-Eigenschaft legt den anfänglichen URI fest, der im WebView2-Steuerelement angezeigt wird. Legen Sie die Source-Eigenschaft auf https://www.microsoft.com .

  9. Wählen Sie F5 aus, um Ihr Projekt zu erstellen und auszuführen.

    Stellen Sie sicher, dass das WebView2-Steuerelement angezeigt [https://www.microsoft.com][|::ref1::|Main] wird.

    hello webview

Schritt 4: Hinzufügen von Steuerelementen und Ändern der Größe des Prozessfensters

Fügen Sie ihren Windows Formularen aus der Toolbox weitere Steuerelemente hinzu, und verarbeiten Sie dann die Fenstergröße wie folgt.

  1. Wählen Sie "Toolbox anzeigen" > aus.

  2. Wählen Sie in der Toolbox allgemeine Steuerelemente aus.

  3. Drag and drop TextBox control into the Windows Forms app.

  4. Ändern Sie im Eigenschaftenbereich den Namen in "addressBar".

  5. Drag and drop a Button control into the Windows Forms app.

  6. Ändern Sie im Eigenschaftenbereich den Namen in "goButton".

  7. Ändern Sie die Text-Eigenschaft in Go!

  8. Ändern Sie die Größe der Schaltfläche nach Bedarf, um den Text anzuzeigen.

  9. Ordnen Sie das Textfeld links neben der Schaltfläche an, das wie dargestellt am Text ausgerichtet ist.

    WinForms-Designer

  10. Ändern Sie die Größe des Textfelds wie dargestellt.

    WinForms Designer-Textfeld und Schaltfläche

  11. Wählen Sie **** > "Code anzeigen" aus, um die Datei zu Form1.cs öffnen.

    Legen Sie Form_Resize folgendermaßen fest, dass die Steuerelemente beim Ändern der Größe des App-Fensters beibehalten werden.

  12. Ersetzen Sie den folgenden Code:

        public Form1()
    {
        InitializeComponent();
    }
    

    Mit:

    public Form1()
    {
        InitializeComponent();
        this.Resize += new System.EventHandler(this.Form_Resize);
    }
    
    private void Form_Resize(object sender, EventArgs e)
    {
        webView.Size = this.ClientSize - new System.Drawing.Size(webView.Location);
        goButton.Left = this.ClientSize.Width - goButton.Width;
        addressBar.Width = goButton.Left - addressBar.Left;
    }
    
  13. Wählen Sie F5 aus, um das Projekt zu erstellen und auszuführen.

    Stellen Sie sicher, dass die App-Anzeige dem folgenden Bild ähnelt.

App

Schritt 5 : Navigation

Fügen Sie benutzern die Möglichkeit hinzu, die URL zu ändern, die das WebView2-Steuerelement anzeigt, indem Sie der App eine Adressleiste hinzufügen.

  1. Wählen Sie F5 die Option zum Erstellen und Ausführen des Projekts aus. Vergewissern Sie sich, dass die App ähnlich wie im folgenden Screenshot angezeigt wird.

    WinForms-App

  2. Um Form1.cs den Namespace hinzuzufügen, fügen Sie in der Datei oben den CoreWebView2 folgenden Codeausschnitt ein.

  3. Form1.csFügen Sie den Namespace CoreWebView2 hinzu, indem Sie den folgenden Codeausschnitt oben in Form1.cs einfügen.

    using Microsoft.Web.WebView2.Core;
    
  4. Doppelklicken Sie im Windows Formular-Designerauf die Go! Schaltfläche, um die Methode in der Datei zu goButton_Click Form1.cs erstellen. Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in die Funktion ein. Jetzt goButton_Click navigiert die Funktion die WebView zu der URL, die in der Adressleiste eingegeben wurde.

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

Um Ihr Projekt zu erstellen und auszuführen, wählen Sie F5 . Geben Sie eine neue URL in die Adressleiste ein, und wählen Sie "Los" aus. Geben Sie beispielsweise https://www.bing.com . Stellen Sie sicher, dass das WebView2-Steuerelement zur URL navigiert.

Hinweis

Stellen Sie sicher, dass in der Adressleiste eine vollständige URL eingegeben wird. Wird ArgumentException ausgelöst, wenn die URL nicht mit http:// oder https://

bing.com

Schritt 6: Navigationsereignisse

Während der Webseitennavigation löst das WebView2-Steuerelement Ereignisse aus. Die App, die WebView2-Steuerelemente hostet, überwacht die folgenden Ereignisse.

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Navigieren Sie zu Navigationsereignissen,um weitere Informationen zu erfahren.

Navigationsereignisse

Navigationsereignisse

Wenn ein Fehler auftritt, werden die folgenden Ereignisse ausgelöst und hängen möglicherweise von der Navigation zu einer Fehlerwebseite ab.

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Hinweis

Wenn eine HTTP-Umleitung erfolgt, gibt es mehrere NavigationStarting Ereignisse in einer Zeile.

Um zu veranschaulichen, wie die Ereignisse verwendet werden, registrieren Sie zunächst einen Handler dafür, der NavigationStarting alle Anforderungen abbricht, die nicht HTTPS verwenden.

Aktualisieren Sie in der Form1.cs Datei den Konstruktor so, dass er dem folgenden Codeausschnitt entspricht, und fügen Sie die EnsureHttps Funktion hinzu.

public Form1()
{
    InitializeComponent();
    this.Resize += new System.EventHandler(this.Form_Resize);

    webView.NavigationStarting += EnsureHttps;
}

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

Im Konstruktor EnsureHttps wird als Ereignishandler für das NavigationStarting Ereignis im WebView2-Steuerelement registriert.

Um Ihr Projekt zu erstellen und auszuführen, wählen Sie F5 . Stellen Sie sicher, dass die WebView beim Navigieren zu einer HTTP-Website unverändert bleibt. WebView navigiert jedoch zu HTTPS-Websites.

Schritt 7 – Skripting

Sie können Host-Apps verwenden, um JavaScript-Code zur Laufzeit in WebView2-Steuerelemente einzufügen. Sie können WebView zum Ausführen beliebigen JavaScripts oder zum Hinzufügen von Initialisierungsskripts verwenden. Das eingefügte JavaScript gilt für alle neuen Dokumente der obersten Ebene und alle untergeordneten Frames, bis javaScript entfernt wird. Das eingefügte JavaScript wird mit einem bestimmten Timing ausgeführt.

  • Führen Sie es nach der Erstellung des globalen Objekts aus.
  • Führen Sie es aus, bevor ein anderes skript, das im HTML-Dokument enthalten ist, ausgeführt wird.

Fügen Sie beispielsweise Skripts hinzu, die eine Warnung senden, wenn ein Benutzer zu Nicht-HTTPS-Websites navigiert. Ändern Sie die EnsureHttps Funktion, um ein Skript in den Webinhalt einzufügen, der die ExecuteScriptAsync-Methode verwendet.

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

Um Ihr Projekt zu erstellen und auszuführen, wählen Sie F5 . Stellen Sie sicher, dass die App eine Warnung anzeigt, wenn Sie zu einer Website navigieren, die https nicht verwendet.

https

Schritt 8: Kommunikation zwischen Host- und Webinhalten

Host- und Webinhalte können für die Kommunikation miteinander wie folgt verwendet postMessage werden:

  • Webinhalte in einem WebView2-Steuerelement können zum Posten einer Nachricht an den Host verwendet window.chrome.webview.postMessage werden. Der Host verarbeitet die Nachricht mithilfe einer WebMessageReceived beliebigen registrierten Nachricht auf dem Host.
  • Hosts post messages to web content in a WebView2 control using CoreWebView2.PostWebMessageAsString or CoreWebView2.PostWebMessageAsJSON . Diese Nachrichten werden von Handlern abgefangen, die hinzugefügt window.chrome.webview.addEventListener wurden.

Der Kommunikationsmechanismus übergibt Nachrichten von Webinhalten mit systemeigenen Funktionen an den Host.

Wenn das WebView2-Steuerelement in Ihrem Projekt zu einer URL navigiert, zeigt es die URL in der Adressleiste an und benachrichtigt den Benutzer über die im WebView2-Steuerelement angezeigte URL.

  1. Aktualisieren Sie in der Form1.cs Datei den Konstruktor, und erstellen Sie eine InitializeAsync Funktion, die dem folgenden Codeausschnitt entspricht. Die InitializeAsync Funktion wartet auf EnsureCoreWebView2Async, da die Initialisierung CoreWebView2 asynchron ist.

    public Form1()
    {
        InitializeComponent();
        this.Resize += new System.EventHandler(this.Form_Resize);
        webView.NavigationStarting += EnsureHttps;
        InitializeAsync();
    }
    
    async void InitializeAsync()
    {
        await webView.EnsureCoreWebView2Async(null);
    }
    
  2. Registrieren Sie nach der CoreWebView2 Initialisierung einen Ereignishandler, auf den reagiert werden WebMessageReceived soll. Aktualisieren Sie die Form1.cs Datei, InitializeAsync und fügen Sie sie UpdateAddressBar mithilfe des folgenden Codeausschnitts hinzu.

    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. Damit WebView die Webnachricht senden und darauf antworten kann, fügt der Host nach CoreWebView2 der Initialisierung ein Skript in den Webinhalt ein:

    1. Senden Sie die URL mithilfe von postMessage .
    2. Registrieren Sie einen Ereignishandler, um eine vom Host gesendete Nachricht zu drucken.

Aktualisieren Sie die Form1.cs Datei so, InitializeAsync dass sie dem folgenden Codeausschnitt entspricht.

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));");
}

Um die App zu erstellen und auszuführen, wählen Sie F5 . Jetzt zeigt die Adressleiste den URI im WebView2-Steuerelement an. Wenn Sie erfolgreich zu einer neuen URL navigieren, warnt WebView außerdem den Benutzer über die in der WebView angezeigte URL.

Endgültige App

Herzlichen Glückwunsch, Sie haben Ihre erste WebView2-App erstellt!

Weitere Informationen