Partilhar via

Gerir pastas de dados do utilizador

  • Artigo

A pasta de dados do utilizador (UDF) é uma pasta armazenada no computador do utilizador, que contém dados relacionados com a aplicação anfitriã e o WebView2. As aplicações WebView2 utilizam pastas de dados de utilizador para armazenar dados do browser, como cookies, permissões e recursos em cache.

Terminologia:

Termo Definição
pasta de dados do utilizador Uma pasta que o WebView2 cria para armazenar dados do browser, como cookies, permissões e recursos em cache.
UDF A pasta de dados do utilizador.
Localização da UDF O caminho do diretório da pasta de dados do utilizador.
localização predefinida do UDF O caminho de diretório predefinido da pasta de dados do utilizador. O caminho do diretório onde o WebView2 cria o UDF se não especificar uma localização UDF personalizada.
localização personalizada do UDF Uma localização personalizada para a pasta de dados do utilizador. O caminho do diretório que a sua aplicação anfitriã WebView2 especifica onde o WebView2 irá criar a pasta de dados do utilizador.

O WebView2 cria o UDF na localização predefinida para a plataforma ou na localização UDF personalizada especificada explicitamente pela sua aplicação anfitriã.

Por predefinição, o WebView2 cria um UDF na localização predefinida para a plataforma específica. Isto funciona bem em algumas plataformas, mas não em outras. Se a sua aplicação tiver necessidades específicas, pode especificar uma localização UDF personalizada.

Localizações UDF personalizadas adequadas

Se especificar uma localização UDF personalizada, esta deverá cumprir os seguintes requisitos:

  • A localização UDF personalizada tem de ter as permissões de Leitura/Escrita adequadas para o runtime da aplicação WebView2.

  • Evite armazenar as definições de utilizador numa unidade de rede. Isto pode resultar em abrandamentos, falhas ou perda de dados.

Que tipo de dados são armazenados na UDF

As aplicações WebView2 utilizam pastas de dados de utilizador (UDFs) para armazenar dados do browser, como cookies, permissões e recursos em cache.

Tipos de dados Descrição
AllDomStorage Dados de armazenamento DOM, agora e no futuro. Este tipo de dados de navegação inclui FileSystems, , IndexedDbWebSql, CacheStorage.
AllProfile Dados de perfil que devem ser apagados para que pareçam um novo perfil. Isto não elimina dados no âmbito da conta, como palavras-passe, mas remove o acesso aos dados no âmbito da conta ao terminar sessão do utilizador. Todos os dados de perfil, agora e no futuro. Poderão ser adicionados novos tipos de dados de perfil a este tipo de dados no futuro. Este tipo de dados de navegação inclui os tipos AllSitede dados , DiskCache, DownloadHistory, GeneralAutofill, PasswordAutosave, e SettingsBrowsingHistory.
AllSite Todos os dados do site, agora e no futuro. Este tipo de dados de navegação inclui os tipos de AllDomStorage dados e Cookies. Poderão ser adicionados novos tipos de dados de site a este tipo de dados no futuro.
BrowsingHistory Dados do histórico de navegação.
CacheStorage Dados armazenados pela API DOM CacheStorage.
Cookies Dados de cookies HTTP.
DiskCache Cache de disco.
DownloadHistory Transferir dados do histórico.
FileSystems Dados de sistemas de ficheiros.
GeneralAutofill Dados gerais do formulário de preenchimento automático. Isto exclui informações de palavra-passe e inclui informações como nomes, endereços de rua e e-mail, números de telefone e entradas arbitrárias. Inclui dados de pagamento.
IndexedDb Dados armazenados pela funcionalidade DOM do IndexedDB.
LocalStorage Dados armazenados pela API DOM localStorage.
PasswordAutosave Guardar dados automaticamente com palavra-passe.
Settings Definições de dados.
WebSql Dados armazenados pela API DOM da base de dados SQL Web.

Os tipos de dados acima são listados como membros de enumeração na Enumeração CoreWebView2BrowsingDataKinds.

Como e quando a UDF é criada

A pasta de dados do utilizador (UDF) é criada para a sua aplicação anfitriã WebView2 pelo controlo WebView2.

A UDF é criada na localização UDF predefinida para a plataforma ou, se a aplicação anfitriã especificar uma localização UDF personalizada, a UDF é criada na localização UDF personalizada.

A UDF é criada no arranque da aplicação anfitriã WebView2, se a UDF não existir.

