Partilhar via

Gerenciar pastas de dados do usuário

  • Artigo

A pasta de dados do usuário (UDF) é uma pasta armazenada no computador do usuário, que contém dados relacionados ao aplicativo host e Ao WebView2. Os aplicativos WebView2 usam pastas de dados do usuário para armazenar dados do navegador, como cookies, permissões e recursos armazenados em cache.

Terminologia:

Termo Definição
pasta de dados do usuário Uma pasta que o WebView2 cria para armazenar dados do navegador, como cookies, permissões e recursos armazenados em cache.
UDF A pasta de dados do usuário.
Localização UDF O caminho do diretório da pasta de dados do usuário.
local padrão da UDF O caminho de diretório padrão da pasta de dados do usuário. O caminho do diretório em que o WebView2 cria o UDF se você não especificar um local UDF personalizado.
Local UDF personalizado Um local personalizado para a pasta de dados do usuário. O caminho do diretório que seu aplicativo host WebView2 especifica onde o WebView2 criará a pasta de dados do usuário.

O WebView2 cria o UDF no local padrão da plataforma ou no local UDF personalizado que o aplicativo host especifica explicitamente.

Por padrão, o WebView2 cria um UDF no local padrão da plataforma específica. Isso funciona bem em algumas plataformas, mas não em outras. Se seu aplicativo tiver necessidades específicas, você poderá especificar um local UDF personalizado.

Locais de UDF personalizados adequados

Se você especificar um local UDF personalizado, ele deverá atender aos seguintes requisitos:

  • O local UDF personalizado deve ter permissões apropriadas de leitura/gravação para o runtime do aplicativo WebView2.

  • Evite armazenar configurações de usuário em uma unidade de rede. Isso pode resultar em desaceleração, falhas ou perda de dados.

Que tipo de dados são armazenados na UDF

Os aplicativos WebView2 usam UDFs (pastas de dados do usuário) para armazenar dados do navegador, como cookies, permissões e recursos armazenados em cache.

Tipos de dados Descrição
AllDomStorage Dados de armazenamento DOM, agora e futuro. Esse tipo de dados de navegação é inclusivo de FileSystems, IndexedDb, WebSql, . CacheStorage
AllProfile Dados de perfil que devem ser apagados para fazer com que pareça um novo perfil. Isso não exclui dados com escopo de conta como senhas, mas removerá o acesso aos dados com escopo da conta assinando a saída do usuário. Todos os dados de perfil, agora e futuro. Novos tipos de dados de perfil podem ser adicionados a esse tipo de dados no futuro. Esse tipo de dados de navegação inclui os tipos AllSitede dados , DiskCache, DownloadHistory, GeneralAutofill, PasswordAutosave, , BrowsingHistorye Settings.
AllSite Todos os dados do site, agora e futuro. Esse tipo de dados de navegação inclui os tipos AllDomStorage de dados e Cookies. Novos tipos de dados do site podem ser adicionados a esse tipo de dados no futuro.
BrowsingHistory Dados de histórico de navegação.
CacheStorage Dados armazenados pela API DOM do CacheStorage.
Cookies Dados de cookies HTTP.
DiskCache Cache de disco.
DownloadHistory Baixar dados de histórico.
FileSystems Dados de sistemas de arquivos.
GeneralAutofill Dados gerais do formulário de preenchimento automático. Isso exclui informações de senha e inclui informações como nomes, endereços de rua e email, números de telefone e entrada arbitrária. Inclui dados de pagamento.
IndexedDb Dados armazenados pelo recurso DOM IndexedDB.
LocalStorage Dados armazenados pela API do DOM localStorage.
PasswordAutosave Senha desativar dados automaticamente.
Settings Configurações de dados.
WebSql Dados armazenados pela API DOM do banco de dados SQL Web.

Os tipos de dados acima são listados como membros de enumeração no CoreWebView2BrowsingDataKinds Enum.

Como e quando a UDF é criada

A pasta de dados do usuário (UDF) é criada para seu aplicativo host WebView2 pelo controle WebView2.

