管理用户数据文件夹

UDF) (用户数据文件夹是存储在用户计算机上的文件夹，其中包含与主机应用和 WebView2 相关的数据。 WebView2 应用使用用户数据文件夹来存储浏览器数据，例如 Cookie、权限和缓存的资源。

术语：

Term	定义
用户数据文件夹	WebView2 创建用于存储浏览器数据（如 Cookie、权限和缓存资源）的文件夹。
Udf	用户数据文件夹。
UDF 位置	用户数据文件夹的目录路径。
默认 UDF 位置	用户数据文件夹的默认目录路径。 如果未指定自定义 UDF 位置，则 WebView2 在其中创建 UDF 的目录路径。
自定义 UDF 位置	用户数据文件夹的自定义位置。 WebView2 主机应用指定 WebView2 创建用户数据文件夹的位置的目录路径。

WebView2 在平台的默认位置或主机应用显式指定的自定义 UDF 位置创建 UDF。

默认情况下，WebView2 在特定平台的默认位置创建 UDF。 这在某些平台上非常有效，但不适用于其他平台。 如果应用有特定需求，可以指定自定义 UDF 位置。

合适的自定义 UDF 位置

如果指定自定义 UDF 位置，则它应满足以下要求：

• 自定义 UDF 位置必须对 WebView2 应用运行时具有相应的读/写权限。

• 避免将用户设置存储在网络驱动器上。 这可能会导致速度变慢、崩溃或数据丢失。

UDF 中存储了哪些类型的数据

WebView2 应用使用用户数据文件夹 (UDF) 来存储浏览器数据，例如 Cookie、权限和缓存的资源。

数据类型	说明
AllDomStorage	现在和将来的 DOM 存储数据。 此浏览数据类型包括 FileSystems、、IndexedDbWebSql、CacheStorage。
AllProfile	应擦除以使其看起来像新配置文件的配置文件数据。 这不会删除帐户范围的数据（如密码），但会通过注销用户来删除对帐户范围数据的访问权限。现在和将来的所有配置文件数据。 将来可能会向此数据类型添加新的配置文件数据类型。 此浏览数据类型包括数据类型 AllSite、、DiskCache、DownloadHistoryGeneralAutofill、PasswordAutosave、 BrowsingHistory和 Settings。
AllSite	现在和将来的所有站点数据。 此浏览数据类型包括数据类型 AllDomStorage 和 Cookies。 将来可能会向此数据类型添加新的站点数据类型。
BrowsingHistory	浏览历史记录数据。
CacheStorage	由 CacheStorage DOM API 存储的数据。
Cookies	HTTP Cookie 数据。
DiskCache	磁盘缓存。
DownloadHistory	下载历史记录数据。
FileSystems	文件系统数据。
GeneralAutofill	常规自动填充表单数据。 这不包括密码信息，包括姓名、街道和电子邮件地址、电话号码和任意输入等信息。 包括付款数据。
IndexedDb	由 IndexedDB DOM 功能存储的数据。
LocalStorage	localStorage DOM API 存储的数据。
PasswordAutosave	密码自动保存数据。
Settings	设置数据。
WebSql	Web SQL 数据库 DOM API 存储的数据。

上述数据类型在 CoreWebView2BrowsingDataKinds 枚举中列为枚举成员。

UDF 的创建方式和时间

用户数据文件夹 (UDF) 由 WebView2 控件为 WebView2 主机应用创建。

UDF 是在平台的默认 UDF 位置创建的，或者如果主机应用指定了自定义 UDF 位置，则会在自定义 UDF 位置中创建 UDF。

如果 UDF 不存在，则在 WebView2 主机应用启动时创建 UDF。

创建了多少 UDF？

WebView2 控件的每个实例都与 UDF) (用户数据文件夹相关联。

每个 WebView2 会话都必须有一个 UDF。 每个 WebView2 会话只有 1 个活动 UDF。

每个应用 WebView2 会话至少有一个 UDF。 主机应用可以通过指定自定义 UDF 位置来重叠它们。 或者，可以为每个计算机提供一个 UDF。 这取决于主机应用如何配置 UDF。

如果应用是按用户安装的，则 UDF 可以是每个用户。 如果主机应用按用户安装，则每个 UDF 对于用户是唯一的（如果未另行指定）。

如何移动 UDF

若要 (UDF) 移动用户数据文件夹，

1. 关闭所有 WebView2 会话。

2. 启动新的 WebView2 主机应用会话，并指定新的自定义 UDF 位置。

默认 UDF 位置

默认用户数据文件夹 (UDF) 位置因平台而异。

Win32

在此平台上，默认 UDF 位置是运行应用可执行文件 (.exe) 的目录。 默认 UDF 是应用的可执行 (exe) 路径 + .WebView2。 UDF 的文件名是应用) exe 路径的可执行文件 (+ .WebView2。

例如，如果运行 D:\WebView2App\WebView2.exe了 ，则会创建一个 UDF 文件夹： D:\WebView2App\WebView2.exe.WebView2\。 作为另一个示例： WebView2APISample.exe.WebView2\。

应使用默认还是自定义 UDF 位置？

在大多数情况下，应指定自定义 UDF 位置，而不是使用默认 UDF 位置。 这可确保 WebView2 控件具有写入访问权限，以便 WebView2 控件能够创建 UDF，然后将其写入。 请参阅下面的“指定自定义 UDF 位置”部分。

包装：

Win32 MSIX 打包是独立的 .exe。

.NET (WPF/WinForms)

在此平台上，默认 UDF 位置是运行应用可执行文件 (.exe) 的目录。 默认 UDF 是应用的可执行 (exe) 路径 + .WebView2。 UDF 的文件名是应用) exe 路径的可执行文件 (+ .WebView2。

例如，如果运行 D:\WebView2App\WebView2.exe了 ，则会创建一个 UDF 文件夹： D:\WebView2App\WebView2.exe.WebView2\。 作为另一个示例： WebView2APISample.exe.WebView2\。

应使用默认还是自定义 UDF 位置？

在大多数情况下，应指定自定义 UDF 位置，而不是使用默认 UDF 位置。 这可确保 WebView2 控件具有写入访问权限，以便 WebView2 控件能够创建 UDF，然后将其写入。 请参阅下面的“指定自定义 UDF 位置”部分。

ClickOnce

在此平台上，默认 UDF 位置是应用可执行文件 (.exe) 在 (或) 的子目录中运行的目录。

应使用默认还是自定义 UDF 位置？

在大多数情况下，应使用默认 UDF 位置。 将在其中创建 UDF 的默认位置在运行时具有适当的权限;默认 UDF 位置是可写位置。

为什么默认位置是可写的：

在运行时，ClickOnce 会自动在 WebView2 具有写入权限的位置安装主机应用。 ClickOnce 可以使用默认 UDF 位置，并保证 WebView2 具有写入权限，以便能够在那里创建 UDF。

但是，主机应用可能无法使用该位置写入数据。 如果主机应用无法写入默认 UDF 位置，请参阅下面的“指定自定义 UDF 位置”部分。

清理：

会话结束时，ClickOnce 会自动清理。

包装：

ClickOnce 是一种用于轻型暂时性应用的部署方法;它是混合模型。 可以保留 ClickOnce 应用，但这不是标准的典型做法。

ClickOnce 应用包装的平台应用类型：

ClickOnce 应用通常包含 .NET 应用。

WinUI 2 (UWP)

在此平台上，默认 UDF 位置是 ApplicationData\LocalFolder 包文件夹中的子文件夹。

应使用默认还是自定义 UDF 位置？

在此平台上，使用默认 UDF 位置。

为什么默认位置是可写的：

WinUI 2 (UWP) 是一个打包的平台;它在沙盒中运行，并打包为在沙盒中运行，通常不是作为单独的文件，而是作为应用程序捆绑包运行。

WinUI 2 (UWP) 应用是每个用户，在安装位置下具有写入访问权限。

对于 UWP， .exe 位于安装程序可以写入到的受保护位置。

在运行时，仅在会话期间，WebView2 主机应用将被授予对本地文件夹的访问权限，因此 WebView2 控件能够在此处创建 UDF 并向其写入。

WebView2 检查该运行时，并在该可写位置创建 UDF。

包装：

WinUI 2 (UWP) 应用是关于依赖项的独立应用，并且用于部署 (DLL) ，尽管它未打包到单个文件中。

WinUI 2 (UWP) 应用是每个用户，在安装位置下具有写入访问权限。

WinUI 3

在此平台上，默认 UDF 位置是 ApplicationData\LocalFolder 包文件夹中的子文件夹。

应使用默认还是自定义 UDF 位置？

在此平台上，使用默认 UDF 位置。

包装：

WinUI 3 是一个“打包”平台;它在沙盒中运行，并打包为在沙盒中运行，通常不是作为单独的文件，而是作为应用程序捆绑包运行。

指定自定义 UDF 位置

如何指定自定义用户数据文件夹 (UDF) 位置因平台而异。

Win32

在此平台上，在大多数情况下，应指定自定义 UDF 位置，而不是使用默认 UDF 位置。 这可确保 WebView2 控件具有写入访问权限，以便 WebView2 控件能够创建 UDF，然后将其写入。

应指定存储所有其他应用数据的同一文件夹。

如何指定自定义 UDF 位置：

使用 ICoreWebView2Environment 和 userDataFolder 参数。 但请使用以下代码，该代码来自 WebView2Samples 存储库。

示例代码：

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

有关示例代码，请参阅 WebView2Samples 存储库 > WebView2APISample 附近的 Win32 适当.cpp或.cs文件。

浏览器数据存储在 UDF 中的位置：

创建会话和 UDF 后，WebView2 控件中的浏览器数据将存储在 的 userDataFolder子文件夹中。

为何应在此平台上使用自定义 UDF 位置：

如果不指定自定义 UDF 位置，则如果使用安装程序技术，则默认位置可能会产生运行时故障，因为安装程序技术将应用和 UDF 置于文件系统的受保护区域，其中 WebView2 无法创建 UDF，因此 UDF 创建通常会失败。 WebView2 将引发错误，让主机应用知道无法在该位置创建 UDF。

如果主机应用从用户没有写入访问权限的位置运行，则 WebView2 无法创建 UDF，并且你在 WebView2 启动期间将收到运行时错误。

.NET (WPF/WinForms)

在此平台上，在大多数情况下，应指定自定义 UDF 位置，而不是使用默认 UDF 位置。 这可确保 WebView2 控件具有写入访问权限，以便 WebView2 控件能够创建 UDF，然后将其写入。

如何指定自定义 UDF 位置：

应指定存储所有其他应用数据的同一文件夹。

使用 CoreWebView2Environment.CreateAsync 方法传递 userDataFolder 参数。

示例代码：

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

有关示例代码，请参阅 WebView2Samples 存储库 > WebView2WpfBrowser 附近的 .NET (WPF & WinForms) 适当的.cpp或.cs文件。

为何需要在此平台上指定自定义 UDF：

如果未指定自定义 UDF 位置，则默认位置可能会产生运行时故障（如果使用安装程序技术）。 这是因为安装程序技术将应用和 UDF 置于文件系统的受保护区域中，其中 WebView2 无法创建 UDF，因此 UDF 创建通常会失败。

WebView2 将引发错误，让主机应用知道无法在该位置创建 UDF。

数据存储在 UDF 中的位置： 创建会话和 UDF 后，WebView2 控件中的浏览器数据将存储在 的 userDataFolder子文件夹中。

ClickOnce

在此平台上，在大多数情况下，应使用默认 UDF 位置。

如果指定自定义 UDF 位置，请确保用户数据文件夹位置具有 WebView2 应用运行时的相应读/写权限。

如何指定自定义 UDF 位置：

使用 CoreWebView2Environment.CreateAsync 方法传递 userDataFolder 参数。

应指定存储所有其他应用数据的同一文件夹。

示例代码：

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

有关示例代码，请参阅 WebView2Samples 存储库 > WebView2WpfBrowser 附近的 .NET (WPF & WinForms) 适当的.cpp或.cs文件。

浏览器数据存储在 UDF 中的位置：

创建会话和 UDF 后，WebView2 控件中的浏览器数据将存储在 的 userDataFolder子文件夹中。

WinUI 2 (UWP)

在此平台上，使用默认 UDF 位置。

浏览器数据存储在 UDF 中的位置：

创建会话和 UDF 后，WebView2 控件中的浏览器数据将存储在 的 userDataFolder子文件夹中。

示例代码：

有关示例代码，请参阅 WebView2Samples 存储库>webview2_sample_uwp.cs中的 WinUI 2 (UWP) 文件。

WinUI 3

在此平台上，使用默认 UDF 位置。

示例代码：

有关示例代码，请参阅 WinUI 3 .cs 文件，位于 WebView2Samples 存储库 > WebView2_WinUI3_Sample。

浏览器数据存储在 UDF 中的位置：

创建会话和 UDF 后，WebView2 控件中的浏览器数据将存储在 的 userDataFolder子文件夹中。

检索 UDF 位置

若要了解将 UDF) 位置 (用户数据文件夹设置为什么，请使用 UserDataFolder 属性。 此只读属性返回 WebView2 应用的 UDF 位置。

可能想要读取 UDF 位置的原因：

• 如果要清除 UDF 文件夹中的浏览数据，例如在会话结束时。

• 如果要删除 UDF。

Win32

使用 Win32 ICoreWebView2Environment7.get_UserDataFolder 属性 getter。 该 API 参考页包含显示如何读取 UserDataFolder 属性的示例代码。

示例代码：

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

有关读取 UserDataFolder 属性的示例，请参阅 WebView2Samples 存储库中的 Win32 示例。

.NET (WPF/WinForms)

示例代码：

有关读取 UserDataFolder 属性的示例，请参阅 WebView2Samples 存储库中的 .NET (WPF/WinForms) 示例。

ClickOnce

使用 .NET CoreWebView2Environment.UserDataFolder 属性。

示例代码：

有关读取 UserDataFolder 属性的示例，请参阅 WebView2Samples 存储库 > webview2_sample_uwp。

WinUI 2 (UWP)

使用 WinRT CoreWebView2Environment.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;
}

