Поделиться через


Управление папками данных пользователя

Папка пользовательских данных (UDF) — это папка, хранящаяся на компьютере пользователя, которая содержит данные, связанные с ведущим приложением и WebView2. Приложения WebView2 используют папки данных пользователей для хранения данных браузера, таких как файлы cookie, разрешения и кэшированные ресурсы.

Терминологии:

Термин Определение
папка данных пользователя Папка, созданная WebView2 для хранения данных браузера, таких как файлы cookie, разрешения и кэшированные ресурсы.
UDF Папка данных пользователя.
Расположение определяемой пользователем функции Путь к каталогу папки данных пользователя.
расположение UDF по умолчанию Путь к каталогу по умолчанию для папки данных пользователя. Путь к каталогу, по которому WebView2 создает определяемую пользователем функцию, если не указать пользовательское расположение.
пользовательское расположение UDF Пользовательское расположение для папки данных пользователя. Путь к каталогу, который указывает ведущем приложении WebView2, где WebView2 создаст папку данных пользователя.

WebView2 создает определяемую пользователем функцию в расположении по умолчанию для платформы или в пользовательском расположении UDF, явно заданном ведущим приложением.

По умолчанию WebView2 создает определяемую пользователем функцию в расположении по умолчанию для конкретной платформы. Это хорошо работает на некоторых платформах, но не на других. Если приложение имеет определенные потребности, можно указать пользовательское расположение UDF.

Подходящие пользовательские расположения UDF

Если указать пользовательское расположение UDF, оно должно соответствовать следующим требованиям:

  • Пользовательское расположение UDF должно иметь соответствующие разрешения на чтение и запись для среды выполнения приложения WebView2.

  • Избегайте хранения параметров пользователя на сетевом диске. Это может привести к замедлению, сбоям или потере данных.

Тип данных, хранящихся в UDF

Приложения WebView2 используют папки пользовательских данных (UDF) для хранения данных браузера, таких как файлы cookie, разрешения и кэшированные ресурсы.

Тип данных Описание
AllDomStorage Данные хранилища DOM сейчас и в будущем. Этот тип данных браузера включает в себя FileSystems, IndexedDb, WebSql, CacheStorage.
AllProfile Данные профиля, которые необходимо очистить, чтобы они выглядели как новый профиль. Это не приведет к удалению данных на уровне учетной записи, таких как пароли, но приведет к удалению доступа к данным на уровне учетной записи путем выхода пользователя из учетной записи. Все данные профиля, как сейчас, так и в будущем. В будущем в этот тип данных могут быть добавлены новые типы данных профиля. Этот тип данных браузера включает типы AllSiteданных , , DiskCache, DownloadHistoryGeneralAutofill, PasswordAutosave, BrowsingHistoryи Settings.
AllSite Все данные сайта, сейчас и в будущем. Этот тип данных браузера включает типы AllDomStorage данных и Cookies. В будущем в этот тип данных могут быть добавлены новые типы данных сайта.
BrowsingHistory Данные журнала браузера.
CacheStorage Данные, хранящиеся API DOM CacheStorage.
Cookies Данные файлов cookie HTTP.
DiskCache Кэш диска.
DownloadHistory Скачивание данных журнала.
FileSystems Данные файловой системы.
GeneralAutofill Общие данные формы автозаполнения. Это исключает сведения о пароле и включает такие сведения, как имена, адреса улиц и электронной почты, номера телефонов и произвольные входные данные. Включает платежные данные.
IndexedDb Данные, хранящиеся функцией DOM IndexedDB.
LocalStorage Данные, хранящиеся с помощью API DOM localStorage.
PasswordAutosave Данные с автоматическим сохранением пароля.
Settings Данные параметров.
WebSql Данные, хранящиеся в API DOM базы данных ВЕБ-SQL.

Приведенные выше типы данных перечислены как члены перечисления в перечислении CoreWebView2BrowsingDataKinds.

Как и когда создается определяемая пользователем функция

Папка пользовательских данных (UDF) создается для ведущего приложения WebView2 элементом управления WebView2.

Определяемая пользователем функция создается в расположении UDF по умолчанию для платформы. Если ведущее приложение указывает пользовательское расположение определяемой определяемой пользователем функции, то определяемая пользователем функция создается в пользовательском расположении UDF.

Определяемая пользователем функция создается при запуске ведущего приложения WebView2, если определяемая пользователем функция не существует.