O UDF é criado no local padrão da UDF para a plataforma ou se o aplicativo host especificar um local UDF personalizado, o UDF será criado no local UDF personalizado.

O UDF será criado na inicialização do aplicativo host WebView2, se o UDF não existir.

Quantos UDFs são criados?

Cada instância de um controle WebView2 está associada a uma UDF (pasta de dados do usuário).

Cada sessão do WebView2 deve ter um UDF. Há apenas 1 UDF ativo por sessão WebView2.

Há pelo menos uma sessão UDF por aplicativo WebView2. É possível que seu aplicativo host os sobreponha, especificando um local UDF personalizado. Ou você pode ter um UDF por computador. Isso depende de como seu aplicativo host configura a UDF.

Uma UDF pode ser por usuário, se o aplicativo foi instalado por usuário. Se o aplicativo host estiver instalado por usuário, cada UDF será exclusivo para um usuário, se não for especificado de outra forma.

Como mover a UDF

Para mover uma pasta de dados de usuário (UDF):

  1. Desligue todas as sessões do WebView2.

  2. Inicie uma nova sessão de aplicativo host do WebView2, especificando um novo local UDF personalizado.

O local padrão da UDF

O local da UDF (pasta de dados do usuário) padrão varia de acordo com a plataforma.

Nesta plataforma, o local padrão da UDF é o diretório em que o executável do aplicativo (.exe) está em execução. O UDF padrão é o caminho executável (exe) do seu aplicativo + .WebView2. O nome do arquivo da UDF é o caminho executável (exe) do seu aplicativo + .WebView2.

Por exemplo, se você tiver executado D:\WebView2App\WebView2.exe, uma pasta UDF será criada: D:\WebView2App\WebView2.exe.WebView2\. Como outro exemplo: WebView2APISample.exe.WebView2\.

Você deve usar o local de UDF padrão ou personalizado?

Na maioria dos casos, você deve especificar um local UDF personalizado, em vez de usar o local padrão da UDF. Isso garante que o controle WebView2 tenha acesso a Gravação para que o controle WebView2 seja capaz de criar o UDF e, em seguida, gravar nele. Confira a seção "Especificando um local UDF personalizado" abaixo.

Embalagem:

A embalagem do WIN32 MSIX é autônoma .exe.

Especificando um local UDF personalizado

Como especificar uma localização de UDF (pasta de dados de usuário) personalizada varia de acordo com a plataforma.

Nesta plataforma, na maioria dos casos, você deve especificar um local UDF personalizado, em vez de usar o local padrão da UDF. Isso garante que o controle WebView2 tenha acesso a Gravação para que o controle WebView2 seja capaz de criar o UDF e, em seguida, gravar nele.

Você deve especificar a mesma pasta em que todos os outros dados do aplicativo são armazenados.

Como especificar um local UDF personalizado:

Use ICoreWebView2Environment e o userDataFolder parâmetro. Mas use 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, código, consulte o arquivo ou apropriado .cpp para Win32, próximo a WebView2Samples repositório > WebView2APISample..cs

Onde os dados do navegador são armazenados na UDF:

Após a criação da sessão e do UDF, os dados do navegador do controle WebView2 são armazenados em uma subpasta de userDataFolder.

Por que você deve usar um local UDF personalizado nesta plataforma:

Se você não especificar um local UDF personalizado, o local padrão poderá produzir uma falha em tempo de execução, se estiver usando tecnologias do instalador, porque as tecnologias do instalador colocam o aplicativo e, portanto, a UDF em uma área protegida do sistema de arquivos, onde o WebView2 não é capaz de criar o UDF e, portanto, a criação de UDF geralmente falhará. O WebView2 gerará um erro para que seu aplicativo host saiba que a UDF não pode ser criada nesse local.

Se o aplicativo host estiver em execução a partir de um local ao qual o usuário não tem acesso ao Write, o WebView2 não poderá criar o UDF e você receberá um erro de runtime durante a inicialização do WebView2.

Recuperando a localização da UDF