有关读取UserDataFolder属性的示例，请参阅 WebView2Samples 存储库>webview2_sample_uwp中的 WinUI 2 (UWP) 示例。

WinUI 3

使用 .NET CoreWebView2Environment.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;
}

清除 UDF 中的空间

从 UDF 中清除浏览数据，而不是 (UDF) 删除用户数据文件夹。 例如，在用户注销时清除用户数据和历史记录。

请参阅 清除用户数据文件夹中的浏览数据。

处理错误消息

如果用户数据文件夹 (UDF) 没有写入权限，可能会返回以下错误消息字符串：

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

无论用户数据文件夹的位置是默认 UDF 位置还是自定义 UDF 位置，上述都是 true。

如果内存不足，或者 Microsoft Edge 运行时无法启动，或者找不到 WebView2 运行时，可能会返回类似于以下内容的错误消息字符串：

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

添加代码（如 try/catch 代码）来处理这些错误。 这些错误往往是无法从中恢复的严重错误，因此 try/catch 可以防止应用崩溃。 然后，你将能够检测到故障并正常关闭应用。 某些错误不可恢复，例如 Access Denied 尝试使用你没有写入权限的用户数据文件夹时。

错误消息字符串显示在对话框中。

是否在各种方案中保留用户数据文件夹

主机应用 (UDF) 控制用户数据文件夹的生存期。 如果应用重新使用应用会话中的用户数据，请考虑保存 (即不删除 UDF) 。

