Verwalten von Benutzerdatenordnern

Der Benutzerdatenordner (User Data Folder, UDF) ist ein Ordner, der auf dem Computer des Benutzers gespeichert ist und Daten im Zusammenhang mit der Host-App und WebView2 enthält. WebView2-Apps verwenden Benutzerdatenordner, um Browserdaten wie Cookies, Berechtigungen und zwischengespeicherte Ressourcen zu speichern.

Terminologie:

WebView2 erstellt die UDF am Standardspeicherort für die Plattform oder am benutzerdefinierten UDF-Speicherort, den Ihre Host-App explizit angibt.

WebView2 erstellt standardmäßig eine UDF am Standardspeicherort für die jeweilige Plattform. Dies funktioniert auf einigen Plattformen gut, auf anderen jedoch nicht. Wenn Ihre App bestimmte Anforderungen erfüllt, können Sie einen benutzerdefinierten UDF-Speicherort angeben.

Geeignete benutzerdefinierte UDF-Speicherorte

Wenn Sie einen benutzerdefinierten UDF-Speicherort angeben, sollte er die folgenden Anforderungen erfüllen:

• Der benutzerdefinierte UDF-Speicherort muss über die entsprechenden Lese-/Schreibberechtigungen für die WebView2-App-Runtime verfügen.

• Vermeiden Sie das Speichern von Benutzereinstellungen auf einem Netzlaufwerk. Dies kann zu Verlangsamungen, Abstürzen oder Datenverlust führen.

Welche Art von Daten in der UDF gespeichert wird

WebView2-Apps verwenden Benutzerdatenordner (UDFs), um Browserdaten wie Cookies, Berechtigungen und zwischengespeicherte Ressourcen zu speichern.

Die oben genannten Datentypen werden in der CoreWebView2BrowsingDataKinds-Enumeration als Enumerationsmember aufgeführt.

Wie und wann die UDF erstellt wird

Der Benutzerdatenordner (User Data Folder, UDF) wird für Ihre WebView2-Host-App vom WebView2-Steuerelement erstellt.

Die UDF wird am Standardmäßigen UDF-Speicherort für die Plattform erstellt, oder wenn Ihre Host-App einen benutzerdefinierten UDF-Speicherort angibt, wird die UDF am benutzerdefinierten UDF-Speicherort erstellt.

Die UDF wird beim Start der WebView2-Host-App erstellt, wenn die UDF nicht vorhanden ist.

Wie viele UDFs werden erstellt?

Jede instance eines WebView2-Steuerelements ist einem Benutzerdatenordner (UDF) zugeordnet.

Jede WebView2-Sitzung muss über eine UDF verfügen. Pro WebView2-Sitzung ist nur eine aktive UDF vorhanden.

Es gibt mindestens eine UDF pro App WebView2-Sitzung. Es ist möglich, dass Ihre Host-App sie überlappt, indem Sie einen benutzerdefinierten UDF-Speicherort angeben. Alternativ können Sie eine UDF pro Computer verwenden. Dies hängt davon ab, wie Ihre Host-App die UDF erstellt.

Eine UDF kann entweder pro Benutzer sein, wenn die App pro Benutzer installiert wurde. Wenn die Host-App pro Benutzer installiert wird, ist jede UDF für einen Benutzer eindeutig, sofern nicht anders angegeben.

Verschieben der UDF

So verschieben Sie einen Benutzerdatenordner (UDF):

1. Beenden Sie alle WebView2-Sitzungen.

2. Starten Sie eine neue WebView2-Host-App-Sitzung, und geben Sie einen neuen benutzerdefinierten UDF-Speicherort an.

Der UDF-Standardspeicherort

Der Standardspeicherort für Benutzerdatenordner (User Data Folder, UDF) variiert je nach Plattform.

Angeben eines benutzerdefinierten UDF-Speicherorts

Die Angabe eines benutzerdefinierten Speicherorts für Benutzerdatenordner (User Data Folder, UDF) variiert je nach Plattform.

std::wstring m_userDataFolder;
m_userDataFolder = L"C:\\MyAppUserDataFolder";
auto options = Microsoft::WRL::Make<CoreWebView2ExperimentalEnvironmentOptions>();

HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
    NULL, m_userDataFolder.c_str(), options.Get(),
    Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
        this, &AppWindow::OnCreateEnvironmentCompleted)
        .Get());

