Gérer les dossiers de données utilisateur

  • Article

Le dossier de données utilisateur (UDF) est un dossier stocké sur l’ordinateur de l’utilisateur, qui contient des données relatives à l’application hôte et à WebView2. Les applications WebView2 utilisent des dossiers de données utilisateur pour stocker les données du navigateur, telles que les cookies, les autorisations et les ressources mises en cache.

Terminologie:

Terme Définition
dossier de données utilisateur Dossier créé par WebView2 pour stocker les données du navigateur, telles que les cookies, les autorisations et les ressources mises en cache.
UDF Dossier de données utilisateur.
Emplacement de la fonction définie par l’utilisateur Chemin d’accès au répertoire du dossier de données utilisateur.
Emplacement de la fonction définie par l’utilisateur par défaut Chemin d’accès au répertoire par défaut du dossier de données utilisateur. Chemin d’accès au répertoire où WebView2 crée la fonction définie par l’utilisateur si vous ne spécifiez pas d’emplacement UDF personnalisé.
Emplacement UDF personnalisé Emplacement personnalisé pour le dossier de données utilisateur. Chemin d’accès au répertoire que votre application hôte WebView2 spécifie où WebView2 créera le dossier de données utilisateur.

WebView2 crée la fonction définie par l’utilisateur à l’emplacement par défaut de la plateforme ou à l’emplacement UDF personnalisé spécifié explicitement par votre application hôte.

Par défaut, WebView2 crée une fonction définie par l’utilisateur à l’emplacement par défaut de la plateforme particulière. Cela fonctionne bien sur certaines plateformes, mais pas sur d’autres. Si votre application a des besoins spécifiques, vous pouvez spécifier un emplacement UDF personnalisé.

Emplacements UDF personnalisés appropriés

Si vous spécifiez un emplacement UDF personnalisé, il doit répondre aux exigences suivantes :

  • L’emplacement UDF personnalisé doit disposer des autorisations de lecture/écriture appropriées pour le runtime de l’application WebView2.

  • Évitez de stocker les paramètres utilisateur sur un lecteur réseau. Cela peut entraîner des ralentissements, des plantages ou une perte de données.

Quel type de données est stocké dans la fonction définie par l’utilisateur

Les applications WebView2 utilisent des dossiers de données utilisateur (UDF) pour stocker les données du navigateur, telles que les cookies, les autorisations et les ressources mises en cache.

DataType Description
AllDomStorage Données de stockage DOM, maintenant et à venir. Ce type de données de FileSystemsnavigation comprend , IndexedDb, WebSqlet CacheStorage.
AllProfile Données de profil qui doivent être effacées pour qu’elles ressemblent à un nouveau profil. Cela ne supprime pas les données délimitées au compte, telles que les mots de passe, mais supprime l’accès aux données délimitées au compte en déconnectez l’utilisateur. Toutes les données de profil, maintenant et à venir. De nouveaux types de données de profil peuvent être ajoutés à ce type de données à l’avenir. Ce type de données de navigation inclut les types de AllSitedonnées , DiskCache, DownloadHistoryGeneralAutofill, PasswordAutosave, , BrowsingHistoryet Settings.
AllSite Toutes les données de site, maintenant et à venir. Ce type de données de navigation inclut les types de AllDomStorage données et Cookies. De nouveaux types de données de site peuvent être ajoutés à ce type de données à l’avenir.
BrowsingHistory Données d’historique de navigation.
CacheStorage Données stockées par l’API DOM CacheStorage.
Cookies Données des cookies HTTP.
DiskCache Cache de disque.
DownloadHistory Télécharger les données d’historique.
FileSystems Données des systèmes de fichiers.
GeneralAutofill Données générales de formulaire de remplissage automatique. Cela exclut les informations de mot de passe et inclut des informations telles que les noms, les adresses postales et de messagerie, les numéros de téléphone et les entrées arbitraires. Inclut les données de paiement.
IndexedDb Données stockées par la fonctionnalité DOM IndexedDB.
LocalStorage Données stockées par l’API DOM localStorage.
PasswordAutosave Données d’enregistrement automatique du mot de passe.
Settings Données de paramètres.
WebSql Données stockées par l’API DOM de base de données WEB SQL.

