Administrar carpetas de datos de usuario

  • Artículo

La carpeta de datos de usuario (UDF) es una carpeta almacenada en el equipo del usuario, que contiene datos relacionados con la aplicación host y WebView2. Las aplicaciones WebView2 usan carpetas de datos de usuario para almacenar datos del explorador, como cookies, permisos y recursos almacenados en caché.

Terminología:

Término Definición
carpeta de datos de usuario Carpeta que WebView2 crea para almacenar datos del explorador, como cookies, permisos y recursos almacenados en caché.
UDF Carpeta de datos de usuario.
Ubicación de UDF Ruta de acceso del directorio de la carpeta de datos de usuario.
ubicación de UDF predeterminada Ruta de acceso de directorio predeterminada de la carpeta de datos de usuario. Ruta de acceso del directorio donde WebView2 crea la UDF si no especifica una ubicación udf personalizada.
ubicación de UDF personalizada Una ubicación personalizada para la carpeta de datos del usuario. La ruta de acceso del directorio que la aplicación host de WebView2 especifica dónde creará WebView2 la carpeta de datos de usuario.

WebView2 crea la UDF en la ubicación predeterminada de la plataforma o en la ubicación udf personalizada que especifica explícitamente la aplicación host.

De forma predeterminada, WebView2 crea una UDF en la ubicación predeterminada para la plataforma determinada. Esto funciona bien en algunas plataformas, pero no en otras. Si la aplicación tiene necesidades específicas, puede especificar una ubicación udf personalizada.

Ubicaciones udf personalizadas adecuadas

Si especifica una ubicación udf personalizada, debe cumplir los siguientes requisitos:

  • La ubicación de UDF personalizada debe tener los permisos de lectura y escritura adecuados para el entorno de ejecución de la aplicación WebView2.

  • Evite almacenar la configuración de usuario en una unidad de red. Esto puede dar lugar a ralentizaciones, bloqueos o pérdida de datos.

Qué tipo de datos se almacenan en la UDF

Las aplicaciones WebView2 usan carpetas de datos de usuario (UDF) para almacenar datos del explorador, como cookies, permisos y recursos almacenados en caché.

Tipo de datos Descripción
AllDomStorage Datos de almacenamiento DOM, ahora y en el futuro. Este tipo de datos de FileSystemsexploración incluye , IndexedDb, WebSql, CacheStorage.
AllProfile Datos de perfil que se deben borrar para que parezcan un perfil nuevo. Esto no elimina los datos con ámbito de cuenta, como las contraseñas, sino que quitará el acceso a los datos con ámbito de cuenta mediante la firma del usuario. Todos los datos de perfil, ahora y el futuro. Los nuevos tipos de datos de perfil se pueden agregar a este tipo de datos en el futuro. Este tipo de datos de exploración incluye los tipos AllSitede datos , DiskCache, DownloadHistory, GeneralAutofill, PasswordAutosave, BrowsingHistoryy Settings.
AllSite Todos los datos del sitio, ahora y el futuro. Este tipo de datos de exploración incluye los tipos de AllDomStorage datos y Cookies. Los nuevos tipos de datos de sitio se pueden agregar a este tipo de datos en el futuro.
BrowsingHistory Datos del historial de exploración.
CacheStorage Datos almacenados por la API DOM CacheStorage.
Cookies Datos de cookies HTTP.
DiskCache Memoria caché de disco.
DownloadHistory Descargue los datos del historial.
FileSystems Datos de sistemas de archivos.
GeneralAutofill Datos generales del formulario de autorrellenar. Esto excluye la información de contraseña e incluye información como nombres, direcciones de calle y correo electrónico, números de teléfono y entradas arbitrarias. Incluye datos de pago.
IndexedDb Datos almacenados por la característica INDEXEDDB DOM.
LocalStorage Datos almacenados por la API dom localStorage.
PasswordAutosave Datos de guardado automático de contraseñas.
Settings Datos de configuración.
WebSql Datos almacenados por la API DOM de base de datos Web SQL.

Los tipos de datos anteriores se enumeran como miembros de enumeración en la enumeración CoreWebView2BrowsingDataKinds.

Cómo y cuándo se crea la UDF

El control WebView2 crea la carpeta de datos de usuario (UDF) para la aplicación host WebView2.