Quantas UDFs são criadas?

Cada instância de um controlo WebView2 está associada a uma sessão WebView2.

  • Cada sessão webView2 tem exatamente uma UDF.
  • Uma UDF só pode ter, no máximo, uma sessão WebView2 de cada vez.

Um controlo WebView2 partilha a respetiva sessão WebView2 com qualquer outro controlo WebView2 que utilize o mesmo UDF. Isto acontece se os controlos WebView2 estão na mesma aplicação anfitriã ou em aplicações anfitriãs diferentes. No entanto, uma UDF só pode ser partilhada entre aplicações anfitriãs que estejam na mesma sessão de início de sessão (mais especificamente, apenas um HDESKTOP). Veja Modelo de processo para aplicações WebView2.

Como mover o UDF

Para mover uma pasta de dados de utilizador (UDF):

  1. Encerre todas as sessões do WebView2.

  2. Mova o conteúdo da UDF para a nova localização UDF personalizada.

  3. Inicie uma nova sessão da aplicação anfitriã WebView2, especificando a nova localização UDF personalizada.

A localização predefinida do UDF

A localização predefinida da pasta de dados do utilizador (UDF) varia de acordo com a plataforma.

Nesta plataforma, a localização UDF predefinida é o diretório no qual a aplicação executável (.exe) está em execução. O UDF predefinido é o caminho executável (exe) da sua aplicação + .WebView2. O nome de ficheiro do UDF é o caminho executável (exe) da sua aplicação + .WebView2.

Por exemplo, se executasse D:\WebView2App\WebView2.exe, seria criada uma pasta UDF: D:\WebView2App\WebView2.exe.WebView2\. Como outro exemplo: WebView2APISample.exe.WebView2\.

Deve utilizar a localização UDF predefinida ou personalizada?

Na maioria dos casos, deve especificar uma localização UDF personalizada, em vez de utilizar a localização UDF predefinida. Isto garante que o controlo WebView2 tem acesso de Escrita para que o controlo WebView2 possa criar o UDF e, em seguida, escrever no mesmo. Veja a secção "Especificar uma localização UDF personalizada" abaixo.

Empacotamento:

A embalagem Win32 MSIX é autónoma .exe.

Especificar uma localização UDF personalizada

Como especificar uma localização personalizada da pasta de dados do utilizador (UDF) varia de acordo com a plataforma.

Nesta plataforma, na maioria dos casos, deve especificar uma localização UDF personalizada, em vez de utilizar a localização UDF predefinida. Isto garante que o controlo WebView2 tem acesso de Escrita para que o controlo WebView2 possa criar o UDF e, em seguida, escrever no mesmo.

Deve especificar a mesma pasta onde estão armazenados todos os outros dados da aplicação.

Como especificar uma localização UDF personalizada:

Utilize ICoreWebView2Environment e o userDataFolder parâmetro . No entanto, utilize o código abaixo, que é do WebView2Samples repositório.

Código de exemplo:

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

Por exemplo, veja o ficheiro ou .cs o ficheiro win32 adequado, .cpp perto de WebView2Samples repositório > WebView2APISample.

Onde os dados do browser são armazenados no UDF:

Após a criação da sessão e do UDF, os dados do browser do seu controlo WebView2 são armazenados numa subpasta do userDataFolder.

Por que motivo deve utilizar uma localização UDF personalizada nesta plataforma:

Se não especificar uma localização UDF personalizada, a localização predefinida pode produzir uma falha de tempo de execução, se utilizar tecnologias de instalação, porque as tecnologias do instalador colocam a aplicação e, portanto, o UDF numa área protegida do sistema de ficheiros, onde o WebView2 não consegue criar o UDF e, portanto, a criação do UDF normalmente falhará. O WebView2 gerará um erro para informar a aplicação anfitriã de que não é possível criar o UDF nessa localização.

Se a aplicação anfitriã estiver a ser executada a partir de uma localização à qual o utilizador não tem acesso de Escrita, o WebView2 não conseguirá criar o UDF e receberá um erro de runtime durante o arranque do WebView2.

A obter a localização da UDF

Para saber para que localização foi definida a localização da pasta de dados do utilizador (UDF), utilize a CoreWebView2Environment.UserDataFolder propriedade . Esta propriedade só de leitura devolve a localização UDF para a sessão WebView2.