Les types de données ci-dessus sont répertoriés en tant que membres enum dans l’énumération CoreWebView2BrowsingDataKinds.

Comment et quand la fonction définie par l’utilisateur est créée

Le dossier de données utilisateur (UDF) est créé pour votre application hôte WebView2 par le contrôle WebView2.

La fonction UDF est créée dans l’emplacement par défaut de la fonction définie par l’utilisateur pour la plateforme, ou si votre application hôte spécifie un emplacement UDF personnalisé, la fonction définie par l’utilisateur est créée dans l’emplacement UDF personnalisé.

La fonction définie par l’utilisateur est créée au démarrage de l’application hôte WebView2, si la fonction définie par l’utilisateur n’existe pas.

Combien de fonctions définies par l’utilisateur sont créées ?

Chaque instance d’un contrôle WebView2 est associé à un dossier de données utilisateur (UDF).

Chaque session WebView2 doit avoir une fonction définie par l’utilisateur. Il n’y a qu’une seule fonction UDF active par session WebView2.

Il existe au moins une fonction définie par application WebView2 session. Il est possible que votre application hôte les chevauche en spécifiant un emplacement UDF personnalisé. Vous pouvez également avoir une fonction définie par l’utilisateur par machine. Cela dépend de la façon dont votre application hôte configure la fonction définie par l’utilisateur.

Une fonction définie par l’utilisateur peut être définie par utilisateur, si l’application a été installée par utilisateur. Si l’application hôte est installée par utilisateur, chaque fonction définie par l’utilisateur est unique, si elle n’est pas spécifiée autrement.

Comment déplacer la fonction définie par l’utilisateur

Pour déplacer un dossier de données utilisateur (UDF) :

  1. Arrêtez toutes les sessions WebView2.

  2. Démarrez une nouvelle session d’application hôte WebView2, en spécifiant un nouvel emplacement UDF personnalisé.

Emplacement par défaut de la fonction définie par l’utilisateur

L’emplacement par défaut du dossier de données utilisateur (UDF) varie selon la plateforme.

Sur cette plateforme, l’emplacement par défaut de la fonction définie par l’utilisateur est le répertoire dans lequel l’exécutable de l’application (.exe) s’exécute. La fonction définie par défaut est le chemin d’accès exécutable (exe) de votre application + .WebView2. Le nom de fichier de la fonction définie par l’utilisateur est le chemin d’accès exécutable (exe) de votre application + .WebView2.

Par exemple, si vous avez exécuté D:\WebView2App\WebView2.exe, un dossier UDF est créé : D:\WebView2App\WebView2.exe.WebView2\. Autre exemple : WebView2APISample.exe.WebView2\.

Devez-vous utiliser l’emplacement par défaut ou personnalisé de la fonction définie par l’utilisateur ?

Dans la plupart des cas, vous devez spécifier un emplacement UDF personnalisé, plutôt que d’utiliser l’emplacement par défaut de la fonction définie par l’utilisateur. Cela garantit que le contrôle WebView2 dispose d’un accès en écriture afin que le contrôle WebView2 soit en mesure de créer la fonction définie par l’utilisateur, puis d’y écrire. Consultez la section « Spécification d’un emplacement UDF personnalisé » ci-dessous.

Emballage:

L’empaquetage MSIX Win32 est un package autonome .exe.

Spécification d’un emplacement UDF personnalisé

La spécification d’un emplacement de dossier de données utilisateur (UDF) personnalisé varie selon la plateforme.

Sur cette plateforme, dans la plupart des cas, vous devez spécifier un emplacement UDF personnalisé, plutôt que d’utiliser l’emplacement par défaut de la fonction définie par l’utilisateur. Cela garantit que le contrôle WebView2 dispose d’un accès en écriture afin que le contrôle WebView2 soit en mesure de créer la fonction définie par l’utilisateur, puis d’y écrire.

Vous devez spécifier le même dossier que celui où sont stockées toutes les autres données d’application.

