Muokkaa

Jaa

Manage user data folders

  • Artikkeli

The user data folder (UDF) is a folder stored on the user's machine, that contains data related to the host app and WebView2. WebView2 apps use user data folders to store browser data, such as cookies, permissions, and cached resources.

Terminology:

Term Definition
user data folder A folder that WebView2 creates to store browser data, such as cookies, permissions, and cached resources.
UDF The user data folder.
UDF location The directory path of the user data folder.
default UDF location The default directory path of the user data folder. The directory path where WebView2 creates the UDF if you don't specify a custom UDF location.
custom UDF location A custom location for the user data folder. The directory path that your WebView2 host app specifies where WebView2 will create the user data folder.

WebView2 creates the UDF in the default location for the platform, or in the custom UDF location that your host app explicitly specifies.

By default, WebView2 creates a UDF in the default location for the particular platform. This works well on some platforms, but not others. If your app has specific needs, you can specify a custom UDF location.

Suitable custom UDF locations

If you specify a custom UDF location, it should meet the following requirements:

  • The custom UDF location must have appropriate Read/Write permissions for the WebView2 app runtime.

  • Avoid storing user settings on a network drive. This can result in slowdowns, crashes, or loss of data.

What kind of data is stored in the UDF

WebView2 apps use user data folders (UDFs) to store browser data, such as cookies, permissions, and cached resources.

Type of data Description
AllDomStorage DOM storage data, now and future. This browsing data kind is inclusive of FileSystems, IndexedDb, WebSql, CacheStorage.
AllProfile Profile data that should be wiped to make it look like a new profile. This does not delete account-scoped data like passwords but will remove access to account-scoped data by signing the user out. All profile data, now and future. New profile data types may be added to this data kind in the future. This browsing data kind includes the data kinds AllSite, DiskCache, DownloadHistory, GeneralAutofill, PasswordAutosave, BrowsingHistory, and Settings.
AllSite All site data, now and future. This browsing data kind includes the data kinds AllDomStorage and Cookies. New site data types may be added to this data kind in the future.
BrowsingHistory Browsing history data.
CacheStorage Data stored by the CacheStorage DOM API.
Cookies HTTP cookies data.
DiskCache Disk cache.
DownloadHistory Download history data.
FileSystems File systems data.
GeneralAutofill General autofill form data. This excludes password information and includes information such as names, street and email addresses, phone numbers, and arbitrary input. Includes payment data.
IndexedDb Data stored by the IndexedDB DOM feature.
LocalStorage Data stored by the localStorage DOM API.
PasswordAutosave Password autosave data.
Settings Settings data.
WebSql Data stored by the Web SQL database DOM API.

The above types of data are listed as enum members in the CoreWebView2BrowsingDataKinds Enum.

How and when the UDF is created

The user data folder (UDF) is created for your WebView2 host app by the WebView2 control.

The UDF is created in the default UDF location for the platform, or if your host app specifies a custom UDF location, the UDF is created in the custom UDF location.

The UDF is created on startup of the WebView2 host app, if the UDF doesn't exist.

How many UDFs are created?

Each instance of a WebView2 control is associated with a user data folder (UDF).

Each WebView2 session must have a UDF. There's only 1 active UDF per WebView2 session.

There is at least one UDF per app WebView2 session. It's possible for your host app to overlap them, by specifying a custom UDF location. Or, you can have one UDF per machine. This depends on how your host app configs the UDF.

A UDF can be either per user, if the app was installed per-user. If the host app is installed per-user, each UDF is unique to a user, if not otherwise specified.

How to move the UDF

To move a user data folder (UDF):

  1. Shut down all WebView2 sessions.

  2. Start a new WebView2 host app session, specifying a new custom UDF location.

The default UDF location

The default user data folder (UDF) location varies per platform.

On this platform, the default UDF location is the directory that the app executable (.exe) is running in. The default UDF is the executable (exe) path of your app + .WebView2. The file name of the UDF is the executable (exe) path of your app + .WebView2.