string UserDataFolder;
UserDataFolder = "C:\\MyAppUserDataFolder";
_task = CoreWebView2Environment.CreateAsync(BrowserExecutableFolder, 
                                            UserDataFolder, 
                                            new CoreWebView2EnvironmentOptions(null, Language, null));

string UserDataFolder;
UserDataFolder = "C:\\MyAppUserDataFolder";
_task = CoreWebView2Environment.CreateAsync(BrowserExecutableFolder, 
                                            UserDataFolder, 
                                            new CoreWebView2EnvironmentOptions(null, Language, null));

Abrufen des UDF-Speicherorts

Verwenden Sie UserDataFolder die -Eigenschaft, um herauszufinden, auf welchen Speicherort der Benutzerdatenordner (User Data Folder, UDF) festgelegt wurde. Diese schreibgeschützte Eigenschaft gibt den UDF-Speicherort für die WebView2-App zurück.

Gründe für das Lesen des UDF-Speicherorts:

• Wenn Sie Browserdaten aus dem UDF-Ordner löschen möchten, z. B. am Ende einer Sitzung.

• Wenn Sie die UDF löschen möchten.

auto environment7 = m_webViewEnvironment.try_query<ICoreWebView2Environment7>();
CHECK_FEATURE_RETURN(environment7);
wil::unique_cotaskmem_string userDataFolder;
environment7->get_UserDataFolder(&userDataFolder);

private void OnGetUDFClick(object sender, RoutedEventArgs e)
{
    // This property can be used after WebView2 creation to find the actual location of the User Data Folder
    UserDataFolder.Text = WebView2.CoreWebView2.Environment.UserDataFolder;
}

private void OnGetUDFClick(object sender, RoutedEventArgs e)
{
    // This property can be used after WebView2 creation to find the actual location of the User Data Folder
    UserDataFolder.Text = WebView2.CoreWebView2.Environment.UserDataFolder;
}

Leerraum in der UDF

Anstatt den Benutzerdatenordner (User Data Folder, UDF) zu löschen, löschen Sie die Browserdaten aus der UDF. Löschen Sie beispielsweise Benutzerdaten und den Verlauf, wenn sich ein Benutzer abmeldet.

Weitere Informationen finden Sie unter Löschen von Browserdaten aus dem Benutzerdatenordner.

Behandeln von Fehlermeldungen

Wenn der Benutzerdatenordner (User Data Folder, UDF) nicht über Schreibberechtigungen verfügt, werden möglicherweise die folgenden Fehlermeldungszeichenfolgen zurückgegeben:

• User data folder cannot be created because a file with the same name already exists.
• Unable to create user data folder, Access Denied.

Das obige Gilt unabhängig davon, ob der Speicherort des Benutzerdatenordners der UDF-Standardspeicherort oder ein benutzerdefinierter UDF-Speicherort war.

Wenn nicht genügend Arbeitsspeicher vorhanden ist, die Microsoft Edge-Runtime nicht gestartet werden kann oder die WebView2-Runtime nicht gefunden wird, werden möglicherweise Fehlermeldungszeichenfolgen wie die folgende zurückgegeben:

• Microsoft Edge runtime unable to start
• Failed to create WebView2 environment

Fügen Sie Code hinzu, z try/catch . B. Code, um diese Fehler zu behandeln. Diese Fehler sind in der Regel schwerwiegende Fehler, von denen Sie keine Wiederherstellung durchführen können, sodass try/catch die App nicht abstürzt. Anschließend können Sie den Fehler erkennen und die App ordnungsgemäß schließen. Einige Fehler sind nicht behebbar, z Access Denied . B. beim Versuch, einen Benutzerdatenordner zu verwenden, für den Sie nicht über Schreibberechtigungen verfügen.

Fehlermeldungszeichenfolgen werden in einem Dialogfeld angezeigt.

Gibt an, ob Benutzerdatenordner in verschiedenen Szenarien beibehalten werden sollen.

Ihre Host-App steuert die Lebensdauer des Benutzerdatenordners (UDF). Wenn Ihre App Benutzerdaten aus App-Sitzungen erneut verwendet, sollten Sie die UDFs speichern (d. h. nicht löschen).

Wenn Ihre App keine Benutzerdaten aus App-Sitzungen wiederverwendet, können Sie die UDF löschen. Während eine Sitzung ausgeführt wird, ist es jedoch besser, die Clear Browsing-Datenmethoden aufzurufen, anstatt die UDF zu löschen.

Beibehalten von Benutzerdatenordnern, wenn derselbe Benutzer Ihre App wiederholt verwendet und der Webinhalt der App von den Daten des Benutzers abhängt

