Gerenciamento de estado Blazor do ASP.NET Core

O lado do servidor Blazor é uma estrutura do aplicativo com estado. Na maioria das vezes, o aplicativo mantém uma conexão com o servidor. O estado do usuário é retido na memória do servidor em um circuito.

Os exemplos de estado do usuário retido em um circuito incluem:

• A hierarquia das instâncias de componente e a saída de renderização mais recente na interface do usuário renderizada.
• Os valores de campos e as propriedades nas instâncias de componente.
• Os dados retidos nas instâncias de serviço de DI (injeção de dependência) que têm como escopo o circuito.

O estado do usuário também pode ser encontrado em variáveis JavaScript no conjunto de memória do navegador por meio de chamadas de interoperabilidade do JavaScript .

Se um usuário tiver uma perda temporária de conexão de rede, Blazor tentará reconectar o usuário ao circuito original com o estado original. No entanto, reconectar um usuário ao circuito original na memória do servidor nem sempre é possível:

• O servidor não pode reter um circuito desconectado para sempre. O servidor deve liberar um circuito desconectado após um tempo limite ou quando o servidor estiver sob pressão de memória.
• Em ambientes de implantação com balanceamento de carga de vários servidores, os servidores individuais podem falhar ou ser removidos automaticamente, quando não forem mais necessários para lidar com o volume geral de solicitações. As solicitações de processamento do servidor original para um usuário podem ficar indisponíveis, quando o usuário tenta se reconectar.
• O usuário pode fechar e reabrir o navegador ou recarregar a página, o que remove qualquer estado mantido na memória do navegador. Por exemplo, os valores de variável JavaScript definidos por meio de chamadas de interoperabilidade do JavaScript são perdidos.

Quando um usuário não pode ser reconectado ao circuito original, o usuário recebe um novo circuito com um estado vazio. Isso é equivalente a fechar e reabrir um aplicativo de desktop.

Persistir o estado entre circuitos

Em geral, mantenha o estado entre circuitos em que os usuários estão criando dados ativamente, não simplesmente lendo dados que já existem.

Para preservar o estado entre circuitos, o aplicativo deve persistir os dados em algum outro local de armazenamento que não seja a memória do servidor. A persistência de estado não é automática. Você deve executar etapas ao desenvolver o aplicativo para implementar a persistência de dados com estado.

A persistência de dados normalmente só é necessária para o estado de alto valor que os usuários se esforçaram para criar. Nos exemplos a seguir, persistir o estado economiza tempo ou ajuda em atividades comerciais:

• Formulários da Web de várias etapas: demora para um usuário inserir dados novamente em várias etapas concluídas de um formulário da Web de várias etapas, se o estado for perdido. Um usuário perderá o estado nesse cenário, se sair do formulário e retornar mais tarde.
• Carrinhos de compras: qualquer componente comercialmente importante de um aplicativo que representa uma possível receita pode ser mantido. Um usuário que perde o estado e, portanto, o carrinho de compras, pode comprar menos produtos ou serviços quando retornar ao site mais tarde.

Um aplicativo só pode persistir o estado do aplicativo. As interfaces do usuário não podem ser persistidas, como instâncias de componente e as árvores de renderização. Os componentes e as árvores de renderização geralmente não são serializáveis. Para persistir o estado da interface do usuário, como os nós expandidos de um controle de exibição de árvore, o aplicativo deve usar o código personalizado para modelar o comportamento do estado da interface do usuário como estado serializável do aplicativo.

Onde persistir o estado

Existem locais comuns para persistir o estado:

• Armazenamento do lado do servidor
• URL
• Armazenamento do navegador
• Serviço de contêiner de estado na memória

Armazenamento do lado do servidor

Para persistência de dados permanente que abrange vários usuários e dispositivos, o aplicativo pode usar o armazenamento do lado do servidor. As opções incluem:

• Armazenamento de Blobs
• Armazenamento de par chave-valor
• Banco de dados relacional
• Armazenamento de tabela

Depois que os dados são salvos, o estado do usuário é retido e disponibilizado em qualquer novo circuito.

Para obter mais informações sobre as opções de armazenamento de dados do Azure, confira o seguinte:

• Bancos de dados do Azure
• Documentação do Armazenamento do Azure

URL

Para dados transitórios que representam o estado de navegação, modele os dados como parte da URL. Os exemplos de estado do usuário modelados na URL incluem:

• A ID de uma entidade exibida.
• O número da página atual em uma grade paginada.

O conteúdo da barra de endereços do navegador é retido:

• Se o usuário recarregar manualmente a página.
• Se o servidor Web ficar indisponível e o usuário for forçado a recarregar a página para se conectar a um servidor diferente.

Para obter informações sobre como definir padrões de URL com a diretiva @page, confira Roteamento e navegação Blazor do ASP.NET Core.

Armazenamento do navegador

Para dados transitórios que o usuário está criando ativamente, um local de armazenamento comumente usado é as coleções localStorage e sessionStorage do navegador:

• localStorage tem como escopo a janela do navegador. Se o usuário recarregar a página ou fechar e reabrir o navegador, o estado persistirá. Se o usuário abrir várias guias do navegador, o estado será compartilhado entre as guias. Os dados persistem em localStorage até serem explicitamente limpos.
• sessionStorage tem como escopo a guia do navegador. Se o usuário recarregar a guia, o estado será mantido. Se o usuário fechar a guia ou o navegador, o estado será perdido. Se o usuário abrir várias guias do navegador, cada guia terá sua própria versão independente dos dados.

Em geral, sessionStorage é mais seguro de usar. sessionStorage evita o risco de um usuário abrir várias guias e encontrar o seguinte:

• Bugs no armazenamento de estado entre guias.
• Comportamento confuso quando uma guia substitui o estado de outras guias.

localStorage é a melhor opção se o aplicativo precisar manter o estado ao fechar e reabrir o navegador.

Advertências para usar o armazenamento do navegador:

• Semelhante ao uso de um banco de dados do lado do servidor, o carregamento e o salvamento de dados são assíncronos.
• A página solicitada não existe no navegador durante a pré-renderização, portanto, o armazenamento local fica indisponível durante a pré-renderização.
• O armazenamento de alguns kilobytes de dados é um motivo razoável para persistir em aplicativos do lado do servidor Blazor. Além de alguns quilobytes, você deve considerar as implicações de desempenho, pois os dados são carregados e salvos em toda a rede.
• Os usuários podem exibir ou adulterar os dados. A Proteção de Dados do ASP.NET Core pode mitigar o risco. Por exemplo, o Armazenamento de Navegador Protegido do ASP.NET Core usa a Proteção de Dados do ASP.NET Core.

Os pacotes NuGet de terceiros fornecem APIs para trabalhar com localStorage e sessionStorage. Vale a pena considerar a escolha de um pacote que usa de forma transparente a Proteção de Dados do ASP.NET Core. A Proteção de Dados criptografa os dados armazenados e reduz o possível risco de adulteração de dados armazenados. Se os dados serializados por JSON forem armazenados em texto sem formatação, os usuários poderão vê-los e modificá-los usando as ferramentas de desenvolvedor do navegador. Proteger dados triviais não é um problema. Por exemplo, ler ou modificar a cor armazenada de um elemento de interface do usuário não é um risco de segurança significativo para o usuário ou para a organização. Evite permitir que os usuários inspecionem ou violem dados confidenciais.

Armazenamento de Navegador Protegido do ASP.NET Core

O Armazenamento de Navegador Protegido do ASP.NET Core utiliza a Proteção de Dados do ASP.NET Core para localStorage e sessionStorage.

Salvar e carregar dados em um componente

Em qualquer componente que exija carregar ou salvar dados no armazenamento do navegador, use a diretiva @inject para injetar uma instância de uma das seguintes opções:

• ProtectedLocalStorage
• ProtectedSessionStorage

A escolha depende do local de armazenamento do navegador que você deseja usar. No exemplo a seguir, sessionStorage é usado:

@using Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage
@inject ProtectedSessionStorage ProtectedSessionStore

@using Microsoft.AspNetCore.ProtectedBrowserStorage
@inject ProtectedSessionStorage ProtectedSessionStore

A diretiva @using pode ser colocada no arquivo do aplicativo _Imports.razor, em vez de no componente. O uso do arquivo _Imports.razor disponibiliza o namespace para segmentos maiores do aplicativo ou de todo o aplicativo.

Para persistir o valor currentCount no componente Counter de um aplicativo com base no modelo de projeto Blazor, modifique o método IncrementCount para usar ProtectedSessionStore.SetAsync:

private async Task IncrementCount()
{
    currentCount++;
    await ProtectedSessionStore.SetAsync("count", currentCount);
}

Em aplicativos maiores e mais realistas, o armazenamento de campos individuais é um cenário improvável. Os aplicativos são mais propensos a armazenar objetos de modelo inteiros que incluem o estado complexo. ProtectedSessionStore serializa e desserializa dados JSON automaticamente para armazenar objetos de estado complexos.