Motivos pelos quais poderá querer ler a localização da UDF:

  • Se quiser limpar os dados de navegação da pasta UDF, como no final de uma sessão.

  • Se quiser eliminar o UDF.

Utilize o getter da propriedade win32 ICoreWebView2Environment7.get_UserDataFolder. Essa página de Referência da API contém código de exemplo que mostra como ler a UserDataFolder propriedade.

Código de exemplo:

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

Para obter exemplos de leitura da UserDataFolder propriedade, veja os exemplos win32 no repositório WebView2Samples.

Limpar espaço na UDF

Em vez de eliminar toda a pasta de dados do utilizador (UDF), pode utilizar as APIs webView2 para limpar dados de navegação específicos da UDF. Por exemplo, pode limpar os dados e o histórico do utilizador quando um utilizador termina sessão na sua aplicação.

Veja Limpar dados de navegação da pasta de dados do utilizador.

Processar mensagens de erro

Se a pasta de dados do utilizador (UDF) não tiver permissões de Escrita, poderão ser devolvidas as seguintes cadeias de mensagens de erro:

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

O acima é verdadeiro, independentemente de a localização da pasta de dados do utilizador ser a localização predefinida do UDF ou uma localização UDF personalizada.

Se não existir memória suficiente ou se o runtime do Microsoft Edge não conseguir iniciar ou se o Runtime do WebView2 não for encontrado, poderão ser devolvidas cadeias de mensagens de erro semelhantes às seguintes:

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

Adicione código, como try/catch código, para processar estes erros. Estes erros tendem a ser erros fatais dos quais não consegue recuperar, pelo try/catch que impedirão a aplicação de falhar. Em seguida, poderá detetar a falha e fechar a aplicação corretamente. Alguns erros são irrecuperáveis, como Access Denied quando tenta utilizar uma pasta de dados de utilizador para a qual não tem permissões de Escrita.

As cadeias de mensagens de erro são apresentadas numa caixa de diálogo.

Se pretende manter as pastas de dados do utilizador em vários cenários

A aplicação anfitriã controla a duração da pasta de dados do utilizador (UDF). Se a sua aplicação reutilizar dados de utilizador de sessões de aplicações, considere guardar (ou seja, não eliminar) os UDFs.

Se a sua aplicação não reutilizar os dados de utilizador das sessões da aplicação, pode eliminar o UDF. No entanto, enquanto uma sessão está em execução, é melhor chamar os métodos de dados de navegação claros em vez de eliminar o UDF.

Manter as pastas de dados do utilizador se o mesmo utilizador utilizar a sua aplicação repetidamente e o conteúdo Web da aplicação depender dos dados do utilizador

Neste cenário, não elimine explicitamente a pasta de dados do utilizador (UDF); manter os dados.

Pastas de dados do utilizador persistentes se vários utilizadores utilizarem a sua aplicação repetidamente

Se vários utilizadores utilizarem a sua aplicação repetidamente, deve criar uma nova pasta de dados de utilizador (UDF) para cada novo utilizador e guardar o UDF de cada utilizador.

O controlo WebView2 cria um novo UDF para cada novo utilizador. O controlo WebView2 cria um UDF por sessão. Se existirem várias sessões webView2, o controlo WebView2 cria vários UDFs. Normalmente, se a aplicação anfitriã tiver mais do que uma instância de controlo WebView2, a aplicação anfitriã deve apontar todas as instâncias do WebView2 para o mesmo UDF.

Cada aplicação anfitriã que tenha uma instância de controlo WebView2 terá a sua própria UDF. A aplicação anfitriã pode ter cada ponto UDF no mesmo local.

Se a aplicação anfitriã for para vários utilizadores, provavelmente deverá criar uma UDF por utilizador. Se a sua aplicação foi instalada por utilizador, é assim que funciona.

Se iniciar duas cópias da sua aplicação anfitriã, estas utilizarão a mesma UDF.

  • Para aplicações anfitriãs Win32, a UDF não é removida automaticamente.
  • Para aplicações anfitriãs .NET (WPF & WinForms), a UDF não é removida automaticamente.
  • Para aplicações de anfitrião ClickOnce, a UDF é removida automaticamente.
  • Para aplicações anfitriãs WinUI 2 (UWP), a UDF não é removida automaticamente.
  • Para aplicações anfitriãs WinUI 3, a UDF não é removida automaticamente.

Desinstalar uma aplicação anfitriã