Comment spécifier un emplacement UDF personnalisé :

Utilisez ICoreWebView2Environment et le userDataFolder paramètre . Mais utilisez le code ci-dessous, qui provient du WebView2Samples référentiel.

Exemple de code :

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

Pour obtenir un exemple de code, consultez le fichier Win32 approprié, .cpp ou .cs fichier, près du référentiel > WebView2Samples WebView2APISample.

Où les données du navigateur sont stockées dans la fonction définie par l’utilisateur :

Après la création de la session et de la fonction définie par l’utilisateur, les données de navigateur de votre contrôle WebView2 sont stockées dans un sous-dossier de userDataFolder.

Pourquoi vous devez utiliser un emplacement UDF personnalisé sur cette plateforme :

Si vous ne spécifiez pas d’emplacement UDF personnalisé, l’emplacement par défaut peut produire un échec d’exécution, si vous utilisez des technologies d’installation, car les technologies du programme d’installation placent l’application et donc la fonction UDF dans une zone protégée du système de fichiers, où WebView2 n’est pas en mesure de créer la fonction définie par l’utilisateur, et par conséquent, la création de la fonction UDF échoue généralement. WebView2 génère une erreur pour informer votre application hôte que la fonction définie par l’utilisateur ne peut pas être créée à cet emplacement.

Si l’application hôte s’exécute à partir d’un emplacement auquel l’utilisateur n’a pas accès en écriture, WebView2 ne peut pas créer la fonction définie par l’utilisateur et vous recevrez une erreur d’exécution au démarrage de WebView2.

Récupération de l’emplacement de la fonction définie par l’utilisateur

Pour connaître l’emplacement du dossier de données utilisateur (UDF), utilisez la UserDataFolder propriété . Cette propriété en lecture seule renvoie l’emplacement de la fonction définie par l’utilisateur pour l’application WebView2.

Raisons pour lesquelles vous souhaiterez peut-être lire l’emplacement de la fonction définie par l’utilisateur :

  • Si vous souhaitez effacer les données de navigation du dossier UDF, par exemple à la fin d’une session.

  • Si vous souhaitez supprimer la fonction définie par l’utilisateur.

Utilisez la propriété win32 ICoreWebView2Environment7.get_UserDataFolder getter. Cette page De référence d’API contient un exemple de code montrant comment lire la UserDataFolder propriété.

Exemple de code :

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

Pour obtenir des exemples de lecture de la UserDataFolder propriété, consultez les exemples Win32 dans le référentiel WebView2Samples.

Suppression de l’espace dans la fonction définie par l’utilisateur

Au lieu de supprimer le dossier de données utilisateur (UDF), effacez les données de navigation de la fonction définie par l’utilisateur. Par exemple, effacez les données et l’historique utilisateur lorsqu’un utilisateur se déconnecte.

Consultez Effacer les données de navigation du dossier des données utilisateur.

Gestion des messages d’erreur

Si le dossier de données utilisateur (UDF) ne dispose pas des autorisations d’écriture, les chaînes de message d’erreur suivantes peuvent être retournées :

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

La valeur ci-dessus est vraie, que l’emplacement du dossier de données utilisateur soit l’emplacement par défaut de la fonction définie par l’utilisateur ou un emplacement UDF personnalisé.

Si la mémoire est insuffisante, si le runtime Microsoft Edge ne parvient pas à démarrer ou si le runtime WebView2 est introuvable, des chaînes de message d’erreur similaires à ce qui suit peuvent être retournées :

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

Ajoutez du code, tel que try/catch du code, pour gérer ces erreurs. Ces erreurs ont tendance à être des erreurs irrécupérables dont vous ne pouvez pas récupérer, ce try/catch qui empêche l’application de se bloquer. Vous serez alors en mesure de détecter l’échec et de fermer l’application correctement. Certaines erreurs sont irrécupérables, telles que Access Denied lorsque vous essayez d’utiliser un dossier de données utilisateur pour lequel vous ne disposez pas des autorisations d’écriture.

Les chaînes de message d’erreur s’affichent dans une boîte de dialogue.