Para descobrir como a localização da UDF (pasta de dados do usuário) foi definida, use a UserDataFolder propriedade. Essa propriedade somente leitura retorna o local da UDF para o aplicativo WebView2.

Motivos pelos quais você pode querer ler o local da UDF:

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

  • Se você quiser excluir a UDF.

Use o getter da propriedade Win32 ICoreWebView2Environment7.get_UserDataFolder. Essa página referência de API contém código de exemplo mostrando 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, confira os exemplos do Win32 no repositório WebView2Samples.

Limpar espaço na UDF

Em vez de excluir a UDF (pasta de dados do usuário), desmarque os dados de navegação da UDF. Por exemplo, desmarque os dados e o histórico do usuário quando um usuário sair.

Consulte Limpar dados de navegação da pasta de dados do usuário.

Manipulação de mensagens de erro

Se a UDF (pasta de dados do usuário) não tiver permissões de gravação, as seguintes cadeias de caracteres de mensagem de erro poderão ser retornadas:

  • 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 o local da pasta de dados do usuário ser o local padrão da UDF ou um local UDF personalizado.

Se não houver memória insuficiente ou o runtime do Microsoft Edge não puder ser iniciado ou o WebView2 Runtime não for encontrado, cadeias de caracteres de mensagem de erro semelhantes às seguintes poderão ser retornadas:

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

Adicione código, como try/catch código, para lidar com esses erros. Esses erros tendem a ser erros fatais dos quais você não pode se recuperar, portanto try/catch , impedirá que o aplicativo falhe. Em seguida, você poderá detectar a falha e fechar o aplicativo normalmente. Alguns erros são irrecuperáveis, como Access Denied ao tentar usar uma pasta de dados de usuário à qual você não tem permissões de gravação.

As cadeias de caracteres de mensagem de erro são exibidas em uma caixa de diálogo.

Se deve persistir pastas de dados do usuário em vários cenários

Seu aplicativo host controla o tempo de vida da UDF (pasta de dados do usuário). Se o aplicativo reutiliza os dados do usuário de sessões de aplicativo, considere salvar (ou seja, não excluir) as UDFs.

Se seu aplicativo não reutilizar dados do usuário de sessões de aplicativo, você poderá excluir a 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 excluir a UDF.

Persistindo pastas de dados do usuário se o mesmo usuário usar seu aplicativo repetidamente, e o conteúdo da Web do aplicativo depender dos dados do usuário

Nesse cenário, não exclua explicitamente a pasta de dados do usuário (UDF); persista os dados.

Persistindo pastas de dados do usuário se vários usuários usarem seu aplicativo repetidamente

Se vários usuários usarem seu aplicativo repetidamente, você deverá criar uma nova UDF (pasta de dados de usuário) para cada novo usuário e salvar a UDF de cada usuário.

O controle WebView2 cria um novo UDF para cada novo usuário. O controle WebView2 cria um UDF por sessão. Se houver várias sessões do WebView2, o controle WebView2 criará vários UDFs. Normalmente, se o aplicativo host tiver mais de uma instância de controle WebView2, o aplicativo host deverá apontar todas as instâncias do WebView2 para a mesma UDF.

Cada aplicativo host que tem uma instância de controle Do WebView2 terá sua própria UDF. Seu aplicativo host pode fazer com que cada UDF aponte para o mesmo lugar.

Se o aplicativo host for para vários usuários, você provavelmente deverá criar um UDF por usuário. Se seu aplicativo foi instalado por usuário, é assim que ele funciona.

Se você iniciar duas cópias do aplicativo host, elas usarão a mesma UDF.

  • Para aplicativos host Win32, o UDF não é removido automaticamente.
  • Para aplicativos host .NET (WPF & WinForms), o UDF não é removido automaticamente.
  • Para aplicativos host ClickOnce, o UDF é removido automaticamente.
  • Para aplicativos host do WinUI 2 (UWP), o UDF não é removido automaticamente.
  • Para aplicativos host WinUI 3, o UDF não é removido automaticamente.

Desinstalar um aplicativo host

A desinstalação de um aplicativo host do WebView2 usa o processo de desinstalação padrão; esse processo não é exclusivo do WebView2.