La UDF se crea en la ubicación de UDF predeterminada para la plataforma o, si la aplicación host especifica una ubicación udf personalizada, la UDF se crea en la ubicación de UDF personalizada.

La UDF se crea al iniciar la aplicación host WebView2, si la UDF no existe.

¿Cuántas UDF se crean?

Cada instancia de un control WebView2 está asociada a una carpeta de datos de usuario (UDF).

Cada sesión de WebView2 debe tener una UDF. Solo hay 1 UDF activa por sesión de WebView2.

Hay al menos una UDF por cada sesión webView2 de la aplicación. Es posible que la aplicación host se superponga especificando una ubicación UDF personalizada. O bien, puede tener una UDF por máquina. Esto depende de cómo la aplicación host configure la UDF.

Una UDF puede ser por usuario, si la aplicación se instaló por usuario. Si la aplicación host está instalada por usuario, cada UDF es única para un usuario, si no se especifica de otro modo.

Cómo mover la UDF

Para mover una carpeta de datos de usuario (UDF):

  1. Cierre todas las sesiones de WebView2.

  2. Inicie una nueva sesión de aplicación host de WebView2, especificando una nueva ubicación udf personalizada.

Ubicación de UDF predeterminada

La ubicación predeterminada de la carpeta de datos de usuario (UDF) varía según la plataforma.

En esta plataforma, la ubicación de UDF predeterminada es el directorio en el que se ejecuta el ejecutable de la aplicación (.exe). La UDF predeterminada es la ruta de acceso ejecutable (exe) de la aplicación y .WebView2. El nombre de archivo de la UDF es la ruta de acceso ejecutable (exe) de la aplicación y .WebView2.

Por ejemplo, si ejecuta D:\WebView2App\WebView2.exe, se crearía una carpeta UDF: D:\WebView2App\WebView2.exe.WebView2\. Como otro ejemplo: WebView2APISample.exe.WebView2\.

¿Debe usar la ubicación udf predeterminada o personalizada?

En la mayoría de los casos, debe especificar una ubicación udf personalizada, en lugar de usar la ubicación de UDF predeterminada. Esto garantiza que el control WebView2 tenga acceso de escritura para que el control WebView2 pueda crear la UDF y, a continuación, escribir en él. Consulte la sección "Especificación de una ubicación udf personalizada" a continuación.

Empaquetado:

El empaquetado msix de Win32 es un archivo independiente .exe.

Especificación de una ubicación udf personalizada

Cómo especificar una ubicación de carpeta de datos de usuario (UDF) personalizada varía según la plataforma.

En esta plataforma, en la mayoría de los casos, debe especificar una ubicación udf personalizada, en lugar de usar la ubicación de UDF predeterminada. Esto garantiza que el control WebView2 tenga acceso de escritura para que el control WebView2 pueda crear la UDF y, a continuación, escribir en él.

Debe especificar la misma carpeta donde se almacenan todos los demás datos de la aplicación.

Cómo especificar una ubicación udf personalizada:

Use ICoreWebView2Environment y el userDataFolder parámetro . Pero use el código siguiente, que es del WebView2Samples repositorio.

Código de ejemplo:

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

Para obtener código de ejemplo, vea el archivo o .cs adecuado para .cpp Win32, cerca del repositorio > WebView2Samples WebView2APISample.

Dónde se almacenan los datos del explorador dentro de la UDF:

Después de crear la sesión y la UDF, los datos del explorador del control WebView2 se almacenan en una subcarpeta de userDataFolder.

Por qué debe usar una ubicación udf personalizada en esta plataforma:

Si no especifica una ubicación udf personalizada, la ubicación predeterminada puede producir un error en tiempo de ejecución, si se usan tecnologías de instalador, ya que las tecnologías del instalador colocan la aplicación y, por tanto, la UDF en un área protegida del sistema de archivos, donde WebView2 no puede crear la UDF y, por tanto, la creación de UDF normalmente producirá un error. WebView2 producirá un error para que la aplicación host sepa que la UDF no se puede crear en esa ubicación.

Si la aplicación host se ejecuta desde una ubicación a la que el usuario no tiene acceso de escritura, WebView2 no puede crear la UDF y recibirá un error en tiempo de ejecución durante el inicio de WebView2.

Recuperación de la ubicación de la UDF