Desinstalar uma aplicação anfitriã WebView2 utiliza o processo de desinstalação padrão; este processo não é exclusivo do WebView2.

Durante a desinstalação, o instalador poderá ter de limpo qualquer UDF criado. Em alguns casos, poderá querer preservar a UDF.

Se criar a aplicação anfitriã, criar um instalador MSIX, instalar a aplicação anfitriã e, em seguida, executar a aplicação anfitriã, esta cria o UDF. No entanto, se desinstalar a aplicação anfitriã, isso não irá limpo automaticamente o UDF (porque o desinstalador protege e preserva os dados do utilizador), pelo que o seu processo de desinstalação tem de estar ciente dessa consideração.

Nas aplicações ClickOnce, é instalada numa única localização e, quando a sessão termina, elimina toda a árvore, pelo que o UDF é eliminado automaticamente. Isto deve-se ao funcionamento do ClickOnce, não devido ao funcionamento do WebView2.

Pastas de dados do utilizador persistentes se a sua aplicação não tiver utilizadores repetidos

Neste cenário, crie uma nova pasta de dados de utilizador (UDF) para cada utilizador e elimine o UDF anterior.

Eliminar pastas de dados do utilizador

A aplicação anfitriã ou o desinstalador pode eliminar a pasta de dados do utilizador (UDF). Poderá ter de eliminar UDFs por qualquer um dos seguintes motivos:

  • Se quiser desinstalar uma aplicação da Loja Windows em pacote. Neste caso, o Windows elimina automaticamente UDFs.

  • Se quiser limpo todo o histórico de dados de navegação. No entanto, veja primeiro os métodos de dados de navegação claros como uma abordagem mais fácil e flexível.

  • Se quiser recuperar de danos em dados.

  • Se quiser remover dados de sessão anteriores.

  • Se quiser alterar a localização da UDF. Se alterar a localização da UDF, a UDF anterior não será automaticamente limpa.

Terminar a sessão webView2 antes de eliminar o UDF

Para eliminar uma pasta de dados de utilizador (UDF), primeiro tem de terminar a sessão WebView2. Não pode eliminar um UDF se a sessão webView2 estiver ativa.

Aguarde pela saída dos processos do browser antes de eliminar o UDF

Se os ficheiros ainda estiverem a ser utilizados após o fecho da aplicação anfitriã WebView2, aguarde que os processos do browser saiam antes de eliminar a pasta de dados do utilizador (UDF).

Os ficheiros em UDFs ainda podem estar a ser utilizados depois de a aplicação WebView2 ser fechada. Nesta situação, aguarde que o processo do browser e todos os processos subordinados saiam antes de eliminar a UDF. Para monitorizar os processos para aguardar a saída dos mesmos, obtenha o ID de processo do processo do browser com a BrowserProcessId propriedade da instância da aplicação WebView2.

Partilhar pastas de dados do utilizador

As instâncias de controlo do WebView2 podem partilhar as mesmas pastas de dados de utilizador (UDFs), para fazer o seguinte:

Considere o seguinte ao partilhar UDFs:

  • Ao recriar controlos WebView2 para atualizar versões do browser com processadores de eventos add_NewBrowserVersionAvailable (Win32) ou NewBrowserVersionAvailable (.NET), a aplicação anfitriã tem de garantir que os processos do browser saem e fecham quaisquer controlos WebView2 que partilhem o mesmo UDF. Para obter o ID do processo do browser, utilize a BrowserProcessId propriedade do controlo WebView2.

Evite executar demasiadas pastas ao mesmo tempo

Para isolar diferentes partes da sua aplicação ou quando partilhar dados entre controlos WebView2 não é necessário, pode utilizar pastas de dados de utilizador diferentes (UDFs). Por exemplo, uma aplicação pode consistir em dois controlos WebView2, um para apresentar um anúncio e o outro para apresentar conteúdo da aplicação. Pode utilizar UDFs diferentes para cada controlo WebView2.

Cada processo de browser WebView2 consome memória e espaço em disco adicionais. Por conseguinte, evite executar um controlo WebView2 com demasiados UDFs diferentes ao mesmo tempo.

Em vez de vários UDFs, pode utilizar vários perfis para alcançar a separação do armazenamento de dados do browser para diferentes controlos WebView2. Cada perfil guarda os dados do browser numa pasta dedicada na mesma UDF partilhada. Veja Suportar múltiplos perfis numa única pasta de dados de utilizador.

Confira também