Durante a desinstalação, o instalador pode precisar limpo qualquer UDF criado. Em alguns casos, talvez você queira preservar a UDF.

Se você criar o aplicativo host, criar um instalador MSIX, instalar o aplicativo host e executar o aplicativo host, ele criará a UDF. Mas, se você desinstalar o aplicativo host, isso não limpo automaticamente a UDF (porque o desinstalador protege e preserva os dados do usuário), portanto, o processo de desinstalação precisa estar ciente dessa consideração.

Em aplicativos ClickOnce, ele é instalado em um único local e, quando a sessão termina, exclui a árvore inteira, de modo que a UDF seja excluída automaticamente. Isso ocorre por causa de como o ClickOnce funciona, não por causa de como o WebView2 funciona.

Persistindo pastas de dados do usuário se seu aplicativo não tiver usuários repetidos

Nesse cenário, crie uma nova UDF (pasta de dados de usuário) para cada usuário e exclua a UDF anterior.

Excluindo pastas de dados do usuário

Seu aplicativo host ou o desinstalador podem excluir a UDF (pasta de dados do usuário). Talvez seja necessário excluir UDFs por qualquer um dos seguintes motivos:

  • Se você quiser desinstalar um aplicativo empacotado da Windows Store. Nesse caso, o Windows exclui UDFs automaticamente.

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

  • Se você quiser se recuperar da corrupção de dados.

  • Se você quiser remover dados de sessão anteriores.

  • Se você quiser alterar o local da UDF. Se você alterar o local da UDF, a UDF anterior não será limpa automaticamente.

Encerrar a sessão do WebView2 antes de excluir a UDF

Para excluir uma UDF (pasta de dados do usuário), primeiro você deve encerrar a sessão do WebView2. Não é possível excluir um UDF se a sessão WebView2 estiver ativa no momento.

Aguarde a saída dos processos do navegador antes de excluir a UDF

Se os arquivos ainda estiverem em uso após o fechamento do aplicativo host do WebView2, aguarde a saída dos processos do navegador antes de excluir a UDF (pasta de dados do usuário).

Os arquivos em UDFs ainda podem estar em uso depois que o aplicativo WebView2 for fechado. Nessa situação, aguarde a saída do processo do navegador e todos os processos filho antes de excluir a UDF. Para monitorar os processos para aguardar a saída deles, recupere a ID do processo do navegador usando a BrowserProcessId propriedade da instância do aplicativo WebView2.

Compartilhamento de pastas de dados do usuário

As instâncias de controle do WebView2 podem compartilhar as mesmas UDFs (pastas de dados do usuário) para fazer o seguinte:

Considere o seguinte ao compartilhar UDFs:

  • Ao recriar controles WebView2 para atualizar versões do navegador usando manipuladores de eventos do add_NewBrowserVersionAvailable (Win32) ou eventos NewBrowserVersionAvailable (.NET), seu aplicativo host deve garantir que os processos do navegador saiam e fechem todos os controles WebView2 que compartilhem o mesmo UDF. Para recuperar a ID do processo do navegador, use a BrowserProcessId propriedade do controle WebView2.

Evite executar muitas pastas ao mesmo tempo

Para isolar diferentes partes do aplicativo ou quando não for necessário compartilhar dados entre controles WebView2, você pode usar diferentes pastas de dados de usuário (UDFs). Por exemplo, um aplicativo pode consistir em dois controles WebView2, um para exibir um anúncio e outro para exibir conteúdo do aplicativo. Você pode usar UDFs diferentes para cada controle WebView2.

Cada processo do navegador WebView2 consome espaço adicional em memória e disco. Portanto, evite executar um controle WebView2 com muitos UDFs diferentes ao mesmo tempo.

Em vez de vários UDFs, você pode usar vários perfis para obter a separação de armazenamento de dados do navegador para diferentes controles WebView2. Cada perfil salva dados do navegador em uma pasta dedicada na mesma UDF compartilhada. Consulte Suporte a vários perfis em uma única pasta de dados do usuário.

Confira também