No exemplo de código anterior, os dados currentCount são armazenados como sessionStorage['count'] no navegador do usuário. Os dados não são armazenados em texto sem formatação, mas sim protegidos usando a Proteção de Dados do ASP.NET Core. Os dados criptografados podem ser inspecionados, se sessionStorage['count'] for avaliado no console do desenvolvedor do navegador.

Para recuperar os dados currentCount, caso o usuário retorne ao componente Counter posteriormente, incluindo se o usuário estiver em um novo circuito, use ProtectedSessionStore.GetAsync:

protected override async Task OnInitializedAsync()
{
    var result = await ProtectedSessionStore.GetAsync<int>("count");
    currentCount = result.Success ? result.Value : 0;
}

protected override async Task OnInitializedAsync()
{
    currentCount = await ProtectedSessionStore.GetAsync<int>("count");
}

Se os parâmetros do componente incluírem o estado de navegação, chame ProtectedSessionStore.GetAsync e atribua um resultado não null em OnParametersSetAsync, não em OnInitializedAsync. OnInitializedAsync é chamado apenas uma vez, quando o componente é instanciado pela primeira vez. OnInitializedAsync não será chamado novamente mais tarde, se o usuário navegar para uma URL diferente enquanto permanecer na mesma página. Para saber mais, consulte Ciclo de vida de renderização de Razor no ASP.NET Core.

Manipular o estado de carregamento

Como o armazenamento do navegador é acessado de forma assíncrona em uma conexão de rede, há sempre um período antes que os dados sejam carregados e disponibilizados para um componente. Para obter os melhores resultados, renderize uma mensagem enquanto o carregamento estiver em andamento em vez de exibir dados em branco ou padrão.

private int? currentCount;

@if (currentCount.HasValue)
{
    <p>Current count: <strong>@currentCount</strong></p>
    <button @onclick="IncrementCount">Increment</button>
}
else
{
    <p>Loading...</p>
}

Manipular pré-renderização

Durante a pré-renderização:

• Uma conexão interativa com o navegador do usuário não existe.
• O navegador ainda não tem uma página na qual possa executar o código JavaScript.

localStorage ou sessionStorage não fica disponível durante a pré-renderização. Se o componente tentar interagir com o armazenamento, um erro será gerado explicando que as chamadas de interoperabilidade do JavaScript não podem ser emitidas, pois o componente está sendo pré-renderizado.

Uma maneira de resolver o erro é desabilitar a pré-renderização. Essa geralmente é a melhor opção, se o aplicativo faz uso intensivo do armazenamento baseado em navegador. A pré-renderização adiciona complexidade e não favorece o aplicativo, pois o aplicativo não pode pré-renderizar o conteúdo útil até que localStorage ou sessionStorage esteja disponível.

<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />

<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />

<component type="typeof(App)" render-mode="Server" />

A pré-renderização pode ser útil para outras páginas que não usam localStorage ou sessionStorage. Para reter a pré-renderização, adie a operação de carregamento até que o navegador esteja conectado ao circuito. Veja a seguir um exemplo para armazenar um valor de contador:

@using Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage
@inject ProtectedLocalStorage ProtectedLocalStore

@if (isConnected)
{
    <p>Current count: <strong>@currentCount</strong></p>
    <button @onclick="IncrementCount">Increment</button>
}
else
{
    <p>Loading...</p>
}

@code {
    private int currentCount;
    private bool isConnected;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            isConnected = true;
            await LoadStateAsync();
            StateHasChanged();
        }
    }

    private async Task LoadStateAsync()
    {
        var result = await ProtectedLocalStore.GetAsync<int>("count");
        currentCount = result.Success ? result.Value : 0;
    }

    private async Task IncrementCount()
    {
        currentCount++;
        await ProtectedLocalStore.SetAsync("count", currentCount);
    }
}

@using Microsoft.AspNetCore.ProtectedBrowserStorage
@inject ProtectedLocalStorage ProtectedLocalStore

@if (isConnected)
{
    <p>Current count: <strong>@currentCount</strong></p>
    <button @onclick="IncrementCount">Increment</button>
}
else
{
    <p>Loading...</p>
}

@code {
    private int currentCount = 0;
    private bool isConnected = false;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            isConnected = true;
            await LoadStateAsync();
            StateHasChanged();
        }
    }

    private async Task LoadStateAsync()
    {
        currentCount = await ProtectedLocalStore.GetAsync<int>("count");
    }

    private async Task IncrementCount()
    {
        currentCount++;
        await ProtectedLocalStore.SetAsync("count", currentCount);
    }
}

Fatorar a preservação do estado para um local comum