For example, if you ran D:\WebView2App\WebView2.exe, a UDF folder would be created: D:\WebView2App\WebView2.exe.WebView2\. As another example: WebView2APISample.exe.WebView2\.

Should you use default or custom UDF location?

In most cases, you should specify a custom UDF location, rather than using the default UDF location. This ensures that the WebView2 control has Write access so that the WebView2 control is able to create the UDF and then write to it. See the section "Specifying a custom UDF location" below.

Packaging:

Win32 MSIX packaging is a standalone .exe.

Specifying a custom UDF location

How to specify a custom user data folder (UDF) location varies per platform.

On this platform, in most cases, you should specify a custom UDF location, rather than using the default UDF location. This ensures that the WebView2 control has Write access so that the WebView2 control is able to create the UDF and then write to it.

You should specify the same folder where all other app data is stored.

How to specify a custom UDF location:

Use ICoreWebView2Environment and the userDataFolder parameter. But use the code below, which is from the WebView2Samples repo.

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

For example code, see the Win32-appropriate, .cpp or .cs file, near WebView2Samples repo > WebView2APISample.

Where browser data gets stored within the UDF:

After creation of the session and UDF, browser data from your WebView2 control is stored in a subfolder of userDataFolder.

Why you should use a custom UDF location on this platform:

If you don't specify a custom UDF location, the default location can produce a run-time failure, if using installer technologies, because installer technologies put the app and thus the UDF in a protected area of the filesystem, where WebView2 isn't able to create the UDF, and thus UDF creation will usually fail. WebView2 will throw an error to let your host app know that the UDF can't be created at that location.

If the host app is running from a location that the user doesn't have Write access to, WebView2 isn't able to create the UDF, and you will receive a runtime error during WebView2 startup.

Retrieving the UDF location

To find out what the user data folder (UDF) location was set to, use the UserDataFolder property. This read-only property returns the UDF location for the WebView2 app.

Reasons you might want to read the UDF location:

  • If you want to clear browsing data from the UDF folder, such as at the end of a session.

  • If you want to delete the UDF.

Use the Win32 ICoreWebView2Environment7.get_UserDataFolder property getter. That API Reference page contains example code showing how to read the UserDataFolder property.

Example code:

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

For examples of reading the UserDataFolder property, see the Win32 samples in the WebView2Samples repo.

Clearing space in the UDF

Instead of deleting the user data folder (UDF), clear browsing data from the UDF. For example, clear user data and history when a user signs out.

See Clear browsing data from the user data folder.

Handling error messages

If the user data folder (UDF) doesn't have Write permissions, the following error message strings may be returned:

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

The above is true regardless of whether the location of the user data folder was the default UDF location or a custom UDF location.

If there's insufficient memory, or the Microsoft Edge runtime is unable to start, or the WebView2 Runtime is not found, error message strings similar to the following may be returned:

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

Add code, such as try/catch code, to handle these errors. These errors tend to be fatal errors that you can't recover from, so try/catch will prevent the app from crashing. You'll then be able to detect the failure and close the app gracefully. Some errors are unrecoverable, such as Access Denied when trying to use a user data folder that you don't have Write permissions to.

Error message strings are displayed in a dialog.

Whether to persist user data folders in various scenarios

Your host app controls the lifetime of the user data folder (UDF). If your app re-uses user data from app sessions, consider saving (that is, not deleting) the UDFs.

If your app doesn't reuse user data from app sessions, you can delete the UDF. However, while a session is running, it's better to call the clear browsing data methods instead of deleting the UDF.

Persisting user data folders if same user uses your app repeatedly, and the web content of the app relies on the user's data

In this scenario, don't explicitly delete the user data folder (UDF); persist the data.

Persisting user data folders if multiple users use your app repeatedly

If multiple users use your app repeatedly, you should create a new user data folder (UDF) for each new user, and save the UDF of each user.

