管理用戶資料資料夾

  • 發行項

UDF) (用戶資料資料資料夾是儲存在用戶電腦上的資料夾，其中包含與主應用程式和 WebView2 相關的數據。 WebView2 應用程式會使用使用者資料資料夾來儲存瀏覽器數據，例如 Cookie、許可權和快取的資源。

術語：

術語 定義
用戶資料資料夾 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、IndexedDb、、WebSqlCacheStorage。
AllProfile 應該抹除的配置檔數據，使其看起來像新的配置檔。 這不會刪除帳戶範圍的數據，例如密碼，但會藉由將使用者註銷來移除帳戶範圍數據的存取權。所有配置檔數據，現在和未來。 未來可能會將新的配置檔數據類型新增至此數據類型。 此瀏覽資料種類包含資料類型AllSite、、DiskCache、、DownloadHistoryPasswordAutosaveGeneralAutofill、 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 (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) 位置會因每個平台而異。

在此平臺上，預設 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，然後寫入它。 See the section "Specifying a custom UDF location" below.

包裝：

Win32 MSIX 封裝是獨立的 .exe。

指定自訂 UDF 位置

如何指定自定義使用者數據資料夾 (UDF) 位置會因每個平臺而異。

在此平臺上，在大部分情況下，您應該指定自定義 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 啟動期間收到運行時錯誤。

擷取 UDF 位置

若要找出 UDF) 位置設定的使用者資料資料夾 (，請使用 UserDataFolder 屬性。 這個只讀屬性會傳回 WebView2 應用程式的 UDF 位置。

您可能要讀取 UDF 位置的原因：

  • 如果您想要清除 UDF 資料夾中的瀏覽資料，例如在工作階段結束時。

  • 如果您想要刪除 UDF。

使用 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 範例。

清除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位置，上述都成立。

如果記憶體不足，或 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。 若要監視進程等候它們結束，請使用 BrowserProcessId WebView2 應用程式實例的 屬性來擷取瀏覽器進程的進程識別碼。

共用使用者資料資料資料夾

WebView2 控制項實例可以分享 UDF) (相同的使用者資料資料夾，以執行下列動作：

共用UDF時，請考慮下列事項：

  • 重新建立 WebView2 控制件以使用 add_NewBrowserVersionAvailable ( Win32) 事件處理程式或 NewBrowserVersionAvailable (.NET) 事件更新瀏覽器版本時，您的主應用程式必須確定瀏覽器進程會結束並關閉任何共用相同 UDF 的 WebView2 控件。 若要擷取瀏覽器進程的進程標識碼，請使用 BrowserProcessId WebView2 控件的屬性。

避免一次執行太多資料夾

若要隔離應用程式的不同部分，或不需要在 WebView2 控件之間共用數據時，您可以使用不同的使用者數據資料夾， (UDF) 。 例如，應用程式可以包含兩個 WebView2 控制件，一個用於顯示廣告，另一個用於顯示應用程式內容。 您可以針對每個 WebView2 控制件使用不同的 UDF。

每個 WebView2 瀏覽器程式都會耗用額外的記憶體和磁碟空間。 因此，請避免同時執行具有太多不同 UDF 的 WebView2 控件。

您可以使用多個配置檔來達到不同 WebView2 控件的瀏覽器資料儲存區區隔，而不是多個 UDF。 每個配置檔都會將瀏覽器資料儲存在相同共用UDF下的專用資料夾中。 請參閱 在單一用戶資料夾下支援多個配置檔。

另請參閱