Se muitos componentes dependerem do armazenamento com base no navegador, implementar o código do provedor de estado muitas vezes criará duplicação de código. Uma opção para evitar a duplicação de código é criar um componente pai do provedor de estado que encapsula a lógica do provedor de estado. Os componentes filho podem trabalhar com dados persistentes, sem levar em conta o mecanismo de persistência de estado.

No exemplo a seguir de um componente CounterStateProvider, os dados do contador são persistidos em sessionStorage:

@using Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage
@inject ProtectedSessionStorage ProtectedSessionStore

@if (isLoaded)
{
    <CascadingValue Value="this">
        @ChildContent
    </CascadingValue>
}
else
{
    <p>Loading...</p>
}

@code {
    private bool isLoaded;

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    public int CurrentCount { get; set; }

    protected override async Task OnInitializedAsync()
    {
        var result = await ProtectedSessionStore.GetAsync<int>("count");
        CurrentCount = result.Success ? result.Value : 0;
        isLoaded = true;
    }

    public async Task SaveChangesAsync()
    {
        await ProtectedSessionStore.SetAsync("count", CurrentCount);
    }
}

@using Microsoft.AspNetCore.ProtectedBrowserStorage
@inject ProtectedSessionStorage ProtectedSessionStore

@if (isLoaded)
{
    <CascadingValue Value="this">
        @ChildContent
    </CascadingValue>
}
else
{
    <p>Loading...</p>
}

@code {
    private bool isLoaded;

    [Parameter]
    public RenderFragment ChildContent { get; set; }

    public int CurrentCount { get; set; }

    protected override async Task OnInitializedAsync()
    {
        CurrentCount = await ProtectedSessionStore.GetAsync<int>("count");
        isLoaded = true;
    }

    public async Task SaveChangesAsync()
    {
        await ProtectedSessionStore.SetAsync("count", CurrentCount);
    }
}

O componente CounterStateProvider manipula a fase de carregamento não renderizando o conteúdo filho até que o carregamento de estado seja concluído.

<Routes @rendermode="InteractiveServer" />

<CounterStateProvider>
    <Router ...>
        ...
    </Router>
</CounterStateProvider>

Os componentes encapsulados recebem e podem modificar o estado do contador persistente. O seguinte componente Counter implementa o padrão:

@page "/counter"

<p>Current count: <strong>@CounterStateProvider?.CurrentCount</strong></p>
<button @onclick="IncrementCount">Increment</button>

@code {
    [CascadingParameter]
    private CounterStateProvider? CounterStateProvider { get; set; }

    private async Task IncrementCount()
    {
        if (CounterStateProvider is not null)
        {
            CounterStateProvider.CurrentCount++;
            await CounterStateProvider.SaveChangesAsync();
        }
    }
}

O componente anterior não é necessário para interagir com ProtectedBrowserStorage, nem lida com uma fase de "carregamento".

Para lidar com a pré-renderização, conforme descrito anteriormente, CounterStateProvider pode ser alterado para que todos os componentes que consomem os dados do contador funcionem automaticamente com a pré-renderização. Para obter mais informações, confira a seção Manipular pré-renderização.

Em geral, o padrão de componente pai do provedor de estado é recomendado:

• Para consumir o estado em muitos componentes.
• Se houver apenas um objeto de estado de nível superior para persistir.

Para persistir muitos objetos de estado diferentes e consumir diferentes subconjuntos de objetos em locais diferentes, é melhor evitar persistir o estado globalmente.

O estado do usuário criado em um aplicativo Blazor WebAssembly é retido na memória do navegador.

Os exemplos de estado do usuário retido na memória do navegador incluem:

• A hierarquia das instâncias de componente e a saída de renderização mais recente na interface do usuário renderizada.
• Os valores de campos e as propriedades nas instâncias de componente.
• Os dados retidos nas instâncias de serviço de DI (injeção de dependência).
• Valores definidos por meio de chamadas de interoperabilidade do JavaScript.

Quando um usuário fecha e reabre o navegador ou recarrega a página, o estado do usuário mantido na memória do navegador é perdido.

Persistir o estado entre sessões do navegador

Em geral, mantenha o estado entre sessões do navegador em que os usuários estão criando dados ativamente, não simplesmente lendo dados que já existem.

Para preservar o estado entre sessões do navegador, o aplicativo deve persistir os dados em algum outro local de armazenamento que não seja a memória do navegador. A persistência de estado não é automática. Você deve executar etapas ao desenvolver o aplicativo para implementar a persistência de dados com estado.