Löschen Sie in diesem Szenario den Benutzerdatenordner (User Data Folder, UDF) nicht explizit. Die Daten werden beibehalten.

Beibehalten von Benutzerdatenordnern, wenn mehrere Benutzer Ihre App wiederholt verwenden

Wenn mehrere Benutzer Ihre App wiederholt verwenden, sollten Sie für jeden neuen Benutzer einen neuen Benutzerdatenordner (User Data Folder, UDF) erstellen und die UDF jedes Benutzers speichern.

Das WebView2-Steuerelement erstellt für jeden neuen Benutzer eine neue Benutzeroberfläche. Das WebView2-Steuerelement erstellt eine UDF pro Sitzung. Wenn mehrere WebView2-Sitzungen vorhanden sind, erstellt das WebView2-Steuerelement mehrere UDFs. Wenn die Host-App über mehr als ein WebView2-Steuerelement instance verfügt, sollte die Host-App in der Regel alle Instanzen von WebView2 auf dieselbe UDF verweisen.

Jede Host-App mit einem WebView2-Steuerelement instance verfügt über eine eigene Benutzeroberfläche. Ihre Host-App kann jedes UDF-Element auf denselben Ort verweisen.

Wenn Ihre Host-App für mehrere Benutzer bestimmt ist, sollten Sie wahrscheinlich eine UDF pro Benutzer erstellen. Wenn Ihre App pro Benutzer installiert wurde, funktioniert dies.

Wenn Sie zwei Kopien Ihrer Host-App starten, verwenden diese dieselbe UDF.

• Bei Win32-Host-Apps wird die UDF nicht automatisch entfernt.
• Bei .NET-Host-Apps (WPF & WinForms) wird die UDF nicht automatisch entfernt.
• Bei ClickOnce-Host-Apps wird die UDF automatisch entfernt.
• Für WinUI 2-Host-Apps (UWP) wird die UDF nicht automatisch entfernt.
• Bei WinUI 3-Host-Apps wird die UDF nicht automatisch entfernt.

Deinstallieren einer Host-App

Beim Deinstallieren einer WebView2-Host-App wird der standardmäßige Deinstallationsprozess verwendet. Dieser Prozess ist nicht nur für WebView2 verfügbar.

Während der Deinstallation muss Ihr Installationsprogramm möglicherweise alle erstellten UDF sauber. In einigen Fällen empfiehlt es sich möglicherweise, die UDF beizubehalten.

Wenn Sie die Host-App erstellen, ein MSIX-Installationsprogramm erstellen, die Host-App installieren und dann die Host-App ausführen, wird die UDF erstellt. Wenn Sie dann jedoch die Host-App deinstallieren, wird die UDF nicht automatisch sauber (da das Deinstallationsprogramm die Benutzerdaten schützt und beibewahrt). Daher muss ihr Deinstallationsprozess diese Überlegungen berücksichtigen.

In ClickOnce-Apps wird es an einem einzigen Speicherort installiert, und wenn die Sitzung beendet wird, wird die gesamte Struktur gelöscht, sodass die UDF automatisch gelöscht wird. Dies liegt an der Funktionsweise von ClickOnce, nicht an der Funktionsweise von WebView2.

Beibehalten von Benutzerdatenordnern, wenn Ihre App keine wiederholten Benutzer enthält

Erstellen Sie in diesem Szenario einen neuen Benutzerdatenordner (User Data Folder, UDF) für jeden Benutzer, und löschen Sie die vorherige UDF.

Löschen von Benutzerdatenordnern

Ihre Host-App oder das Deinstallationsprogramm kann den Benutzerdatenordner (User Data Folder, UDF) löschen. Möglicherweise müssen Sie UDFs aus einem der folgenden Gründe löschen:

• Wenn Sie eine gepackte Windows Store-App deinstallieren möchten. In diesem Fall löscht Windows UDFs automatisch.

• Wenn Sie den gesamten Browserdatenverlauf sauber möchten. Sehen Sie sich jedoch zuerst die Methoden zum Löschen von Browserdaten an, als einen einfacheren und flexibleren Ansatz.

• Wenn Sie datenbeschädigungen wiederherstellen möchten.

• Wenn Sie vorherige Sitzungsdaten entfernen möchten.

• Wenn Sie den UDF-Speicherort ändern möchten. Wenn Sie den UDF-Speicherort ändern, wird die vorherige UDF nicht automatisch bereinigt.

