ASP.NET Core Razor Bibliotecas de classes (RCLs) com renderização estática do lado do servidor (SSR estático)

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 10 deste artigo.

Este artigo fornece orientações para autores de bibliotecas de componentes que consideram suporte para renderização estática do lado do servidor (SSR estático).

Blazorincentiva o desenvolvimento de um ecossistema de bibliotecas de componentes open-source e comerciais, formalmente chamadas Razor de bibliotecas de classes (RCLs). Os programadores podem também criar componentes reutilizáveis para partilhar componentes de forma privada entre aplicações dentro das suas próprias empresas. Idealmente, os componentes são desenvolvidos para serem compatíveis com o maior número possível de modelos de hospedagem e modos de renderização. O SSR estático introduz restrições adicionais que podem ser mais difíceis de suportar do que os modos de renderização interativa.

Compreender as capacidades e restrições do SSR estático

SSR estático é um modo em que os componentes funcionam quando o servidor lida com um pedido HTTP recebido. Blazor renderiza o componente como HTML, que está incluído na resposta. Uma vez enviada a resposta, o estado do componente do lado do servidor e do renderizador é descartado, pelo que tudo o que resta é HTML no navegador.

A vantagem deste modo é o alojamento mais barato e escalável, pois não são necessários recursos contínuos do servidor para manter o estado do componente, não é necessário manter uma ligação contínua entre browser e servidor, e não é necessário um payload WebAssembly no navegador.

Todos os componentes existentes ainda podem ser usados com SSR estático. No entanto, o custo deste modo é que os gestores de eventos, como @onclick†, não podem ser executados pelas seguintes razões:

• Não há código .NET no navegador para os executar.
• O servidor descartou imediatamente qualquer estado de componente e renderizador que fosse necessário para executar manipuladores de eventos ou para renderizar novamente as mesmas instâncias de componentes.

†Existe uma exceção especial para o @onsubmit gestor de eventos de formulários, que é sempre funcional, independentemente do modo de renderização.

Isto é equivalente ao comportamento dos componentes durante a pré-renderização, antes do Blazor circuito de SignalR ou antes de o runtime do WebAssembly .NET ser iniciado.

Para componentes cuja única função é produzir conteúdo DOM de somente leitura, estes comportamentos para SSR estático são completamente suficientes. No entanto, os autores das bibliotecas devem considerar que abordagem adotar ao incluir componentes interativos nas suas bibliotecas.

Opções para autores de componentes

Existem três abordagens principais:

• Não use comportamentos interativos (Básico)

  Para componentes cuja única função é produzir conteúdo DOM apenas de leitura, o programador não é obrigado a tomar qualquer ação especial. Estes componentes funcionam naturalmente com qualquer modo de renderização.

  Examples:

  • Um componente de "cartão de utilizador" que carrega dados correspondentes a uma pessoa e os renderiza numa interface estilizada com uma fotografia, cargo e outros detalhes.
  • Um componente de "vídeo" que funciona como um envoltório em torno do elemento HTML <video>, tornando-o mais conveniente de utilizar num componente Razor.

• Exigir renderização interativa (Básico)

  Pode optar por exigir que o seu componente seja usado apenas com renderização interativa. Isto limita a aplicabilidade do seu componente, mas significa que pode confiar livremente em manipuladores de eventos arbitrários. Mesmo assim, deve evitar declarar um específico @rendermode e permitir que o autor da aplicação que consome a sua biblioteca escolha um.

  Examples:

  • Um componente de edição de vídeo em que os utilizadores podem emendar e reordenar segmentos de vídeo. Mesmo que houvesse uma forma de representar estas operações de edição com botões HTML simples e publicações de formulários, a experiência do utilizador seria inaceitável sem uma verdadeira interatividade.
  • Um editor de documentos colaborativo que deve mostrar as atividades de outros utilizadores em tempo real.

• Use comportamentos interativos, mas projete para SSR estático e melhoria progressiva (Avançado)

  Muitos comportamentos interativos podem ser implementados apenas com capacidades HTML. Com um bom entendimento de HTML e CSS, muitas vezes consegues criar uma base útil de funcionalidades que funcionam com SSR estático. Ainda podes declarar gestores de eventos que implementam comportamentos mais avançados e opcionais, que só funcionam em modos de renderização interativa.

  Examples:

  • Um componente de grade. Em SSR estático, o componente pode apenas suportar a exibição de dados e a navegação entre páginas (implementado com <a> links). Quando usado com renderização interativa, o componente pode adicionar ordenação e filtragem em tempo real.
  • Um componente de tabset. Desde que a navegação entre separadores seja feita usando <a> links e o estado seja mantido apenas nos parâmetros de consulta URL, o componente pode funcionar sem @onclick.
  • Um componente avançado de upload de ficheiros. Sob SSR estático, o componente pode comportar-se como um <input type=file> nativo. Quando usado com renderização interativa, o componente também podia mostrar o progresso de upload.
  • Um ticker de ações. Sob SSR estático, o componente pode mostrar a cotação da ação no momento em que o HTML foi renderizado. Quando usado com renderização interativa, o componente pode então atualizar o preço da ação em tempo real.