A persistência de dados normalmente só é necessária para o estado de alto valor que os usuários se esforçaram para criar. Nos exemplos a seguir, persistir o estado economiza tempo ou ajuda em atividades comerciais:

• Formulários da Web de várias etapas: demora para um usuário inserir dados novamente em várias etapas concluídas de um formulário da Web de várias etapas, se o estado for perdido. Um usuário perderá o estado nesse cenário, se sair do formulário e retornar mais tarde.
• Carrinhos de compras: qualquer componente comercialmente importante de um aplicativo que representa uma possível receita pode ser mantido. Um usuário que perde o estado e, portanto, o carrinho de compras, pode comprar menos produtos ou serviços quando retornar ao site mais tarde.

Um aplicativo só pode persistir o estado do aplicativo. As interfaces do usuário não podem ser persistidas, como instâncias de componente e as árvores de renderização. Os componentes e as árvores de renderização geralmente não são serializáveis. Para persistir o estado da interface do usuário, como os nós expandidos de um controle de exibição de árvore, o aplicativo deve usar o código personalizado para modelar o comportamento do estado da interface do usuário como estado serializável do aplicativo.

Onde persistir o estado

Existem locais comuns para persistir o estado:

• Armazenamento do lado do servidor
• URL
• Armazenamento do navegador
• Serviço de contêiner de estado na memória

Armazenamento do lado do servidor

Para persistência de dados permanente que abrange vários usuários e dispositivos, o aplicativo pode usar o armazenamento do lado do servidor independente, acessado por meio de uma API Web. As opções incluem:

• Armazenamento de Blobs
• Armazenamento de par chave-valor
• Banco de dados relacional
• Armazenamento de tabela

Depois que os dados são salvos, o estado do usuário é retido e disponibilizado em qualquer nova sessão do navegador.

Como os aplicativos Blazor WebAssembly são executados inteiramente no navegador do usuário, eles exigem medidas adicionais para acessar sistemas externos seguros, como serviços de armazenamento e bancos de dados. Aplicativos Blazor WebAssembly são protegidos da mesma maneira que SPAs (aplicativos de página única). Normalmente, um aplicativo autentica um usuário por meio do OIDC (OAuth/OpenID Connect) e interage com serviços de armazenamento e bancos de dados por meio de chamadas à API Web para um aplicativo do lado do servidor. O aplicativo do lado do servidor media a transferência de dados entre o aplicativo Blazor WebAssembly e o serviço de armazenamento ou o banco de dados. O aplicativo Blazor WebAssembly mantém uma conexão efêmera com o aplicativo do lado do servidor, enquanto o aplicativo do lado do servidor tem uma conexão persistente com o armazenamento.

Para saber mais, consulte os recursos a seguir:

• Chamar uma API Web a partir de um aplicativo Blazor do ASP.NET Core
• Blazor WebAssembly do ASP.NET Core Seguro
• Artigos de BlazorSegurança e Identity

Para obter mais informações sobre as opções de armazenamento de dados do Azure, confira o seguinte:

• Bancos de dados do Azure
• Documentação do Armazenamento do Azure

URL

Para dados transitórios que representam o estado de navegação, modele os dados como parte da URL. Os exemplos de estado do usuário modelados na URL incluem:

• A ID de uma entidade exibida.
• O número da página atual em uma grade paginada.

O conteúdo da barra de endereços do navegador será retido, se o usuário recarregar manualmente a página.

Para obter informações sobre como definir padrões de URL com a diretiva @page, confira Roteamento e navegação Blazor do ASP.NET Core.

Armazenamento do navegador

Para dados transitórios que o usuário está criando ativamente, um local de armazenamento comumente usado é as coleções localStorage e sessionStorage do navegador:

• localStorage tem como escopo a janela do navegador. Se o usuário recarregar a página ou fechar e reabrir o navegador, o estado persistirá. Se o usuário abrir várias guias do navegador, o estado será compartilhado entre as guias. Os dados persistem em localStorage até serem explicitamente limpos.
• sessionStorage tem como escopo a guia do navegador. Se o usuário recarregar a guia, o estado será mantido. Se o usuário fechar a guia ou o navegador, o estado será perdido. Se o usuário abrir várias guias do navegador, cada guia terá sua própria versão independente dos dados.

Em geral, sessionStorage é mais seguro de usar. sessionStorage evita o risco de um usuário abrir várias guias e encontrar o seguinte:

• Bugs no armazenamento de estado entre guias.
• Comportamento confuso quando uma guia substitui o estado de outras guias.

localStorage é a melhor opção se o aplicativo precisar manter o estado ao fechar e reabrir o navegador.