Сколько пользовательских функций создано?

Каждый экземпляр элемента управления WebView2 связан с папкой пользовательских данных (UDF).

Каждый сеанс WebView2 должен иметь определяемую пользователем функцию. Для каждого сеанса WebView2 требуется только 1 активная определяемая пользователем функция.

Для каждого сеанса WebView2 приложения используется по крайней мере одна определяемая пользователем функция. Ведущее приложение может перекрывать их, указав пользовательское расположение 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, а не использовать расположение по умолчанию. Это гарантирует, что элемент управления WebView2 имеет доступ на запись, чтобы элемент управления WebView2 мог создать определяемую пользователем функцию, а затем выполнить запись в нее. См. раздел "Указание пользовательского расположения UDF" ниже.

Упаковки:

Упаковка Win32 MSIX — это автономная .exeупаковка .

Указание пользовательского расположения UDF

Определение расположения пользовательской папки данных пользователя (UDF) зависит от платформы.

На этой платформе в большинстве случаев следует указывать пользовательское расположение UDF, а не использовать расположение UDF по умолчанию. Это гарантирует, что элемент управления WebView2 имеет доступ на запись, чтобы элемент управления WebView2 мог создать определяемую пользователем функцию, а затем выполнить запись в нее.

Следует указать ту же папку, в которой хранятся все остальные данные приложения.

Как указать пользовательское расположение 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());

Пример кода см. в подходящем для Win32 .cpp.cs файле рядом с репозиторием > WebView2Samples WebView2APISample.

Где данные браузера хранятся в UDF:

После создания сеанса и UDF данные браузера из элемента управления WebView2 хранятся во вложенной папке userDataFolder.

Почему следует использовать пользовательское расположение UDF на этой платформе:

Если не указать пользовательское расположение UDF, расположение по умолчанию может привести к сбою во время выполнения при использовании технологий установщика, так как технологии установщика помещают приложение и, следовательно, определяемую пользователем, в защищенную область файловой системы, где WebView2 не может создать определяемую пользователем функцию, и поэтому создание UDF обычно завершается ошибкой. WebView2 выдает ошибку, чтобы сообщить ведущему приложению о том, что определяемую пользователем функцию нельзя создать в этом расположении.

Если ведущее приложение выполняется из расположения, в которое у пользователя нет доступа на запись, WebView2 не сможет создать определяемую пользователем функцию, и во время запуска WebView2 вы получите ошибку среды выполнения.

Получение расположения UDF

Чтобы узнать, в каком расположении была задана папка пользовательских данных (UDF), используйте UserDataFolder свойство . Это свойство, доступное только для чтения, возвращает расположение UDF для приложения WebView2.

Причины, по которым может потребоваться прочитать расположение 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 свойства см. в примерах Win32 в репозитории WebView2Samples.

Очистка пространства в 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) для каждого нового пользователя и сохранить определяемую пользователем функцию пользователя.

Элемент управления WebView2 создает новую UDF для каждого нового пользователя. Элемент управления WebView2 создает одну определяемую пользователем функцию на сеанс. При наличии нескольких сеансов WebView2 элемент управления WebView2 создает несколько определяемых пользователем функций. Как правило, если в ведущем приложении есть несколько экземпляров элемента управления WebView2, ведущее приложение должно указывать все экземпляры WebView2 на одну и ту же определяемую пользователем функцию.

Каждое ведущее приложение с экземпляром элемента управления WebView2 будет иметь собственную определяемую пользователем функцию. Ваше ведущее приложение может иметь все точки UDF в одном и том же месте.

Если ваше ведущее приложение предназначено для нескольких пользователей, скорее всего, следует создать одну определяемую пользователем функцию. Если приложение было установлено для каждого пользователя, оно работает следующим образом.

При запуске двух копий ведущего приложения они будут использовать одну и ту же определяемую пользователем функцию.

  • Для ведущих приложений Win32 определяемая пользователем функция не удаляется автоматически.
  • Для ведущих приложений .NET (WPF & WinForms) определяемая пользователем функция не удаляется автоматически.
  • Для ведущих приложений ClickOnce определяемая пользователем функция удаляется автоматически.
  • Для ведущих приложений WinUI 2 (UWP) определяемая пользователем функция не удаляется автоматически.
  • Для ведущих приложений WinUI 3 определяемая пользователем функция не удаляется автоматически.

Удаление ведущего приложения