如果应用不重复使用应用会话中的用户数据，则可以删除 UDF。 但是，当会话正在运行时，最好调用 清除浏览数据 方法，而不是删除 UDF。

如果同一用户反复使用你的应用，并且应用的 Web 内容依赖于用户的数据，则保留用户数据文件夹

在这种情况下，不要显式删除用户数据文件夹 (UDF) ;持久保存数据。

如果多个用户反复使用你的应用，则保留用户数据文件夹

如果多个用户反复使用你的应用，则应为每个新用户创建一个新的用户数据文件夹 (UDF) ，并保存每个用户的 UDF。

WebView2 控件为每个新用户创建新的 UDF。 WebView2 控件为每个会话创建一个 UDF。 如果有多个 WebView2 会话，WebView2 控件将创建多个 UDF。 通常，如果主机应用有多个 WebView2 控件实例，则主机应用应将 WebView2 的所有实例指向同一 UDF。

具有 WebView2 控件实例的每个主机应用都有自己的 UDF。 主机应用可以将每个 UDF 点指向同一位置。

如果主机应用适用于多个用户，则应该为每个用户创建一个 UDF。 如果你的应用是按用户安装的，则其工作原理就是这样。

如果启动主机应用的两个副本，它们将使用相同的 UDF。

• 对于 Win32 主机应用，UDF 不会自动删除。
• 对于 .NET (WPF & WinForms) 主机应用，不会自动删除 UDF。
• 对于 ClickOnce 主机应用，将自动删除 UDF。
• 对于 WinUI 2 (UWP) 主机应用，UDF 不会自动删除。
• 对于 WinUI 3 主机应用，不会自动删除 UDF。