Para qualquer uma destas estratégias, existe também a opção de implementar funcionalidades interativas com JavaScript.

Para escolher entre estas abordagens, os autores de componentes reutilizáveis Razor devem ponderar um compromisso entre custo e benefício. O teu componente é mais útil e tem uma base de utilizadores potencial mais ampla se suportar todos os modos de renderização, incluindo SSR estático. No entanto, é preciso mais trabalho para desenhar e implementar um componente que suporte e tire o melhor partido de cada modo de renderização.

Quando usar a @rendermode diretiva

Na maioria dos casos, os autores de componentes reutilizáveis não devem especificar um modo de renderização, mesmo quando é necessária interatividade. Isto porque o autor do componente não sabe se a aplicação permite suporte para InteractiveServer, InteractiveWebAssembly, ou ambos com InteractiveAuto. Ao não especificar um @rendermode, o autor do componente deixa a escolha ao desenvolvedor da aplicação.

Mesmo que o autor do componente considere que a interatividade é necessária, ainda podem existir casos em que o autor da aplicação considere suficiente usar apenas SSR estático. Por exemplo, um componente de mapa com interatividade de arrastar e zoom pode parecer requerer interatividade. No entanto, alguns cenários podem exigir apenas renderização de uma imagem estática do mapa e evitar funcionalidades de arrastar/zoom.

A única razão pela qual o autor de um componente reutilizável deve usar a @rendermode diretiva no seu componente é se a implementação estiver fundamentalmente acoplada a um modo de renderização específico e certamente causaria um erro se usada noutro modo. Considere um componente cujo propósito principal é interagir diretamente com o sistema operativo anfitrião usando APIs específicas para Windows ou Linux. Pode ser impossível usar tal componente no WebAssembly. Se sim, é razoável declarar @rendermode InteractiveServer para o componente.

Renderização em streaming

Os componentes reutilizáveis Razor podem declarar @attribute [StreamRendering] livremente para renderização em fluxo ([StreamRendering] atributos API). Isto resulta em atualizações incrementais da interface durante SSR estático. Como os mesmos padrões de carregamento de dados produzem atualizações incrementais da interface durante a renderização interativa, independentemente da presença do [StreamRendering] atributo, o componente pode comportar-se corretamente em todos os casos. Mesmo nos casos em que a transmissão de SSR estático é suprimida no servidor, o componente continua a renderizar corretamente o seu estado final.

Utilização de ligações entre modos de renderização

Componentes reutilizáveis Razor podem usar ligações e navegação aprimorada. As etiquetas HTML <a> devem produzir comportamentos equivalentes com ou sem um componente interativo Router e independentemente de a navegação melhorada estar ativada/desativada a um nível ancestral no DOM.

Utilização de formulários em vários modos de renderização

Componentes reutilizáveis Razor podem incluir formulários (ou <form> ou <EditForm>), pois estes podem ser implementados para funcionar de forma equivalente tanto em modos de renderização estáticos como interativos.

Considere o seguinte exemplo:

<EditForm Enhance FormName="NewProduct" Model="Model" OnValidSubmit="Save">
    <DataAnnotationsValidator />
    <ValidationSummary />

    <p><label>Name: <InputText @bind-Value="Model!.Name" /></label></p>

    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Product? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private async Task Save()
    {
        ...
    }
}

As EnhanceAPIs , FormName, e SupplyParameterFromFormAttribute são usadas apenas durante SSR estático e são ignoradas durante a renderização interativa. O formulário funciona corretamente tanto durante SSR interativo como estático.

Evite APIs específicas para SSR estático

HttpContext está disponível apenas durante SSR estático, por isso, na criação de componentes que funcionam em todos os modos de renderização, não confie em HttpContext. A HttpContext API também não faz sentido para usar durante a renderização interativa porque não há nenhum pedido HTTP ativo em funcionamento nesses momentos. Não faz sentido pensar em definir um código de estado HTTP ou escrever para a resposta HTTP.

Os componentes reutilizáveis estão livres para receber HttpContext quando disponíveis, da seguinte forma:

[CascadingParameter]
private HttpContext? Context { get; set; }

O valor é null durante a renderização interativa e só é definido durante a SSR (Renderização de Sites Estáticos) estática.

Em muitos casos, existem alternativas melhores do que usar HttpContext. Se precisares de saber a URL atual ou de fazer um redirecionamento, as APIs NavigationManager funcionam com todos os modos de renderização. Se precisar de saber o estado de autenticação do utilizador, use o serviço Blazor (AuthenticationStateProvider) em vez de usar AuthenticationStateProvider.