Beispiel-App für WinUI 3 (Windows App SDK)
- Beispielname: WebView2_WinUI3_Sample
- Repositoryverzeichnis: WebView2_WinUI3_Sample
- Projektmappendatei:
WebView2_WinUI3_Sample.sln
In diesem Beispiel wird die Verwendung eines WebView2-Steuerelements in einer winUI 3 (Windows App SDK) Packaged-Anwendung veranschaulicht.
In diesem Beispiel können Sie die App auch mit einer festen Version von WebView2 Runtime ausliefern, anstatt die Version der WebView2-Runtime zu verwenden, die auf dem Computer des Benutzers installiert ist und ausgeführt wird.
NuGet-Pakete und Workloadkomponenten
Vor dem Erstellen gehen wir wie folgt vor:
- Aktualisieren Sie das NuGet-Paket Microsoft.Windows.SDK.BuildTools für das Projekt und für das Projekt (Paket).
- Aktualisieren Sie das NuGet-Paket Microsoft.WindowsAppSDK für das Projekt und für das Projekt (Paket).
- Installieren Sie die Komponente "Windows 10 SDK" der Workload "Windows-App-Entwicklung", sofern noch nicht installiert.
Verzeichnisse
Verzeichnis | Inhalt |
---|---|
WebView2_WinUI3_Sample | Projektcode |
WebView2_WinUI3_Sample (Paket) | Paket- und Distributionsprojekt |
WebView2_WinUI3_Sample (Package)\FixedRuntime | (Optional) Korrigierte WebView2-Runtime |
WebView2_WinUI3_Sample (Package)\FixedRuntime\130.0.2849.39 | (Optional) WebView2-Runtimebeispiel korrigiert |
Schritt 1: Installieren der neuesten Visual Studio 2022-Version
Stellen Sie sicher, dass Visual Studio 2022 installiert und auf dem neuesten Stand ist.
So installieren Sie die neueste Version von Visual Studio 2022:
Wechseln Sie zu Visual Studio: IDE und Code Editor für Softwareentwickler und Teams, und klicken Sie dann im Abschnitt Visual Studio 2022 auf die Schaltfläche Herunterladen, und wählen Sie dann Community 2022 oder eine andere Version aus.
Im Popup "Downloads " in der oberen rechten Ecke von Microsoft Edge
VisualStudioSetup.exe
ist aufgeführt. Klicken Sie auf Datei öffnen.Visual Studio-Installer wird geöffnet.
Folgen Sie den Anweisungen, und übernehmen Sie die Standardwerte.
Schritt 2: Klonen oder Herunterladen des WebView2Samples-Repositorys
- Falls noch nicht geschehen, klonen Sie das Repository, oder laden Sie es
WebView2Samples
auf Ihr lokales Laufwerk herunter. In einem separaten Fenster oder einer separaten Registerkarte finden Sie weitere Informationen unter Herunterladen des WebView2Samples-Repositorys unter Einrichten Ihrer Entwicklungsumgebung für WebView2. Führen Sie die Schritte in diesem Abschnitt aus, kehren Sie dann zu dieser Seite zurück, und fahren Sie weiter unten fort.
Schritt 3: Öffnen der Projektmappe in Visual Studio
Diese ersten Schritte zum Repository und Branch sind nicht erforderlich, aber sie sind eine bewährte Methode, um zu vermeiden, dass der Code im Branch "Standard" Ihrer geklonten Kopie des WebView2Samples-Repositorys geändert wird. Auf diese Weise können Sie die Dateien des Projekts ändern (um das Beispiel zu erstellen und auszuführen), während der Code, der sich im Branch "Standard" befindet, mit dem Repository identisch bleibt.
Sie können diese Schritte in jedem Tool für Git-Vorgänge ausführen, z. B.:
- GitHub Desktop.
- Die Registerkarte Git-Änderungen neben der Registerkarte Projektmappen-Explorer unten rechts in Visual Studio.
- Die Git Bash-Eingabeaufforderung.
So öffnen Sie die Projektmappendatei des Beispiels in einem Arbeitsbranch:
Wählen Sie in GitHub Desktop in der Liste Aktuelles Repository oben links das Repository WebView2Samples aus.
Klicken Sie oben in der Mitte des Fensters auf Ursprung abrufen .
Erstellen Sie im Menü Aktuelle Verzweigung einen Arbeitsbranch wie user/myGithubUsername/winui3-sample , und wechseln Sie zu diesem Branch.
Sie befinden sich jetzt sicher in einem Arbeitsbranch und nicht in der Verzweigung "Standard" und können damit beginnen, die Dateien des Beispiels zu ändern.
Öffnen Sie die
.sln
Datei auf Ihrem lokalen Laufwerk in Visual Studio.Beispielspeicherorte der
.sln
Datei: Wenn Sie das Repository geklont haben, lautet/WebView2Samples/
der Name des Repositoryverzeichnisses :<your-repos-directory>/WebView2Samples/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln
Wenn Sie das Repository heruntergeladen haben, lautet
/WebView2Samples-main/
der Name des Repositoryverzeichnisses , der den Branch "Standard" darstellt:<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln
Schritt 4: Aktualisieren der NuGet-Pakete
Klicken Sie Projektmappen-Explorer mit der rechten Maustaste auf das projekt WebView2_WinUI3_Sample, und wählen Sie dann NuGet-Pakete verwalten aus.
In Visual Studio wird der NuGet-Paket-Manager geöffnet:
Die Registerkarte Installiert ist ausgewählt und listet die NuGet-Pakete auf:
- Microsoft.Windows.SDK.BuildTools
- Microsoft.WindowsAppSDK
- Microsoft.Web.WebView2
Wählen Sie die Registerkarte Updates aus.
Aktivieren Sie oben links das Kontrollkästchen Alle Pakete auswählen .
Klicken Sie rechts neben diesem Kontrollkästchen auf die Schaltfläche Aktualisieren .
Das Dialogfeld Vorschau der Änderungen wird geöffnet.
Klicken Sie auf die Schaltfläche Übernehmen .
Das Dialogfeld Lizenzakzeptanz wird geöffnet.
Klicken Sie auf die Schaltfläche Ich stimme zu .
Die NuGet-Pakete werden aktualisiert, und die Nummer neben der Registerkarte Updates wird entfernt.
Klicken Sie auf das Menü Ansicht und dann auf das Menüelement Ausgabe .
Auf der Registerkarte Ausgabe ist in der Dropdownliste Ausgabe aus anzeigen die Option Paket-Manager ausgewählt. Die Ausgabe enthält Zeilen wie:
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
Aktualisieren von NuGet-Paketen im Projekt (Paket)
Klicken Sie Projektmappen-Explorer mit der rechten Maustaste auf das Projekt WebView2_WinUI3_Sample (Paket), und wählen Sie dann NuGet-Pakete verwalten aus.
Wählen Sie die Registerkarte Updates aus.
Aktivieren Sie oben links das Kontrollkästchen Alle Pakete auswählen .
Klicken Sie rechts neben diesem Kontrollkästchen auf die Schaltfläche Aktualisieren .
Das Dialogfeld Vorschau der Änderungen wird geöffnet.
Klicken Sie auf die Schaltfläche Übernehmen .
Das Dialogfeld Lizenzakzeptanz wird geöffnet.
Klicken Sie auf die Schaltfläche Ich stimme zu .
Die NuGet-Pakete werden aktualisiert, und die Nummer neben der Registerkarte Updates wird entfernt.
Klicken Sie auf das Menü Ansicht und dann auf das Menüelement Ausgabe .
Auf der Registerkarte Ausgabe ist in der Dropdownliste Ausgabe aus anzeigen die Option Paket-Manager ausgewählt. Die Ausgabe enthält Zeilen wie oben gezeigt.
Schließen Sie das Fenster NuGet-Paket-Manager .
Schritt 5: Installieren des Windows 10 SDK oder anderer Workloadkomponenten
Je nachdem, was Sie installiert haben, müssen Sie möglicherweise eine Visual Studio-Workload oder eine Komponente einer Workload wie die folgende installieren, um das Beispiel zu erstellen.
So installieren Sie die komponente Windows 10 SDK der Windows-Anwendungsentwicklungsworkload:
Klicken Sie in Visual Studio auf das Menü Extras , und klicken Sie dann auf das Menüelement Tools und Features abrufen .
Das fenster Visual Studio-Installer wird geöffnet.
Wählen Sie die Karte Windows-Anwendungsentwicklung aus, sodass ein Häkchen angezeigt wird.
Aktivieren Sie in der Installationsdetailsstruktur auf der rechten Seite das Kontrollkästchen Windows 10 Komponente SDK 10.0.19041.0.
Klicken Sie auf die Schaltfläche Ändern .
Das Dialogfeld Benutzerkontensteuerung wird geöffnet.
Klicken Sie auf die Schaltfläche Ja .
Das Dialogfeld "Before we get started" (der Visual Studio-Installer) wird geöffnet, in dem Sie aufgefordert werden, Ihre Arbeit in Visual Studio zu speichern.
Schließen Sie das Standard Visual Studio-Fenster, und speichern Sie sie bei Bedarf.
Klicken Sie im Dialogfeld Bevor wir beginnen auf die Schaltfläche Wiederholen .
Nach einigen Minuten wird die Workloadkomponente Windows 10 SDK 10.0.19041.0 heruntergeladen und installiert. Visual Studio-Installer sagt: "Alle Installationen sind auf dem neuesten Stand."
Schritt 6: Erstellen und Ausführen der App
Öffnen Sie die Projektmappe in Visual Studio 2022. Klicken Sie beispielsweise in Visual Studio-Installer im Abschnitt Visual Studio 2022 auf die Schaltfläche Starten.
Das Visual Studio-Startfeld wird mit den Abschnitten Zuletzt geöffnet und Erste Schritte geöffnet.
Wählen Sie im Abschnitt Zuletzt geöffnetdie Option WebView2_WinUI3_Sample.sln aus.
Die Projektmappe wird in Visual Studio 2022 geöffnet.
Drücken Sie F5.
In Projektmappen-Explorer ist das Projekt (Paket) fett formatiert, was angibt, dass es sich um das Standardprojekt handelt. Die App wird erstellt, und dann wird das App-Fenster WebView2_WinUI3_Sample (Paket) geöffnet:
Unten wird die Meldung "Navigation abgeschlossen" angezeigt.
Geben Sie in der Adressleiste (ein Textfeld) (eine vollständige HTTPS-URL) ein
https://bing.com
, und drücken Sie dann die EINGABETASTE (entspricht dem Klicken auf die Schaltfläche Gehe zu).Das WebView2-Steuerelement navigiert zu Bing und zeigt dann unten "Navigation abgeschlossen" an.
In Visual Studio werden im Ausgabefenster Meldungen wie die folgenden angezeigt:
AddressBar_KeyDown [Enter]: https://bing.com TryNavigate TryCreateUri Navigation complete
Schritt 7: Committen von Änderungen in Ihrem Arbeitsbranch
In einem Git-Tool wie GitHub Desktop können Sie an diesem Punkt Änderungen committen und optional an einen Fork Ihres Branchs auf GitHub pushen. Diese Arten von Vorgängen sind relevant, wenn Sie das Beispiel ändern, experimentieren und anpassen. Dadurch bleibt auch Ihr Arbeitsbranch sauber und Ihr Klon des Repositorys organisiert, sodass Sie zu einem anderen Beispiel wechseln können.
So committen und pushen Sie Änderungen, die am Beispiel in Ihrem Arbeitsbranch vorgenommen wurden:
Wählen Sie in Visual Studio Datei>Alle speichern (STRG+UMSCHALT+S) aus.
Geben Sie in GitHub Desktop eine kurze Commitnachricht ein, z. B. "Aktualisiert, erstellt, Beispiel ausgeführt", und klicken Sie dann auf die Schaltfläche Commit.
Wählen Sie Repositorypush> aus. Ihr Arbeitsbranch wird von Ihrem lokalen Laufwerk in den verzweigten Branch des WebView2Samples-Repositorys auf GitHub kopiert.
Anzeigen Ihres Arbeitsbranchs auf GitHub
Wechseln Sie in Microsoft Edge zu Ihrem Fork des Repositorys, z
https://github.com/myGithubUsername/WebView2Samples/
. B. .Klicken Sie auf den Link [#] Branches , und wählen Sie dann Ihren neuen Arbeitsbranch aus, z
user/myGithubUsername/winui3-sample
. B. .
Schritt 8: Untersuchen des Codes
Schließen Sie die app WebView2_WinUI3_Sample (Paket).
Doppelklicken Sie in Projektmappen-Explorer im projekt WebView2_WinUI3_Sample auf jede
.xaml
Datei und ihre.cs
Datei:-
App.xaml
– Kein WebView2-Code.-
App.cs
– Code für die Verwendung einer Festversion der WebView2-Runtime.
-
-
MainWindow.xaml
– WebView2-Elemente.-
MainWindow.cs
– WebView2-Code.
-
-
Nachstehend finden Sie komprimierte Versionen dieser Dateien.
App.xaml
Diese Datei enthält keinen WebView2-spezifischen Code.
Verkürzte Auflistung
<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
Der WebView2-spezifische Code in dieser Datei ist auskommentiert. Sie können die Auskommentierung dieser Zeilen aufheben, um eine Runtime mit fester Version zu verwenden. Weitere Informationen finden Sie weiter unten unter Verwenden einer WebView2-Runtime mit fester Version.
Verkürzte Auflistung
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
Das Standard-Fenster enthält die folgenden XAML-Elemente als Steuerelemente:
-
<TextBox>
– Die Adressleiste. -
<Button>
– Die Schaltfläche "Gehe zu". -
<WebView2>
– Das WebView2-Steuerelement. -
<TextBlock>
: Die status Leiste.
Verkürzte Auflistung
<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
Die MainWindow-Klasse verfügt über die folgenden Methoden:
- Konstruktor
- StatusUpdate
- WebView2_CoreWebView2Initialized
- WebView2_NavigationCompleted
- TryCreateUri
- TryNavigate
- Go_OnClick
- AddressBar_KeyDown
- SetTitle
- GetWebView2Version
Auszüge oder komprimierte Versionen dieser Methoden finden Sie unten.
MainWindow-Klasse
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}";
}
Verwenden einer WebView2-Runtime mit fester Version
Wenn Sie eine feste Version der WebView2-Runtime mit Ihrer Anwendung versenden möchten, müssen Sie sie in Ihr Projekt einschließen. Weitere Informationen finden Sie unter Verteilen Ihrer App und der WebView2-Runtime.
In den folgenden Schritten wird die Runtimeversionsnummer 130.0.2849.39
angezeigt. Sie ändern diese Nummer in die Version, die Sie verpacken und versenden.
So verwenden Sie eine Runtime mit fester Version:
Fügen Sie die feste WebView2-Runtime in das Paketprojekt ein:
\WebView2_WinUI3_Sample\WebView2_WinUI3_Sample (Package)\FixedRuntime\130.0.2849.39\
Verwenden Sie oben die Version, die Sie senden, anstelle von
130.0.2849.39
.Aktualisieren Sie die Paketprojektdatei
wapproj
für die version, die Sie verwenden (verwenden Sie Ihre Version anstelle von130.0.2849.39
):< Content Include="FixedRuntime\130.0.2849.39\\**\*.*" >
Heben Sie in
App.xaml.cs
die Auskommentierung der fünf auskommentierten Codezeilen unterhalb des Kommentars auf, um die Laufzeitüberschreibung zu aktivieren: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); }
Ändern Sie im obigen Code die Versionsnummer von in
130.0.2849.39
die Version, die Sie versenden.