Indique s’il faut conserver les dossiers de données utilisateur dans différents scénarios

Votre application hôte contrôle la durée de vie du dossier de données utilisateur (UDF). Si votre application réutilisent les données utilisateur des sessions d’application, envisagez d’enregistrer (c’est-à-dire de ne pas supprimer) les fonctions définies par l’utilisateur.

Si votre application ne réutilise pas les données utilisateur des sessions d’application, vous pouvez supprimer la fonction définie par l’utilisateur. Toutefois, pendant qu’une session est en cours d’exécution, il est préférable d’appeler les méthodes de données de navigation claires au lieu de supprimer la fonction définie par l’utilisateur.

Persistance des dossiers de données utilisateur si le même utilisateur utilise votre application à plusieurs reprises et que le contenu web de l’application s’appuie sur les données de l’utilisateur

Dans ce scénario, ne supprimez pas explicitement le dossier de données utilisateur (UDF) ; conserver les données.

Conservation des dossiers de données utilisateur si plusieurs utilisateurs utilisent votre application à plusieurs reprises

Si plusieurs utilisateurs utilisent votre application à plusieurs reprises, vous devez créer un dossier de données utilisateur (UDF) pour chaque nouvel utilisateur et enregistrer la fonction définie par l’utilisateur.

Le contrôle WebView2 crée une fonction définie par l’utilisateur pour chaque nouvel utilisateur. Le contrôle WebView2 crée une fonction définie par l’utilisateur par session. S’il existe plusieurs sessions WebView2, le contrôle WebView2 crée plusieurs fonctions définies par l’utilisateur. En règle générale, si l’application hôte a plusieurs instance de contrôle WebView2, l’application hôte doit pointer toutes les instances de WebView2 vers la même fonction définie par l’utilisateur.

Chaque application hôte disposant d’un contrôle WebView2 instance aura sa propre fonction définie par l’utilisateur. Votre application hôte peut avoir chaque fonction définie par l’utilisateur vers le même emplacement.

Si votre application hôte est destinée à plusieurs utilisateurs, vous devez probablement créer une fonction définie par utilisateur. Si votre application a été installée par utilisateur, c’est ainsi qu’elle fonctionne.

Si vous lancez deux copies de votre application hôte, elles utilisent la même fonction définie par l’utilisateur.

  • Pour les applications hôtes Win32, la fonction définie par l’utilisateur n’est pas automatiquement supprimée.
  • Pour les applications hôtes .NET (WPF & WinForms), la fonction définie par l’utilisateur n’est pas automatiquement supprimée.
  • Pour les applications hôtes ClickOnce, la fonction définie par l’utilisateur est automatiquement supprimée.
  • Pour les applications hôtes WinUI 2 (UWP), la fonction définie par l’utilisateur n’est pas automatiquement supprimée.
  • Pour les applications hôtes WinUI 3, la fonction définie par l’utilisateur n’est pas automatiquement supprimée.

Désinstallation d’une application hôte

La désinstallation d’une application hôte WebView2 utilise le processus de désinstallation standard ; ce processus n’est pas propre à WebView2.

Lors de la désinstallation, votre programme d’installation peut avoir besoin d’propre toute fonction définie par l’utilisateur créée. Dans certains cas, vous souhaiterez peut-être conserver la fonction définie par l’utilisateur.

Si vous créez l’application hôte, créez un programme d’installation MSIX, installez l’application hôte, puis exécutez l’application hôte, cela crée la fonction définie par l’utilisateur. Toutefois, si vous désinstallez l’application hôte, cela ne propre pas automatiquement la fonction définie par l’utilisateur (car le programme de désinstallation protège et conserve les données utilisateur). Votre processus de désinstallation doit donc tenir compte de cette considération.

Dans les applications ClickOnce, il s’installe dans un emplacement unique et, lorsque la session se termine, il supprime l’arborescence entière, de sorte que la fonction définie par l’utilisateur est automatiquement supprimée. Cela est dû au fonctionnement de ClickOnce, et non à la façon dont WebView2 fonctionne.

Conservation des dossiers de données utilisateur si votre application n’a pas d’utilisateurs récurrents

