Verwalten von Benutzerdatenordnern

  • Artikel

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:

Begriff Definition
Benutzerdatenordner Ein Ordner, den WebView2 erstellt, um Browserdaten wie Cookies, Berechtigungen und zwischengespeicherte Ressourcen zu speichern.
UDF Der Benutzerdatenordner.
UDF-Speicherort Der Verzeichnispfad des Benutzerdatenordners.
UDF-Standardspeicherort Der Standardverzeichnispfad des Benutzerdatenordners. Der Verzeichnispfad, in dem WebView2 die UDF erstellt, wenn Sie keinen benutzerdefinierten UDF-Speicherort angeben.
Benutzerdefinierter UDF-Speicherort Ein benutzerdefinierter Speicherort für den Benutzerdatenordner. Der Verzeichnispfad, den Ihre WebView2-Host-App angibt, wo WebView2 den Benutzerdatenordner erstellt.

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.

Datentyp Beschreibung
AllDomStorage DOM-Speicherdaten, jetzt und in Zukunft. Diese Browserdatenart enthält FileSystems, IndexedDb, WebSql, CacheStorage.
AllProfile Profildaten, die zurückgesetzt werden sollten, damit sie wie ein neues Profil aussehen. Dadurch werden keine kontobezogenen Daten wie Kennwörter gelöscht, sondern der Zugriff auf kontobezogene Daten wird entfernt, indem der Benutzer abgemeldet wird. Alle Profildaten, jetzt und in zukunft. Dieser Datenart können in Zukunft neue Profildatentypen hinzugefügt werden. Diese Browserdatenart umfasst die Datentypen AllSite, DiskCache, , GeneralAutofillDownloadHistory, PasswordAutosave, BrowsingHistoryund Settings.
AllSite Alle Standortdaten, jetzt und in zukunft. Diese Browserdatenart umfasst die Datentypen AllDomStorage und Cookies. Dieser Datenart können in Zukunft neue Websitedatentypen hinzugefügt werden.
BrowsingHistory Browserverlaufsdaten.
CacheStorage Von der CacheStorage-DOM-API gespeicherte Daten.
Cookies HTTP-Cookies-Daten.
DiskCache Datenträgercache.
DownloadHistory Laden Sie Verlaufsdaten herunter.
FileSystems Dateisystemdaten.
GeneralAutofill Allgemeine Daten zum automatischen Ausfüllen von Formularen. Dies schließt Kennwortinformationen aus und umfasst Informationen wie Namen, Straßen- und E-Mail-Adressen, Telefonnummern und beliebige Eingaben. Enthält Zahlungsdaten.
IndexedDb Von der IndexedDB-DOM-Funktion gespeicherte Daten.
LocalStorage Von der localStorage-DOM-API gespeicherte Daten.
PasswordAutosave Automatisches Speichern von Daten für Kennwörter.
Settings Einstellungsdaten.
WebSql Von der WEB SQL-Datenbank-DOM-API gespeicherte Daten.

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.

Auf dieser Plattform ist der UDF-Standardspeicherort das Verzeichnis, in dem die ausführbare App (.exe) ausgeführt wird. Die Standard-UDF ist der ausführbare Pfad (exe) Ihrer App + .WebView2. Der Dateiname der UDF ist der ausführbare Pfad (exe) Ihrer App + .WebView2.

Wenn Sie z. B. ausgeführt D:\WebView2App\WebView2.exehaben, wird ein UDF-Ordner erstellt: D:\WebView2App\WebView2.exe.WebView2\. Ein weiteres Beispiel: WebView2APISample.exe.WebView2\.

Sollten Sie den Standard- oder benutzerdefinierten UDF-Speicherort verwenden?

In den meisten Fällen sollten Sie einen benutzerdefinierten UDF-Speicherort angeben, anstatt den UDF-Standardspeicherort zu verwenden. Dadurch wird sichergestellt, dass das WebView2-Steuerelement über Schreibzugriff verfügt, sodass das WebView2-Steuerelement die UDF erstellen und dann in sie schreiben kann. Weitere Informationen finden Sie weiter unten im Abschnitt "Angeben eines benutzerdefinierten UDF-Speicherorts".

Verpackung:

Win32 MSIX-Paketerstellung ist eine eigenständige .exe.

Angeben eines benutzerdefinierten UDF-Speicherorts

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

Auf dieser Plattform sollten Sie in den meisten Fällen einen benutzerdefinierten UDF-Speicherort angeben, anstatt den UDF-Standardspeicherort zu verwenden. Dadurch wird sichergestellt, dass das WebView2-Steuerelement über Schreibzugriff verfügt, sodass das WebView2-Steuerelement die UDF erstellen und dann in sie schreiben kann.

Sie sollten denselben Ordner angeben, in dem alle anderen App-Daten gespeichert sind.

Angeben eines benutzerdefinierten UDF-Speicherorts:

Verwenden Sie ICoreWebView2Environment und den userDataFolder Parameter. Verwenden Sie jedoch den folgenden Code, der aus dem WebView2Samples Repository stammt.

Beispielcode:

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());

Beispielcode finden Sie in der Win32-geeigneten .cpp Datei in .cs der Nähe des WebView2Samples-Repositorys > WebView2APISample.

Wo Browserdaten in der UDF gespeichert werden:

Nach dem Erstellen der Sitzung und der UDF werden Browserdaten aus Ihrem WebView2-Steuerelement in einem Unterordner von userDataFoldergespeichert.

Gründe für die Verwendung eines benutzerdefinierten UDF-Speicherorts auf dieser Plattform:

Wenn Sie keinen benutzerdefinierten UDF-Speicherort angeben, kann der Standardspeicherort bei Verwendung von Installationsprogrammtechnologien zu einem Laufzeitfehler führen, da die Installationstechnologien die App und damit die UDF in einem geschützten Bereich des Dateisystems platzieren, in dem WebView2 die UDF nicht erstellen kann, sodass die UDF-Erstellung in der Regel fehlschlägt. WebView2 löst einen Fehler aus, um Ihre Host-App darüber zu informieren, dass die UDF nicht an diesem Speicherort erstellt werden kann.

Wenn die Host-App von einem Speicherort aus ausgeführt wird, für den der Benutzer keinen Schreibzugriff hat, kann WebView2 die UDF nicht erstellen, und Sie erhalten beim Starten von WebView2 einen Laufzeitfehler.

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.

Verwenden Sie den Win32-ICoreWebView2Environment7.get_UserDataFolder-Eigenschafts-Getter. Diese API-Referenzseite enthält Beispielcode, der zeigt, wie die UserDataFolder Eigenschaft gelesen wird.

Beispielcode:

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

Beispiele für das Lesen der UserDataFolder Eigenschaft finden Sie in den Win32-Beispielen im WebView2Samples-Repository.

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:

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