共用方式為


管理使用者資料資料夾

UDF) (使用者資料資料夾是儲存在使用者機器上的資料夾,內含與主機應用程式及 WebView2 相關的資料。 WebView2 應用程式使用使用者資料資料夾來儲存瀏覽器資料,例如 Cookie、權限和快取資源。

術語:

術語 定義
使用者資料資料夾 WebView2 建立的資料夾用來儲存瀏覽器資料,例如 Cookie、權限和快取資源。
聯合民主陣線 使用者資料資料夾。
UDF地點 使用者資料資料夾的目錄路徑。
預設的 UDF 位置 使用者資料資料夾的預設目錄路徑。 如果你沒有指定自訂 UDF 位置,WebView2 會建立 UDF 的目錄路徑。
自訂 UDF 位置 使用者資料資料夾的自訂位置。 你的 WebView2 主機應用程式所設定的目錄路徑會指定 WebView2 建立使用者資料資料夾的位置。

WebView2 會在平台預設位置建立 UDF,或是你主機應用程式明確指定的自訂 UDF 位置。

預設情況下,WebView2 會在該平台的預設位置建立 UDF。 這在某些平台上運作良好,但在其他平台上則不然。 如果你的應用程式有特定需求,你可以指定自訂的 UDF 位置。

適合的自訂 UDF 位置

如果您指定自訂的 UDF 位置,應該符合以下要求:

  • 自訂的 UDF 位置必須具備 WebView2 應用程式執行時的適當讀寫權限。

  • 避免將使用者設定儲存在網路磁碟機上。 這可能導致速度變慢、當機或資料遺失。

UDF 中儲存了哪些資料

WebView2 應用程式使用使用者資料資料夾 (UDFs) 來儲存瀏覽器資料,如 Cookie、權限及快取資源。

資料類型 描述
AllDomStorage DOM 儲存資料,現在與未來。 此瀏覽資料類型包含 FileSystemsIndexedDbWebSqlCacheStorage
AllProfile 應該清除帳號資料,讓它看起來像是新的帳號。 這不會刪除像密碼這類帳號範圍的資料,但會透過登出使用者來移除帳號範圍資料的存取權。所有個人資料資料,現在與未來皆可。 未來可能會新增新的個人資料類型。 此瀏覽資料類型包括資料類型 AllSiteDiskCacheDownloadHistoryBrowsingHistoryGeneralAutofillPasswordAutosaveSettings及 。
AllSite 所有現場數據,現在與未來皆可。 此瀏覽資料類型包含資料類型 AllDomStorageCookies。 未來可能會新增網站資料類型。
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 儲存。 (Web SQL 支援已從 Microsoft Edge 移除;請參閱即將在 Microsoft Edge 上進行的網站相容性高影響變更 )

上述資料類型在 CoreWebView2BrowsingDataTypes 枚舉中列為列舉成員。

UDF是如何以及何時成立的

UDF) (使用者資料資料夾是由 WebView2 控制項為你的 WebView2 主機應用程式建立的。

UDF 會在平台的預設 UDF 位置建立,或者如果你的主機應用程式指定自訂 UDF 位置,則該 UDF 會建立在該自訂 UDF 位置。

如果 UDF 不存在,則會在啟動 WebView2 主機應用程式時建立 UDF。

創建了多少個 UDF?

每個 WebView2 控制項實例都與一個 WebView2 會話相關聯。

  • 每個 WebView2 會話恰好有一次 UDF。
  • UDF 一次最多只能有一個 WebView2 會話。

WebView2 控制項會與使用相同 UDF 的其他 WebView2 控制項共享其 WebView2 會話。 無論 WebView2 控制項在同一個主機應用程式中,還是不同主機應用程式,這點都適用。 然而,UDF 只能在同一登入會話中的主機應用程式間共享, (更具體來說,只有一個 HDESKTOP) 。 請參見 WebView2 應用程式的流程模型

如何推動UDF

要將使用者資料資料夾移 (UDF) :

  1. 關閉所有 WebView2 會話。

  2. 將 UDF 的內容移至新的自訂 UDF 位置。

  3. 啟動一個新的 WebView2 主機應用程式會話,指定新的自訂 UDF 位置。

預設的 UDF 位置

UDF) (預設的使用者資料資料夾位置會因平台而異。

在這個平台上,預設的 UDF 位置就是應用程式執行檔 (.exe) 正在執行的目錄。 預設的 UDF 是你應用程式 + .WebView2的) 路徑 (exe 執行檔。 UDF 的檔名是你應用程式 + .WebView2) 路徑上的可執行檔 (exe

例如,如果你執行 D:\WebView2App\WebView2.exe,就會建立一個 UDF 資料夾: D:\WebView2App\WebView2.exe.WebView2\。 另一個例子是: WebView2APISample.exe.WebView2\

你應該使用預設的 UDF 位置還是自訂的 UDF 位置?

大多數情況下,你應該指定自訂的 UDF 位置,而不是使用預設的 UDF 位置。 這確保 WebView2 控制項擁有寫入權限,使 WebView2 控制項能夠建立 UDF 並對其寫入。 請參見下方「指定自訂 UDF 位置」一節。

包裝:

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 倉庫>附近的 Win32 相關 .cpp.cs檔案。

瀏覽器資料在 UDF 中儲存的位置:

建立會話與 UDF 後,瀏覽器資料會儲存在 的 userDataFolder子資料夾中。

為什麼您應該在此平台上使用自訂的 UDF 位置:

如果你沒有指定自訂的 UDF 位置,預設位置可能會在執行時失敗,尤其是安裝程式技術,因為安裝程式會把應用程式和 UDF 放在檔案系統的受保護區域,WebView2 無法建立 UDF,因此 UDF 建立通常會失敗。 WebView2 會拋出錯誤訊息,告知你的主機應用程式無法在該位置建立 UDF。

如果主機應用程式從使用者沒有寫入權限的位置執行,WebView2 就無法建立 UDF,啟動時你會收到執行錯誤。

取得 UDF 位置

要知道 UDF) 位置 (使用者資料資料夾設定在什麼位置,請使用該 CoreWebView2Environment.UserDataFolder 屬性。 此唯讀特性會回傳 WebView2 會話的 UDF 位置。

你可能想閱讀UDF地點的原因:

  • 如果你想清除 UDF 資料夾中的瀏覽資料,例如在會話結束時,

  • 如果你想刪除 UDF,

使用 Win32 ICoreWebView2Environment7.get_UserDataFolder屬性擷取器。 該 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內部空間的清算

你可以使用 WebView2 API 清除 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 要好。

如果同一位使用者反覆使用你的應用程式,且應用程式的網頁內容依賴使用者資料,使用者資料資料夾會持續存在

在這種情況下,不要明確刪除 UDF) (的使用者資料資料夾;持續保存資料。

若多個使用者反覆使用您的應用程式,如何維持使用者資料資料夾

如果有多個使用者重複使用你的應用程式,你應該為每個新使用者建立一個新的 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 Store 應用程式, 在這種情況下,Windows 會自動刪除 UDF。

  • 如果你想清理所有瀏覽資料的歷史, 不過,先看清楚瀏覽 資料 的方法,因為它是一種更簡單、更靈活的方法。

  • 如果你想從資料損壞中恢復。

  • 如果你想移除之前的會話資料,

  • 如果你想更改 UDF 的位置, 如果你更改了 UDF 的位置,之前的 UDF 不會自動被清理。

在刪除 UDF 前,先結束 WebView2 會話

要刪除 UDF) (使用者資料資料夾,必須先結束 WebView2 工作階段。 如果 WebView2 會話目前仍在運作,你無法刪除 UDF。

等瀏覽器程序退出後再刪除 UDF

如果在 WebView2 主機應用程式關閉後檔案仍在使用中,請等瀏覽器程序退出後再刪除 UDF) (使用者資料資料夾。

UDF中的檔案在WebView2應用程式關閉後可能仍在使用中。 在這種情況下,請等瀏覽器程序和所有子程序退出後再刪除 UDF。 為了監控程序等待它們退出,請利用 BrowserProcessId WebView2 應用程式實例的屬性取得瀏覽器程序的程序 ID。

共用使用者資料資料夾

WebView2 控制實例可共用相同的使用者資料資料夾 (UDFs) ,以達成以下功能:

分享 UDF 時請考慮以下幾點:

  • 當你用 add_NewBrowserVersionAvailable (Win32) 事件處理程式或 NewBrowserVersionAvailable (.NET) 事件重新建立 WebView2 控制項以更新瀏覽器版本時,你的主機應用程式必須確保瀏覽器程序退出並關閉所有共用相同 UDF 的 WebView2 控制項。 要取得瀏覽器程序的程序 ID,請使用 BrowserProcessId WebView2 控制項的屬性。

避免同時執行太多資料夾

為了隔離應用程式的不同部分,或在不需要 WebView2 控制項間共享資料時,你可以使用不同的使用者資料資料夾 (UDFs) 。 例如,一個應用程式可以包含兩個 WebView2 控制項,一個用於顯示廣告,另一個用於顯示應用程式內容。 你可以為每個 WebView2 控制項使用不同的 UDF。

每個 WebView2 瀏覽器程序會消耗額外的記憶體和磁碟空間。 因此,避免同時執行過多不同 UDF 的 WebView2 控制項。

你不必使用多個 UDF,而是使用多個設定檔來實現不同 WebView2 控制項的瀏覽器資料儲存分離。 每個設定檔都會將瀏覽器資料儲存在同一個共用 UDF 下的專用資料夾中。 請參閱 支援單一使用者資料資料夾下的多個設定檔

另請參閱