При удалении ведущего приложения WebView2 используется стандартный процесс удаления; этот процесс не является уникальным для WebView2.

Во время удаления установщику может потребоваться очистить все созданные UDF. В некоторых случаях может потребоваться сохранить определяемую пользователем функцию.

Если вы создаете ведущее приложение, создаете установщик MSIX, устанавливаете ведущее приложение, а затем запускаете ведущее приложение, оно создает определяемую пользователем функцию. Но если вы удалите ведущее приложение, это не будет автоматически очищать определяемую пользователем функцию (так как средство удаления защищает и сохраняет данные пользователя), поэтому процесс удаления должен учитывать это соображение.

В приложениях ClickOnce он устанавливается в одном расположении, а по завершении сеанса удаляет все дерево, поэтому определяемая пользователем функция автоматически удаляется. Это связано с тем, как работает ClickOnce, а не из-за того, как работает WebView2.

Сохранение папок данных пользователей, если в приложении нет повторяющихся пользователей

В этом сценарии создайте новую папку пользовательских данных (UDF) для каждого пользователя и удалите предыдущую определяемую пользователем папку.

Удаление папок данных пользователя

Ваше ведущее приложение или средство удаления может удалить папку пользовательских данных (UDF). Вам может потребоваться удалить определяемые пользователем функции по любой из следующих причин:

  • Если вы хотите удалить упакованое приложение Магазина Windows. В этом случае Windows автоматически удаляет определяемые пользователем функции.

  • Если вы хотите очистить весь журнал данных браузера. Однако сначала ознакомьтесь с понятными методами просмотра данных , как более простой и гибкий подход.

  • Если вы хотите восстановить данные после повреждения.

  • Если вы хотите удалить данные предыдущего сеанса.

  • Если вы хотите изменить расположение UDF. Если изменить расположение UDF, предыдущая определяемая пользователем функция не будет очищена автоматически.

Завершение сеанса WebView2 перед удалением UDF

Чтобы удалить папку пользовательских данных (UDF), необходимо сначала завершить сеанс WebView2. Невозможно удалить определяемую пользователем функцию, если сеанс WebView2 в настоящее время активен.

Дождитесь завершения процессов браузера, прежде чем удалять определяемую пользователем функцию

Если файлы по-прежнему используются после закрытия ведущего приложения WebView2, дождитесь завершения процессов браузера, прежде чем удалять папку пользовательских данных (UDF).

Файлы в определяемых пользователем функциях могут по-прежнему использоваться после закрытия приложения WebView2. В этом случае дождитесь завершения процесса браузера и всех дочерних процессов, прежде чем удалять определяемую пользователем функцию. Чтобы отслеживать процессы, ожидая их выхода, получите идентификатор процесса браузера с помощью BrowserProcessId свойства экземпляра приложения WebView2.

Общий доступ к папкам данных пользователя

Экземпляры элементов управления WebView2 могут совместно использовать одни и те же пользовательские папки данных (UDF), чтобы сделать следующее:

При совместном использовании определяемых пользователем функций учитывайте следующее:

  • При повторном создании элементов управления WebView2 для обновления версий браузера с помощью обработчиков событий add_NewBrowserVersionAvailable (Win32) или событий NewBrowserVersionAvailable (.NET) ведущее приложение должно убедиться, что процессы браузера завершают и закрывают все элементы управления WebView2, которые используют одну и ту же определяемую пользователем функцию. Чтобы получить идентификатор процесса браузера, используйте BrowserProcessId свойство элемента управления WebView2.

Избегайте одновременного запуска слишком большого количества папок

Чтобы изолировать различные части приложения или если общий доступ к данным между элементами управления WebView2 не требуется, можно использовать разные папки данных пользователя (определяемые пользователем функции). Например, приложение может состоять из двух элементов управления WebView2: один для отображения объявления, а другой для отображения содержимого приложения. Для каждого элемента управления WebView2 можно использовать разные определяемые пользователем функции.

Каждый процесс браузера WebView2 потребляет дополнительную память и дисковое пространство. Поэтому избегайте одновременного запуска элемента управления WebView2 с слишком большим количеством различных определяемых пользователем функций.

Вместо нескольких определяемых пользователем функций можно использовать несколько профилей для разделения хранилища данных браузера для различных элементов управления WebView2. Каждый профиль сохраняет данные браузера в выделенной папке в одной и той же общей пользовательской функции. См . раздел Поддержка нескольких профилей в одной папке данных пользователя.

См. также