The WebView2 control creates a new UDF for each new user. The WebView2 control creates one UDF per session. If there are multiple WebView2 sessions, the WebView2 control creates multiple UDFs. Usually if the host app has more than one WebView2 control instance, the host app should point all instances of WebView2 to the same UDF.

Each host app that has a WebView2 control instance will have its own UDF. Your host app can have each UDF point to the same place.

If your host app is for multiple users, you should probably create one UDF per user. If your app was installed per-user, this is how it works.

If you launch two copies of your host app, they will use the same UDF.

  • For Win32 host apps, the UDF is not automatically removed.
  • For .NET (WPF & WinForms) host apps, the UDF is not automatically removed.
  • For ClickOnce host apps, the UDF is automatically removed.
  • For WinUI 2 (UWP) host apps, the UDF is not automatically removed.
  • For WinUI 3 host apps, the UDF is not automatically removed.

Uninstalling a host app

Uninstalling a WebView2 host app uses the standard uninstalling process; this process is not unique to WebView2.

During uninstall, your installer may need to clean up any created UDF. In some cases, you might want to preserve the UDF.

If you create the host app, create an MSIX installer, install the host app, and then run the host app, it creates the UDF. But then if you uninstall the host app, that won't auto-clean up the UDF (because the uninstaller protects and preserves the user data), so your uninstall process needs to be aware of that consideration.

In ClickOnce apps, it installs in a single location, and when the session ends, it deletes the entire tree, so the UDF is automatically deleted. That's because of how ClickOnce works, not because of how WebView2 works.

Persisting user data folders if your app doesn't have repeat users

In this scenario, create a new user data folder (UDF) for each user, and delete the previous UDF.

Deleting user data folders

Your host app or the uninstaller can delete the user data folder (UDF). You might need to delete UDFs for any of the following reasons:

  • If you want to uninstall a packaged Windows Store app. In this case, Windows deletes UDFs automatically.

  • If you want to clean up all browsing data history. However, see the clear browsing data methods first, as an easier, more flexible approach.

  • If you want to recover from data corruption.

  • If you want to remove previous session data.

  • If you want to change the UDF location. If you change the UDF location, the previous UDF will not be automatically cleaned up.

End the WebView2 session before deleting the UDF

To delete a user data folder (UDF), you must first end the WebView2 session. You cannot delete a UDF if the WebView2 session is currently active.

Wait for browser processes to exit before deleting the UDF

If files are still in use after your WebView2 host app closes, wait for browser processes to exit before deleting the user data folder (UDF).

Files in UDFs might still be in use after the WebView2 app is closed. In this situation, wait for the browser process and all child processes to exit before deleting the UDF. To monitor processes to wait for them to exit, retrieve the process ID of the browser process by using the BrowserProcessId property of the WebView2 app instance.

Sharing user data folders

WebView2 control instances can share the same user data folders (UDFs), to do the following:

Consider the following when sharing UDFs:

  • When re-creating WebView2 controls to update browser versions using add_NewBrowserVersionAvailable (Win32) event handlers or NewBrowserVersionAvailable (.NET) events, your host app must ensure that browser processes exit and close any WebView2 controls that share the same UDF. To retrieve the process ID of the browser process, use the BrowserProcessId property of the WebView2 control.

Avoid running too many folders at once

To isolate different parts of your app, or when sharing data between WebView2 controls isn't needed, you can use different user data folders (UDFs). For example, an app can consist of two WebView2 controls, one for displaying an advertisement and the other for displaying app content. You can use different UDFs for each WebView2 control.

Each WebView2 browser process consumes additional memory and disk space. Therefore, avoid running a WebView2 control with too many different UDFs at the same time.

Rather than multiple UDFs, you can use multiple profiles to achieve browser data storage separation for different WebView2 controls. Each profile saves browser data in a dedicated folder under the same, shared UDF. See Support multiple profiles under a single user data folder.

See also