Dans ce scénario, créez un dossier de données utilisateur (UDF) pour chaque utilisateur et supprimez la fonction définie par l’utilisateur précédente.

Suppression de dossiers de données utilisateur

Votre application hôte ou le programme de désinstallation peut supprimer le dossier de données utilisateur (UDF). Vous devrez peut-être supprimer des fonctions définies par l’utilisateur pour l’une des raisons suivantes :

  • Si vous souhaitez désinstaller une application du Windows Store empaquetée. Dans ce cas, Windows supprime automatiquement les fonctions définies par l’utilisateur.

  • Si vous souhaitez propre tout l’historique des données de navigation. Toutefois, consultez d’abord les méthodes de navigation claire des données , comme une approche plus facile et plus flexible.

  • Si vous souhaitez récupérer après une altération des données.

  • Si vous souhaitez supprimer les données de session précédentes.

  • Si vous souhaitez modifier l’emplacement de la fonction définie par l’utilisateur. Si vous modifiez l’emplacement de la fonction définie par l’utilisateur, la fonction définie par l’utilisateur précédente n’est pas automatiquement nettoyée.

Mettre fin à la session WebView2 avant de supprimer la fonction définie par l’utilisateur

Pour supprimer un dossier de données utilisateur (UDF), vous devez d’abord mettre fin à la session WebView2. Vous ne pouvez pas supprimer une fonction définie par l’utilisateur si la session WebView2 est actuellement active.

Attendez que les processus du navigateur se terminent avant de supprimer la fonction définie par l’utilisateur

Si les fichiers sont toujours utilisés après la fermeture de votre application hôte WebView2, attendez que les processus du navigateur se terminent avant de supprimer le dossier de données utilisateur (UDF).

Les fichiers dans les fonctions définies par l’utilisateur peuvent toujours être utilisés après la fermeture de l’application WebView2. Dans ce cas, attendez que le processus du navigateur et tous les processus enfants se terminent avant de supprimer la fonction définie par l’utilisateur. Pour surveiller les processus et attendre qu’ils se terminent, récupérez l’ID de processus du processus de navigateur à l’aide de la BrowserProcessId propriété de l’application WebView2 instance.

Partage de dossiers de données utilisateur

Les instances de contrôle WebView2 peuvent partager les mêmes dossiers de données utilisateur (UDF), pour effectuer les opérations suivantes :

Tenez compte des points suivants lors du partage des fonctions définies par l’utilisateur :

  • Lorsque vous recréez des contrôles WebView2 pour mettre à jour les versions du navigateur à l’aide de gestionnaires d’événements add_NewBrowserVersionAvailable (Win32) ou d’événements NewBrowserVersionAvailable (.NET), votre application hôte doit s’assurer que les processus du navigateur quittent et ferment tous les contrôles WebView2 qui partagent la même fonction définie par l’utilisateur. Pour récupérer l’ID de processus du processus du navigateur, utilisez la BrowserProcessId propriété du contrôle WebView2.

Éviter d’exécuter trop de dossiers à la fois

Pour isoler différentes parties de votre application, ou lorsque le partage de données entre les contrôles WebView2 n’est pas nécessaire, vous pouvez utiliser différents dossiers de données utilisateur (UDF). Par exemple, une application peut se composer de deux contrôles WebView2, l’un pour afficher une publication et l’autre pour afficher le contenu de l’application. Vous pouvez utiliser différentes fonctions définies par l’utilisateur pour chaque contrôle WebView2.

Chaque processus de navigateur WebView2 consomme de la mémoire et de l’espace disque supplémentaires. Par conséquent, évitez d’exécuter un contrôle WebView2 avec trop de fonctions définies par l’utilisateur en même temps.

Au lieu de plusieurs fonctions définies par l’utilisateur, vous pouvez utiliser plusieurs profils pour assurer la séparation du stockage des données du navigateur pour différents contrôles WebView2. Chaque profil enregistre les données du navigateur dans un dossier dédié sous la même fonction UDF partagée. Consultez Prise en charge de plusieurs profils dans un dossier de données utilisateur unique.

Voir aussi