Para averiguar en qué se estableció la ubicación de la carpeta de datos de usuario (UDF), use la UserDataFolder propiedad . Esta propiedad de solo lectura devuelve la ubicación udf de la aplicación WebView2.

Motivos por los que podría querer leer la ubicación de udf:

  • Si desea borrar los datos de exploración de la carpeta UDF, como al final de una sesión.

  • Si desea eliminar la UDF.

Use el captador de la propiedad ICoreWebView2Environment7.get_UserDataFolder Win32. Esa página Referencia de API contiene código de ejemplo que muestra cómo leer la UserDataFolder propiedad.

Código de ejemplo:

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

Para obtener ejemplos de cómo leer la UserDataFolder propiedad, consulte los ejemplos de Win32 en el repositorio WebView2Samples.

Borrar espacio en la UDF

En lugar de eliminar la carpeta de datos de usuario (UDF), borre los datos de exploración de la UDF. Por ejemplo, borre los datos de usuario y el historial cuando un usuario cierre la sesión.

Consulte Borrar datos de exploración de la carpeta de datos de usuario.

Control de mensajes de error

Si la carpeta de datos de usuario (UDF) no tiene permisos de escritura, se pueden devolver las siguientes cadenas de mensaje de error:

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

Lo anterior es true independientemente de si la ubicación de la carpeta de datos de usuario era la ubicación predeterminada de UDF o una ubicación UDF personalizada.

Si no hay memoria insuficiente o el entorno de ejecución de Microsoft Edge no se puede iniciar o no se encuentra el entorno de ejecución webView2, se pueden devolver cadenas de mensaje de error similares a las siguientes:

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

Agregue código, como try/catch código, para controlar estos errores. Estos errores tienden a ser errores irrecuperables de los que no se puede recuperar, por lo que try/catch evitará que la aplicación se bloquee. A continuación, podrá detectar el error y cerrar la aplicación correctamente. Algunos errores son irrecuperables, como Access Denied al intentar usar una carpeta de datos de usuario a la que no tiene permisos de escritura.

Las cadenas de mensaje de error se muestran en un cuadro de diálogo.

Si se deben conservar carpetas de datos de usuario en varios escenarios

La aplicación host controla la duración de la carpeta de datos de usuario (UDF). Si la aplicación vuelve a usar los datos de usuario de las sesiones de aplicación, considere la posibilidad de guardar (es decir, no eliminar) las UDF.

Si la aplicación no reutiliza los datos de usuario de las sesiones de la aplicación, puede eliminar la UDF. Sin embargo, mientras se ejecuta una sesión, es mejor llamar a los métodos de datos de exploración sin cifrar en lugar de eliminar la UDF.

Conservar carpetas de datos de usuario si el mismo usuario usa la aplicación repetidamente y el contenido web de la aplicación se basa en los datos del usuario.

En este escenario, no elimine explícitamente la carpeta de datos de usuario (UDF); conservar los datos.

Conservar carpetas de datos de usuario si varios usuarios usan la aplicación repetidamente

Si varios usuarios usan la aplicación repetidamente, debe crear una nueva carpeta de datos de usuario (UDF) para cada usuario nuevo y guardar la UDF de cada usuario.

El control WebView2 crea una nueva UDF para cada nuevo usuario. El control WebView2 crea una UDF por sesión. Si hay varias sesiones WebView2, el control WebView2 crea varias UDF. Normalmente, si la aplicación host tiene más de una instancia de control WebView2, la aplicación host debe apuntar todas las instancias de WebView2 a la misma UDF.

Cada aplicación host que tenga una instancia de control WebView2 tendrá su propia UDF. La aplicación host puede tener cada punto udf en el mismo lugar.

Si la aplicación host es para varios usuarios, probablemente debería crear una UDF por usuario. Si la aplicación se instaló por usuario, así es como funciona.

Si inicia dos copias de la aplicación host, usarán la misma UDF.

  • En el caso de las aplicaciones host de Win32, la UDF no se quita automáticamente.
  • Para las aplicaciones host de .NET (WPF & WinForms), la UDF no se quita automáticamente.
  • En el caso de las aplicaciones host ClickOnce, la UDF se quita automáticamente.
  • En el caso de las aplicaciones host de WinUI 2 (UWP), la UDF no se quita automáticamente.
  • En el caso de las aplicaciones host de WinUI 3, la UDF no se quita automáticamente.

Desinstalación de una aplicación host