Beenden der WebView2-Sitzung vor dem Löschen der UDF

Um einen Benutzerdatenordner (User Data Folder, UDF) zu löschen, müssen Sie zuerst die WebView2-Sitzung beenden. Sie können eine UDF nicht löschen, wenn die WebView2-Sitzung derzeit aktiv ist.

Warten Sie, bis Browserprozesse beendet werden, bevor Sie die UDF löschen.

Wenn Dateien nach dem Schließen Der WebView2-Host-App weiterhin verwendet werden, warten Sie, bis browserische Prozesse beendet werden, bevor Sie den Benutzerdatenordner (UDF) löschen.

Dateien in UDFs werden möglicherweise weiterhin verwendet, nachdem die WebView2-App geschlossen wurde. Warten Sie in diesem Fall, bis der Browserprozess und alle untergeordneten Prozesse beendet werden, bevor Sie die UDF löschen. Um Prozesse so zu überwachen, dass sie auf deren Beendigung warten, rufen Sie die Prozess-ID des Browserprozesses mithilfe der BrowserProcessId -Eigenschaft der WebView2-App-instance ab.

Freigeben von Benutzerdatenordnern

WebView2-Steuerelementinstanzen können die gleichen Benutzerdatenordner (USER Data Folders, UDFs) gemeinsam nutzen, um die folgenden Aktionen auszuführen:

• Optimieren Sie Systemressourcen, indem Sie in einem Browserprozess ausführen. Weitere Informationen finden Sie unter Verarbeiten des Modells für WebView2-Apps.

• Verwenden Sie WebView2-Steuerelemente mit unterschiedlichen Profilen, um die Speicherung von Browserdaten wie Cookies, Berechtigungen und zwischengespeicherten Ressourcen unter derselben UDF zu trennen. Weitere Informationen finden Sie unter Unterstützen mehrerer Profile unter einem einzelnen Benutzerdatenordner.

Beachten Sie beim Freigeben von UDFs Folgendes:

• Wenn Sie WebView2-Steuerelemente neu erstellen, um Browserversionen mithilfe von add_NewBrowserVersionAvailable (Win32)-Ereignishandlern (Win32) oder NewBrowserVersionAvailable (.NET)-Ereignissen zu aktualisieren, muss Ihre Host-App sicherstellen, dass alle WebView2-Steuerelemente, die dieselbe UDF verwenden, beendet und geschlossen werden. Verwenden Sie die -Eigenschaft des WebView2-Steuerelements, um die BrowserProcessId Prozess-ID des Browserprozesses abzurufen.

Vermeiden Sie das gleichzeitige Ausführen von zu vielen Ordnern.

Um verschiedene Teile Ihrer App zu isolieren oder wenn die Freigabe von Daten zwischen WebView2-Steuerelementen nicht erforderlich ist, können Sie verschiedene Benutzerdatenordner (USER Data Folders, UDFs) verwenden. Beispielsweise kann eine App aus zwei WebView2-Steuerelementen bestehen, eines zum Anzeigen einer Ankündigung und eines zum Anzeigen von App-Inhalten. Sie können für jedes WebView2-Steuerelement unterschiedliche UDFs verwenden.

Jeder WebView2-Browserprozess beansprucht zusätzlichen Arbeitsspeicher und Speicherplatz. Vermeiden Sie daher die gleichzeitige Ausführung eines WebView2-Steuerelements mit zu vielen verschiedenen UDFs.

Anstelle mehrerer UDFs können Sie mehrere Profile verwenden, um eine Trennung von Browserdaten für verschiedene WebView2-Steuerelemente zu erreichen. Jedes Profil speichert Browserdaten in einem dedizierten Ordner unter derselben freigegebenen UDF. Weitere Informationen finden Sie unter Unterstützen mehrerer Profile unter einem einzelnen Benutzerdatenordner.

Siehe auch

• Unterstützung mehrerer Profile unter einem einzelnen Benutzerdatenordner
• Löschen von Browserdaten aus dem Benutzerdatenordner
• Packen und Bereitstellen in der Dokumentation zur Entwicklung von Windows-Apps (Erstellen von Desktop-Apps für Windows)
• ClickOnce-Sicherheit und -Bereitstellung : Dokumentation zur Visual Studio-Bereitstellung.
• Grundlegendes zu den ClickOnce- und DirectInvoke-Features in Microsoft Edge finden Sie in der Microsoft Edge Enterprise-Dokumentation.