卸载主机应用

卸载 WebView2 主机应用使用标准卸载过程;此过程并非 WebView2 所独有。

在卸载期间，安装程序可能需要清理任何创建的 UDF。 在某些情况下，可能需要保留 UDF。

如果创建主机应用、创建 MSIX 安装程序、安装主机应用，然后运行主机应用，则会创建 UDF。 但是，如果卸载主机应用，则不会自动清理 UDF (，因为卸载程序会) 保护并保留用户数据，因此卸载过程需要注意这一注意事项。

在 ClickOnce 应用中，它将安装在单个位置，会话结束时，它会删除整个树，因此会自动删除 UDF。 这是因为 ClickOnce 的工作原理，而不是 WebView2 的工作原理。

如果应用没有重复用户，则保留用户数据文件夹

在此方案中，为每个用户创建一个新的用户数据文件夹 (UDF) ，并删除以前的 UDF。

删除用户数据文件夹

主机应用或卸载程序可以删除 UDF) (用户数据文件夹。 出于以下任一原因，可能需要删除 UDF：

• 如果要卸载打包的 Windows 应用商店应用。 在这种情况下，Windows 会自动删除 UDF。

• 如果要清理所有浏览数据历史记录。 但是，请先查看 清晰的浏览数据 方法，这是一种更简单、更灵活的方法。

• 如果要从数据损坏中恢复。

• 如果要删除以前的会话数据。

• 如果要更改 UDF 位置。 如果更改 UDF 位置，则不会自动清理以前的 UDF。

在删除 UDF 之前结束 WebView2 会话

若要 (UDF) 删除用户数据文件夹，必须先结束 WebView2 会话。 如果 WebView2 会话当前处于活动状态，则无法删除 UDF。

在删除 UDF 之前等待浏览器进程退出

如果 WebView2 主机应用关闭后仍在使用文件，请等待浏览器进程退出，然后删除用户数据文件夹 (UDF) 。

关闭 WebView2 应用后，UDF 中的文件可能仍在使用。 在这种情况下，请等待浏览器进程和所有子进程退出，然后再删除 UDF。 若要监视进程以等待它们退出，请使用 WebView2 应用实例的 属性检索浏览器进程的进程 BrowserProcessId ID。

共享用户数据文件夹

WebView2 控件实例可以共享相同的用户数据文件夹 (UDF) ，以执行以下操作：

• 通过在一个浏览器进程中运行来优化系统资源。 请参阅 WebView2 应用的进程模型。

• 具有具有不同配置文件的 WebView2 控件，以将浏览器数据存储（例如 Cookie、权限和缓存资源）分隔在同一 UDF 下。 请参阅 支持单个用户数据文件夹下的多个配置文件。

共享 UDF 时，请考虑以下事项：

• 使用 add_NewBrowserVersionAvailable ( Win32) 事件处理程序或 NewBrowserVersionAvailable (.NET) 事件重新创建 WebView2 控件以更新浏览器版本时，主机应用必须确保浏览器处理退出并关闭共享同一 UDF 的任何 WebView2 控件。 若要检索浏览器进程的进程 ID，请使用 BrowserProcessId WebView2 控件的 属性。

避免一次运行过多文件夹

若要隔离应用的不同部分，或者在不需要在 WebView2 控件之间共享数据时，可以使用不同的用户数据文件夹 (UDF) 。 例如，一个应用可以包含两个 WebView2 控件，一个用于显示广告，另一个用于显示应用内容。 可以为每个 WebView2 控件使用不同的 UDF。

每个 WebView2 浏览器进程都会消耗额外的内存和磁盘空间。 因此，避免同时运行具有太多不同 UDF 的 WebView2 控件。

可以使用多个配置文件来实现不同 WebView2 控件的浏览器数据存储分离，而不是多个 UDF。 每个配置文件将浏览器数据保存在同一共享 UDF 下的专用文件夹中。 请参阅 支持单个用户数据文件夹下的多个配置文件。

另请参阅

• 支持单个用户数据文件夹下的多个配置文件
• 清除用户数据文件夹中的浏览数据
• 在 Windows 应用开发文档中打包和部署 (生成适用于 Windows) 的桌面应用。
• ClickOnce 安全性和部署 - Visual Studio 部署文档。
• 了解 Microsoft Edge 中的 ClickOnce 和 DirectInvoke 功能 - Microsoft Edge Enterprise 文档中。