Al desinstalar una aplicación host WebView2 se usa el proceso de desinstalación estándar; este proceso no es exclusivo de WebView2.

Durante la desinstalación, es posible que el instalador tenga que limpiar cualquier UDF creada. En algunos casos, es posible que desee conservar la UDF.

Si crea la aplicación host, crea un instalador MSIX, instala la aplicación host y, a continuación, ejecuta la aplicación host, crea la UDF. Pero, a continuación, si desinstala la aplicación host, no limpiará automáticamente la UDF (porque el desinstalador protege y conserva los datos del usuario), por lo que el proceso de desinstalación debe tener en cuenta esa consideración.

En las aplicaciones ClickOnce, se instala en una sola ubicación y, cuando finaliza la sesión, elimina todo el árbol, por lo que la UDF se elimina automáticamente. Esto se debe a cómo funciona ClickOnce, no a cómo funciona WebView2.

Conservar carpetas de datos de usuario si la aplicación no tiene usuarios repetidos

En este escenario, cree una nueva carpeta de datos de usuario (UDF) para cada usuario y elimine la UDF anterior.

Eliminación de carpetas de datos de usuario

La aplicación host o el desinstalador pueden eliminar la carpeta de datos de usuario (UDF). Es posible que tenga que eliminar las UDF por cualquiera de las siguientes razones:

  • Si quieres desinstalar una aplicación empaquetada de la Tienda Windows. En este caso, Windows elimina automáticamente las UDF.

  • Si desea limpiar todo el historial de datos de exploración. Sin embargo, vea primero los métodos de datos de exploración claros , como un enfoque más sencillo y flexible.

  • Si desea recuperarse de daños en los datos.

  • Si desea quitar datos de sesión anteriores.

  • Si desea cambiar la ubicación de udf. Si cambia la ubicación de udf, la UDF anterior no se limpiará automáticamente.

Finalizar la sesión de WebView2 antes de eliminar la UDF

Para eliminar una carpeta de datos de usuario (UDF), primero debe finalizar la sesión de WebView2. No se puede eliminar una UDF si la sesión WebView2 está activa actualmente.

Espere a que los procesos del explorador salgan antes de eliminar la UDF.

Si los archivos siguen en uso después de que se cierre la aplicación host WebView2, espere a que los procesos del explorador salgan antes de eliminar la carpeta de datos de usuario (UDF).

Es posible que los archivos de las UDF todavía estén en uso después de cerrar la aplicación WebView2. En esta situación, espere a que salga el proceso del explorador y todos los procesos secundarios antes de eliminar la UDF. Para supervisar los procesos para esperar a que salgan, recupere el identificador de proceso del proceso del explorador mediante la BrowserProcessId propiedad de la instancia de la aplicación WebView2.

Compartir carpetas de datos de usuario

Las instancias de control WebView2 pueden compartir las mismas carpetas de datos de usuario (UDF) para hacer lo siguiente:

Tenga en cuenta lo siguiente al compartir UDF:

  • Al volver a crear controles WebView2 para actualizar las versiones del explorador mediante controladores de eventos add_NewBrowserVersionAvailable (Win32) o eventos NewBrowserVersionAvailable (.NET), la aplicación host debe asegurarse de que los procesos del explorador salgan y cierren los controles WebView2 que comparten la misma UDF. Para recuperar el identificador de proceso del proceso del explorador, use la BrowserProcessId propiedad del control WebView2.

Evite ejecutar demasiadas carpetas a la vez

Para aislar diferentes partes de la aplicación, o cuando no se necesitan datos compartidos entre controles WebView2, puede usar diferentes carpetas de datos de usuario (UDF). Por ejemplo, una aplicación puede constar de dos controles WebView2, uno para mostrar un anuncio y otro para mostrar contenido de la aplicación. Puede usar distintas UDF para cada control WebView2.

Cada proceso del explorador WebView2 consume memoria y espacio en disco adicionales. Por lo tanto, evite ejecutar un control WebView2 con demasiadas UDF diferentes al mismo tiempo.

En lugar de varias UDF, puede usar varios perfiles para lograr la separación del almacenamiento de datos del explorador para distintos controles WebView2. Cada perfil guarda los datos del explorador en una carpeta dedicada en la misma UDF compartida. Consulte Compatibilidad con varios perfiles en una sola carpeta de datos de usuario.

Vea también