Modelos de Hospedagem de Blazor ASP.NET CoreASP.NET Core Blazor hosting models

Por Daniel RothBy Daniel Roth

Importante

Webassembly mais incrivelmente em visualizaçãoBlazor WebAssembly in preview

Há suporte para o servidor mais incrivelmente no ASP.NET Core 3,0.Blazor Server is supported in ASP.NET Core 3.0. Webassembly mais incrivelmente está em versão prévia para ASP.NET Core 3,1.Blazor WebAssembly is in preview for ASP.NET Core 3.1.

Blazor é uma estrutura da Web criada para executar o lado do cliente no navegador em um tempo de execução .NET baseado em Webassembly( Blazor Webassembly) ou no lado do servidor no ASP.NET Core ( Blazor Server). is a web framework designed to run client-side in the browser on a WebAssembly-based .NET runtime (Blazor WebAssembly) or server-side in ASP.NET Core (Blazor Server). Independentemente do modelo de hospedagem, os modelos de aplicativo e componente são os mesmos.Regardless of the hosting model, the app and component models are the same.

Para criar um projeto para os modelos de hospedagem descritos neste artigo, consulte Get started with ASP.NET Core Blazor.To create a project for the hosting models described in this article, see Get started with ASP.NET Core Blazor.

Blazor Webassembly WebAssembly

O modelo de hospedagem principal para Blazor está executando o lado do cliente no navegador no Webassembly.The principal hosting model for Blazor is running client-side in the browser on WebAssembly. O aplicativo Blazor, suas dependências e o tempo de execução do .NET são baixados para o navegador.The Blazor app, its dependencies, and the .NET runtime are downloaded to the browser. O aplicativo é executado diretamente no thread da interface do usuário do navegador.The app is executed directly on the browser UI thread. As atualizações da interface do usuário e o tratamento de eventos ocorrem no mesmo processo.UI updates and event handling occur within the same process. Os ativos do aplicativo são implantados como arquivos estáticos em um servidor Web ou serviço capaz de fornecer conteúdo estático aos clientes.The app's assets are deployed as static files to a web server or service capable of serving static content to clients.

[! Parar. Webassembly não LOC (mais alto)]: o [! Parar. O aplicativo no-LOC (mais alto)] é executado em um thread de interface do usuário dentro do navegador. WebAssembly: The Blazor app runs on a UI thread inside the browser.

Para criar um aplicativo Blazor usando o modelo de hospedagem do lado do cliente, use o modelo de aplicativo Webassembly doBlazor (dotnet New blazorwasm).To create a Blazor app using the client-side hosting model, use the Blazor WebAssembly App template (dotnet new blazorwasm).

Depois de selecionar o modelo de aplicativo WebassemblyBlazor , você tem a opção de configurar o aplicativo para usar um back-end ASP.NET Core marcando a caixa de seleção ASP.NET Core hospedado (dotnet New blazorwasm – hospedado).After selecting the Blazor WebAssembly App template, you have the option of configuring the app to use an ASP.NET Core backend by selecting the ASP.NET Core hosted check box (dotnet new blazorwasm --hosted). O aplicativo ASP.NET Core serve o aplicativo Blazor aos clientes.The ASP.NET Core app serves the Blazor app to clients. O aplicativo Webassembly Blazor pode interagir com o servidor pela rede usando chamadas de API Web ou SignalR.The Blazor WebAssembly app can interact with the server over the network using web API calls or SignalR.

Os modelos incluem o script mais incrivelmente. Webassembly. js que manipula:The templates include the blazor.webassembly.js script that handles:

  • Baixar o tempo de execução do .NET, o aplicativo e as dependências do aplicativo.Downloading the .NET runtime, the app, and the app's dependencies.
  • Inicialização do tempo de execução para executar o aplicativo.Initialization of the runtime to run the app.

O modelo de hospedagem Webassembly Blazor oferece vários benefícios:The Blazor WebAssembly hosting model offers several benefits:

  • Não há nenhuma dependência do lado do servidor .NET.There's no .NET server-side dependency. O aplicativo está totalmente funcionando depois de baixado para o cliente.The app is fully functioning after downloaded to the client.
  • Recursos e funcionalidades do cliente são totalmente aproveitados.Client resources and capabilities are fully leveraged.
  • O trabalho é descarregado do servidor para o cliente.Work is offloaded from the server to the client.
  • Um servidor Web ASP.NET Core não é necessário para hospedar o aplicativo.An ASP.NET Core web server isn't required to host the app. Cenários de implantação sem servidor são possíveis (por exemplo, servindo o aplicativo de uma CDN).Serverless deployment scenarios are possible (for example, serving the app from a CDN).

Há desvantagens em Blazor Hospedagem de Webassembly:There are downsides to Blazor WebAssembly hosting:

  • O aplicativo é restrito aos recursos do navegador.The app is restricted to the capabilities of the browser.
  • Hardware e software de cliente com capacidade (por exemplo, suporte a Webassembly) é necessário.Capable client hardware and software (for example, WebAssembly support) is required.
  • O tamanho do download é maior e os aplicativos demoram mais para serem carregados.Download size is larger, and apps take longer to load.
  • O suporte ao tempo de execução e às ferramentas do .NET é menos maduro..NET runtime and tooling support is less mature. Por exemplo, existem limitações em .net Standard suporte e depuração.For example, limitations exist in .NET Standard support and debugging.

Servidor de BlazorBlazor Server

Com o modelo de hospedagem do servidor Blazor, o aplicativo é executado no servidor de dentro de um aplicativo ASP.NET Core.With the Blazor Server hosting model, the app is executed on the server from within an ASP.NET Core app. As atualizações de interface do usuário, manipulação de eventos e chamadas JavaScript são manipuladas por uma conexão SignalR .UI updates, event handling, and JavaScript calls are handled over a SignalR connection.

O navegador interage com o aplicativo (hospedado dentro de um aplicativo ASP.NET Core) no servidor por meio de um [! Parar. Conexão não-LOC (Signalr)].

Para criar um aplicativo Blazor usando o modelo de hospedagem do Blazor Server, use o modelo de aplicativo ASP.NET CoreBlazor Server (dotnet New blazorserver).To create a Blazor app using the Blazor Server hosting model, use the ASP.NET Core Blazor Server App template (dotnet new blazorserver). O aplicativo ASP.NET Core hospeda o aplicativo Blazor Server e cria o ponto de extremidade SignalR onde os clientes se conectam.The ASP.NET Core app hosts the Blazor Server app and creates the SignalR endpoint where clients connect.

O aplicativo ASP.NET Core referencia a classe Startup do aplicativo a ser adicionada:The ASP.NET Core app references the app's Startup class to add:

  • Serviços do lado do servidor.Server-side services.
  • O aplicativo para o pipeline de tratamento de solicitação.The app to the request handling pipeline.

O script mais incrivelmente. Server. js† estabelece a conexão do cliente.The blazor.server.js script† establishes the client connection. É responsabilidade do aplicativo persistir e restaurar o estado do aplicativo, conforme necessário (por exemplo, no caso de uma conexão de rede perdida).It's the app's responsibility to persist and restore app state as required (for example, in the event of a lost network connection).

O modelo de hospedagem do Blazor Server oferece vários benefícios:The Blazor Server hosting model offers several benefits:

  • O tamanho do download é significativamente menor do que um aplicativo Webassembly Blazor e o aplicativo é carregado muito mais rapidamente.Download size is significantly smaller than a Blazor WebAssembly app, and the app loads much faster.
  • O aplicativo aproveita totalmente os recursos do servidor, incluindo o uso de qualquer API compatível com o .NET Core.The app takes full advantage of server capabilities, including use of any .NET Core compatible APIs.
  • O .NET Core no servidor é usado para executar o aplicativo, portanto, as ferramentas .NET existentes, como depuração, funcionam conforme o esperado..NET Core on the server is used to run the app, so existing .NET tooling, such as debugging, works as expected.
  • Há suporte para clientes finos.Thin clients are supported. Por exemplo, os aplicativos do Blazor Server funcionam com navegadores que não dão suporte ao Webassembly e a dispositivos com restrição de recursos.For example, Blazor Server apps work with browsers that don't support WebAssembly and on resource-constrained devices.
  • A base .NET/C# código do aplicativo, incluindo o código de componente do aplicativo, não é servida aos clientes.The app's .NET/C# code base, including the app's component code, isn't served to clients.

Há desvantagens em Blazor Hospedagem de servidor:There are downsides to Blazor Server hosting:

  • A latência mais alta geralmente existe.Higher latency usually exists. Cada interação do usuário envolve um salto de rede.Every user interaction involves a network hop.
  • Não há suporte offline.There's no offline support. Se a conexão do cliente falhar, o aplicativo para de funcionar.If the client connection fails, the app stops working.
  • A escalabilidade é desafiadora para aplicativos com muitos usuários.Scalability is challenging for apps with many users. O servidor deve gerenciar várias conexões de cliente e manipular o estado do cliente.The server must manage multiple client connections and handle client state.
  • Um servidor de ASP.NET Core é necessário para atender ao aplicativo.An ASP.NET Core server is required to serve the app. Cenários de implantação sem servidor não são possíveis (por exemplo, servir o aplicativo de uma CDN).Serverless deployment scenarios aren't possible (for example, serving the app from a CDN).

†o script mais incrivelmente. Server. js é servido por meio de um recurso incorporado na estrutura compartilhada ASP.NET Core.†The blazor.server.js script is served from an embedded resource in the ASP.NET Core shared framework.

Comparação com a interface do usuário renderizada pelo servidorComparison to server-rendered UI

Uma maneira de entender Blazor aplicativos de servidor é entender como ele difere dos modelos tradicionais para renderizar a interface do usuário em aplicativos ASP.NET Core usando exibições do Razor ou Razor Pages.One way to understand Blazor Server apps is to understand how it differs from traditional models for rendering UI in ASP.NET Core apps using Razor views or Razor Pages. Ambos os modelos usam a linguagem Razor para descrever o conteúdo HTML, mas são significativamente diferentes na forma como a marcação é renderizada.Both models use the Razor language to describe HTML content, but they significantly differ in how markup is rendered.

Quando uma página Razor ou exibição é renderizada, cada linha do código do Razor emite HTML na forma de texto.When a Razor Page or view is rendered, every line of Razor code emits HTML in text form. Após a renderização, o servidor descarta a página ou a instância de exibição, incluindo qualquer estado produzido.After rendering, the server disposes of the page or view instance, including any state that was produced. Quando outra solicitação para a página ocorre, por exemplo, quando a validação do servidor falha e o resumo de validação é exibido:When another request for the page occurs, for instance when server validation fails and the validation summary is displayed:

  • A página inteira é reprocessada para o texto HTML novamente.The entire page is rerendered to HTML text again.
  • A página é enviada ao cliente.The page is sent to the client.

Um aplicativo Blazor é composto por elementos reutilizáveis da interface do usuário chamada componentes.A Blazor app is composed of reusable elements of UI called components. Um componente contém C# código, marcação e outros componentes.A component contains C# code, markup, and other components. Quando um componente é renderizado, Blazor produz um grafo dos componentes incluídos de forma semelhante a um XML (Modelo de Objeto do Documento) ou HTML (DOM).When a component is rendered, Blazor produces a graph of the included components similar to an HTML or XML Document Object Model (DOM). Esse grafo inclui o estado do componente mantido em Propriedades e campos.This graph includes component state held in properties and fields. Blazor avalia o grafo de componente para produzir uma representação binária da marcação. evaluates the component graph to produce a binary representation of the markup. O formato binário pode ser:The binary format can be:

  • Transformado em texto HTML (durante o pré-processamento).Turned into HTML text (during prerendering).
  • Usado para atualizar a marcação com eficiência durante a renderização regular.Used to efficiently update the markup during regular rendering.

Uma atualização de interface do usuário no Blazor é disparada por:A UI update in Blazor is triggered by:

  • Interação do usuário, como selecionar um botão.User interaction, such as selecting a button.
  • Gatilhos de aplicativo, como um temporizador.App triggers, such as a timer.

O grafo é rerenderizado e uma comparação de interface do usuário (diferença) é calculada.The graph is rerendered, and a UI diff (difference) is calculated. Essa diferença é o menor conjunto de edições DOM necessárias para atualizar a interface do usuário no cliente.This diff is the smallest set of DOM edits required to update the UI on the client. A comparação é enviada ao cliente em um formato binário e aplicada pelo navegador.The diff is sent to the client in a binary format and applied by the browser.

Um componente é descartado depois que o usuário navega para fora dele no cliente.A component is disposed after the user navigates away from it on the client. Embora um usuário esteja interagindo com um componente, o estado do componente (serviços, recursos) deve ser mantido na memória do servidor.While a user is interacting with a component, the component's state (services, resources) must be held in the server's memory. Como o estado de muitos componentes pode ser mantido pelo servidor simultaneamente, o esgotamento de memória é uma preocupação que deve ser resolvida.Because the state of many components might be maintained by the server concurrently, memory exhaustion is a concern that must be addressed. Para obter orientação sobre como criar um aplicativo do Blazor Server para garantir o melhor uso da memória do servidor, consulte Proteger ASP.NET Core aplicativos do Blazor Server.For guidance on how to author a Blazor Server app to ensure the best use of server memory, see Proteger ASP.NET Core aplicativos do Blazor Server.

CircuitosCircuits

Um aplicativo do Blazor Server é criado sobre ASP.NET Core SignalR.A Blazor Server app is built on top of ASP.NET Core SignalR. Cada cliente se comunica com o servidor por meio de uma ou mais conexões SignalR chamadas de circuito.Each client communicates to the server over one or more SignalR connections called a circuit. Um circuito é A abstração Blazorde SignalR conexões que podem tolerar interrupções de rede temporárias.A circuit is Blazor's abstraction over SignalR connections that can tolerate temporary network interruptions. Quando um cliente Blazor vê que a conexão SignalR está desconectada, ele tenta se reconectar ao servidor usando uma nova conexão SignalR.When a Blazor client sees that the SignalR connection is disconnected, it attempts to reconnect to the server using a new SignalR connection.

Cada tela do navegador (guia do navegador ou iframe) que está conectada a um aplicativo do Blazor Server usa uma conexão SignalR.Each browser screen (browser tab or iframe) that is connected to a Blazor Server app uses a SignalR connection. Essa é ainda outra distinção importante em comparação com os aplicativos típicos renderizados pelo servidor.This is yet another important distinction compared to typical server-rendered apps. Em um aplicativo renderizado pelo servidor, a abertura do mesmo aplicativo em várias telas do navegador geralmente não se traduz em demandas de recursos adicionais no servidor.In a server-rendered app, opening the same app in multiple browser screens typically doesn't translate into additional resource demands on the server. Em um aplicativo do Blazor Server, cada tela do navegador requer um circuito separado e instâncias separadas do estado do componente a serem gerenciadas pelo servidor.In a Blazor Server app, each browser screen requires a separate circuit and separate instances of component state to be managed by the server.

Blazor considera fechar uma guia do navegador ou navegar até uma URL externa um encerramento normal . considers closing a browser tab or navigating to an external URL a graceful termination. No caso de um encerramento normal, o circuito e os recursos associados são lançados imediatamente.In the event of a graceful termination, the circuit and associated resources are immediately released. Um cliente também pode se desconectar não normalmente, por exemplo, devido a uma interrupção de rede.A client may also disconnect non-gracefully, for instance due to a network interruption. Blazor Server armazena circuitos desconectados para um intervalo configurável para permitir que o cliente se reconecte. Server stores disconnected circuits for a configurable interval to allow the client to reconnect. Para obter mais informações, consulte a seção reconexão com o mesmo servidor .For more information, see the Reconnection to the same server section.

Latência da interface do usuárioUI Latency

A latência da interface do usuário é o tempo que leva de uma ação iniciada até a hora em que a interface do usuário é atualizada.UI latency is the time it takes from an initiated action to the time the UI is updated. Valores menores para latência de interface do usuário são imperativos para um aplicativo se sentir responsivo a um usuário.Smaller values for UI latency are imperative for an app to feel responsive to a user. Em um aplicativo do Blazor Server, cada ação é enviada ao servidor, processada e uma comparação da interface do usuário é enviada de volta.In a Blazor Server app, each action is sent to the server, processed, and a UI diff is sent back. Consequentemente, a latência da interface do usuário é a soma da latência da rede e a latência do servidor no processamento da ação.Consequently, UI latency is the sum of network latency and the server latency in processing the action.

Para um aplicativo de linha de negócios limitado a uma rede corporativa privada, o efeito sobre as percepções do usuário de latência devido à latência da rede geralmente é imperceptível.For a line of business app that's limited to a private corporate network, the effect on user perceptions of latency due to network latency are usually imperceptible. Para um aplicativo implantado pela Internet, a latência pode ser perceptível para os usuários, especialmente se os usuários forem amplamente distribuídos geograficamente.For an app deployed over the Internet, latency may become noticeable to users, particularly if users are widely distributed geographically.

O uso de memória também pode contribuir para a latência do aplicativo.Memory usage can also contribute to app latency. O aumento do uso da memória resulta em uma coleta de lixo frequente ou na paginação da memória no disco, e conseqüentemente aumenta a latência da interface do usuário.Increased memory usage results in frequent garbage collection or paging memory to disk, both of which degrade app performance and consequently increase UI latency. Para obter mais informações, consulte Proteger ASP.NET Core aplicativos do Blazor Server.For more information, see Proteger ASP.NET Core aplicativos do Blazor Server.

os aplicativos do Blazor Server devem ser otimizados para minimizar a latência da interface do usuário ao reduzir a latência de rede e o uso de memóriaBlazor Server apps should be optimized to minimize UI latency by reducing network latency and memory usage. Para obter uma abordagem para medir a latência de rede, consulte Hospedar e implantar ASP.NET Core Blazor Server.For an approach to measuring network latency, see Hospedar e implantar ASP.NET Core Blazor Server. Para obter mais informações sobre SignalR e Blazor, consulte:For more information on SignalR and Blazor, see:

Conexão com o servidorConnection to the server

os aplicativos do Blazor Server exigem uma conexão de SignalR ativa com o servidor.Blazor Server apps require an active SignalR connection to the server. Se a conexão for perdida, o aplicativo tentará se reconectar ao servidor.If the connection is lost, the app attempts to reconnect to the server. Desde que o estado do cliente ainda esteja na memória, a sessão do cliente será retomada sem perder o estado.As long as the client's state is still in memory, the client session resumes without losing state.

Reconexão com o mesmo servidorReconnection to the same server

Um aplicativo do Blazor Server é renderizado em resposta à primeira solicitação do cliente, que configura o estado da interface do usuário no servidor.A Blazor Server app prerenders in response to the first client request, which sets up the UI state on the server. Quando o cliente tenta criar uma conexão SignalR, o cliente deve se reconectar ao mesmo servidor.When the client attempts to create a SignalR connection, the client must reconnect to the same server. os aplicativos do Blazor Server que usam mais de um servidor back-end devem implementar sessões adesivas para conexões de SignalR.Blazor Server apps that use more than one backend server should implement sticky sessions for SignalR connections.

É recomendável usar o serviço de SignalR do Azure para aplicativos do Blazor Server.We recommend using the Azure SignalR Service for Blazor Server apps. O serviço permite escalar verticalmente um aplicativo do Blazor Server para um grande número de conexões de SignalR simultâneas.The service allows for scaling up a Blazor Server app to a large number of concurrent SignalR connections. As sessões adesivas são habilitadas para o serviço de SignalR do Azure definindo a opção ServerStickyMode do serviço ou o valor de configuração como Required.Sticky sessions are enabled for the Azure SignalR Service by setting the service's ServerStickyMode option or configuration value to Required. Para obter mais informações, consulte Hospedar e implantar ASP.NET Core Blazor Server.For more information, see Hospedar e implantar ASP.NET Core Blazor Server.

Ao usar o IIS, as sessões adesivas são habilitadas com Application Request Routing.When using IIS, sticky sessions are enabled with Application Request Routing. Para obter mais informações, consulte balanceamento de carga http usando Application Request Routing.For more information, see HTTP Load Balancing using Application Request Routing.

Refletir o estado da conexão na interface do usuárioReflect the connection state in the UI

Quando o cliente detecta que a conexão foi perdida, uma interface de usuário padrão é exibida para o usuário enquanto o cliente tenta se reconectar.When the client detects that the connection has been lost, a default UI is displayed to the user while the client attempts to reconnect. Se a reconexão falhar, o usuário receberá a opção de tentar novamente.If reconnection fails, the user is provided the option to retry.

Para personalizar a interface do usuário, defina um elemento com uma id de components-reconnect-modal na <body> da página do Razor _Host. cshtml :To customize the UI, define an element with an id of components-reconnect-modal in the <body> of the _Host.cshtml Razor page:

<div id="components-reconnect-modal">
    ...
</div>

A tabela a seguir descreve as classes CSS aplicadas ao elemento components-reconnect-modal.The following table describes the CSS classes applied to the components-reconnect-modal element.

Classe CSSCSS class Indica…Indicates…
components-reconnect-show Uma conexão perdida.A lost connection. O cliente está tentando se reconectar.The client is attempting to reconnect. Mostrar o modal.Show the modal.
components-reconnect-hide Uma conexão ativa é restabelecida com o servidor.An active connection is re-established to the server. Ocultar a janela restrita.Hide the modal.
components-reconnect-failed Falha na reconexão, provavelmente devido a uma falha de rede.Reconnection failed, probably due to a network failure. Para tentar a reconexão, chame window.Blazor.reconnect().To attempt reconnection, call window.Blazor.reconnect().
components-reconnect-rejected Reconexão rejeitada.Reconnection rejected. O servidor foi atingido, mas recusou a conexão, e o estado do usuário no servidor foi perdido.The server was reached but refused the connection, and the user's state on the server is lost. Para recarregar o aplicativo, chame location.reload().To reload the app, call location.reload(). Esse estado de conexão pode resultar quando:This connection state may result when:
  • Ocorre uma falha no circuito do lado do servidor.A crash in the server-side circuit occurs.
  • O cliente é desconectado por tempo suficiente para o servidor descartar o estado do usuário.The client is disconnected long enough for the server to drop the user's state. As instâncias dos componentes com os quais o usuário está interagindo são descartadas.Instances of the components that the user is interacting with are disposed.
  • O servidor é reiniciado ou o processo de trabalho do aplicativo é reciclado.The server is restarted, or the app's worker process is recycled.

Reconexão com estado após o pré-processamentoStateful reconnection after prerendering

os aplicativos do Blazor Server são configurados por padrão para PreRender a interface do usuário no servidor antes que a conexão do cliente com o servidor seja estabelecida.Blazor Server apps are set up by default to prerender the UI on the server before the client connection to the server is established. Isso é configurado na página Razor _Host. cshtml :This is set up in the _Host.cshtml Razor page:

<body>
    <app>
      <component type="typeof(App)" render-mode="ServerPrerendered" />
    </app>

    <script src="_framework/blazor.server.js"></script>
</body>
<body>
    <app>@(await Html.RenderComponentAsync<App>(RenderMode.ServerPrerendered))</app>

    <script src="_framework/blazor.server.js"></script>
</body>

RenderMode configura se o componente:RenderMode configures whether the component:

  • É renderizado na página.Is prerendered into the page.
  • É renderizado como HTML estático na página ou se inclui as informações necessárias para inicializar um aplicativo Blazor do agente do usuário.Is rendered as static HTML on the page or if it includes the necessary information to bootstrap a Blazor app from the user agent.
RenderMode DescriçãoDescription
ServerPrerendered Renderiza o componente em HTML estático e inclui um marcador para um aplicativo do Blazor Server.Renders the component into static HTML and includes a marker for a Blazor Server app. Quando o agente do usuário é iniciado, esse marcador é usado para inicializar um aplicativo Blazor.When the user-agent starts, this marker is used to bootstrap a Blazor app.
Server Renderiza um marcador para um aplicativo do Blazor Server.Renders a marker for a Blazor Server app. A saída do componente não está incluída.Output from the component isn't included. Quando o agente do usuário é iniciado, esse marcador é usado para inicializar um aplicativo Blazor.When the user-agent starts, this marker is used to bootstrap a Blazor app.
Static Renderiza o componente em HTML estático.Renders the component into static HTML.
RenderMode DescriçãoDescription
ServerPrerendered Renderiza o componente em HTML estático e inclui um marcador para um aplicativo do Blazor Server.Renders the component into static HTML and includes a marker for a Blazor Server app. Quando o agente do usuário é iniciado, esse marcador é usado para inicializar um aplicativo Blazor.When the user-agent starts, this marker is used to bootstrap a Blazor app. Não há suporte para parâmetros.Parameters aren't supported.
Server Renderiza um marcador para um aplicativo do Blazor Server.Renders a marker for a Blazor Server app. A saída do componente não está incluída.Output from the component isn't included. Quando o agente do usuário é iniciado, esse marcador é usado para inicializar um aplicativo Blazor.When the user-agent starts, this marker is used to bootstrap a Blazor app. Não há suporte para parâmetros.Parameters aren't supported.
Static Renderiza o componente em HTML estático.Renders the component into static HTML. Há suporte para os parâmetros.Parameters are supported.

Não há suporte para a renderização de componentes de servidor de uma página HTML estática.Rendering server components from a static HTML page isn't supported.

Quando RenderMode é ServerPrerendered, o componente é inicialmente renderizado estaticamente como parte da página.When RenderMode is ServerPrerendered, the component is initially rendered statically as part of the page. Depois que o navegador estabelece uma conexão de volta com o servidor, o componente é renderizado novamentee o componente agora é interativo.Once the browser establishes a connection back to the server, the component is rendered again, and the component is now interactive. Se um método de ciclo de vida para inicializar o componente (OnInitialized{Async}) estiver presente, o método será executado duas vezes:If a lifecycle method for initializing the component (OnInitialized{Async}) is present, the method is executed twice:

  • Quando o componente é renderizado estaticamente.When the component is prerendered statically.
  • Depois que a conexão do servidor tiver sido estabelecida.After the server connection has been established.

Isso pode resultar em uma alteração perceptível nos dados exibidos na interface do usuário quando o componente é finalmente renderizado.This can result in a noticeable change in the data displayed in the UI when the component is finally rendered.

Para evitar o cenário de processamento duplo em um aplicativo do Blazor Server:To avoid the double-rendering scenario in a Blazor Server app:

  • Passe um identificador que pode ser usado para armazenar em cache o estado durante o pré-processamento e para recuperar o estado após a reinicialização do aplicativo.Pass in an identifier that can be used to cache the state during prerendering and to retrieve the state after the app restarts.
  • Use o identificador durante o pré-processamento para salvar o estado do componente.Use the identifier during prerendering to save component state.
  • Use o identificador após o pré-processamento para recuperar o estado armazenado em cache.Use the identifier after prerendering to retrieve the cached state.

O código a seguir demonstra uma WeatherForecastService atualizada em um aplicativo do Blazor Server baseado em modelo que evita a renderização dupla:The following code demonstrates an updated WeatherForecastService in a template-based Blazor Server app that avoids the double rendering:

public class WeatherForecastService
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild",
        "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };
    
    public WeatherForecastService(IMemoryCache memoryCache)
    {
        MemoryCache = memoryCache;
    }
    
    public IMemoryCache MemoryCache { get; }

    public Task<WeatherForecast[]> GetForecastAsync(DateTime startDate)
    {
        return MemoryCache.GetOrCreateAsync(startDate, async e =>
        {
            e.SetOptions(new MemoryCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = 
                    TimeSpan.FromSeconds(30)
            });

            var rng = new Random();

            await Task.Delay(TimeSpan.FromSeconds(10));

            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = startDate.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            }).ToArray();
        });
    }
}

Renderizar componentes interativos com estado de páginas e exibições do RazorRender stateful interactive components from Razor pages and views

Os componentes interativos com estado podem ser adicionados a uma página ou exibição Razor.Stateful interactive components can be added to a Razor page or view.

Quando a página ou a exibição renderiza:When the page or view renders:

  • O componente é renderizado com a página ou exibição.The component is prerendered with the page or view.
  • O estado inicial do componente usado para o pré-processamento é perdido.The initial component state used for prerendering is lost.
  • O novo estado do componente é criado quando a conexão de SignalR é estabelecida.New component state is created when the SignalR connection is established.

A seguinte página Razor renderiza um componente Counter:The following Razor page renders a Counter component:

<h1>My Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@code {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}
<h1>My Razor Page</h1>

@(await Html.RenderComponentAsync<Counter>(RenderMode.ServerPrerendered))

@code {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Renderizar componentes não interativos de páginas e exibições do RazorRender noninteractive components from Razor pages and views

Na página Razor a seguir, o componente MyComponent é processado estaticamente com um valor inicial que é especificado usando um formulário:In the following Razor page, the MyComponent component is statically rendered with an initial value that's specified using a form:

<h1>My Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@code {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}
<h1>My Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

@(await Html.RenderComponentAsync<MyComponent>(RenderMode.Static, 
    new { InitialValue = InitialValue }))

@code {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Como MyComponent é processado estaticamente, o componente não pode ser interativo.Since MyComponent is statically rendered, the component can't be interactive.

Detectar quando o aplicativo está sendo renderizadoDetect when the app is prerendering

Embora um aplicativo de servidor mais incrivelmente seja o pré-processamento, determinadas ações, como a chamada para JavaScript, não são possíveis porque uma conexão com o navegador não foi estabelecida.While a Blazor Server app is prerendering, certain actions, such as calling into JavaScript, aren't possible because a connection with the browser hasn't been established. Os componentes podem precisar ser renderizados de forma diferente quando renderizados.Components may need to render differently when prerendered.

Para atrasar as chamadas de interoperabilidade do JavaScript até que a conexão com o navegador seja estabelecida, você pode usar o evento de ciclo de vida do componente OnAfterRenderAsync.To delay JavaScript interop calls until after the connection with the browser is established, you can use the OnAfterRenderAsync component lifecycle event. Esse evento é chamado somente depois que o aplicativo é totalmente renderizado e a conexão do cliente é estabelecida.This event is only called after the app is fully rendered and the client connection is established.

@using Microsoft.JSInterop
@inject IJSRuntime JSRuntime

<div @ref="divElement">Text during render</div>

@code {
    private ElementReference divElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await JSRuntime.InvokeVoidAsync(
                "setElementText", divElement, "Text after render");
        }
    }
}

Para o código de exemplo anterior, forneça uma setElementText função JavaScript dentro do elemento <head> de wwwroot/index.html (Webassembly de mais claro) ou pages/_Host. cshtml (servidor mais incrivelmente).For the preceding example code, provide a setElementText JavaScript function inside the <head> element of wwwroot/index.html (Blazor WebAssembly) or Pages/_Host.cshtml (Blazor Server). A função é chamada com IJSRuntime.InvokeVoidAsync e não retorna um valor:The function is called with IJSRuntime.InvokeVoidAsync and doesn't return a value:

<script>
  window.setElementText = (element, text) => element.innerText = text;
</script>

Aviso

O exemplo anterior modifica o Modelo de Objeto do Documento (DOM) diretamente para fins de demonstração.The preceding example modifies the Document Object Model (DOM) directly for demonstration purposes only. A modificação direta do DOM com o JavaScript não é recomendada na maioria dos cenários porque o JavaScript pode interferir no controle de alterações de mais grande.Directly modifying the DOM with JavaScript isn't recommended in most scenarios because JavaScript can interfere with Blazor's change tracking.

O componente a seguir demonstra como usar a interoperabilidade do JavaScript como parte da lógica de inicialização de um componente de forma que seja compatível com o pré-processamento.The following component demonstrates how to use JavaScript interop as part of a component's initialization logic in a way that's compatible with prerendering. O componente mostra que é possível disparar uma atualização de renderização de dentro OnAfterRenderAsync.The component shows that it's possible to trigger a rendering update from inside OnAfterRenderAsync. O desenvolvedor deve evitar a criação de um loop infinito nesse cenário.The developer must avoid creating an infinite loop in this scenario.

Onde JSRuntime.InvokeAsync é chamado, ElementRef é usado somente no OnAfterRenderAsync e não em nenhum método de ciclo de vida anterior porque não há nenhum elemento JavaScript até que o componente seja renderizado.Where JSRuntime.InvokeAsync is called, ElementRef is only used in OnAfterRenderAsync and not in any earlier lifecycle method because there's no JavaScript element until after the component is rendered.

StateHasChanged é chamado para reprocessar o componente com o novo estado obtido da chamada de interoperabilidade JavaScript.StateHasChanged is called to rerender the component with the new state obtained from the JavaScript interop call. O código não cria um loop infinito porque StateHasChanged é chamado somente quando infoFromJs é null.The code doesn't create an infinite loop because StateHasChanged is only called when infoFromJs is null.

@page "/prerendered-interop"
@using Microsoft.AspNetCore.Components
@using Microsoft.JSInterop
@inject IJSRuntime JSRuntime

<p>
    Get value via JS interop call:
    <strong id="val-get-by-interop">@(infoFromJs ?? "No value yet")</strong>
</p>

Set value via JS interop call:
<div id="val-set-by-interop" @ref="divElement"></div>

@code {
    private string infoFromJs;
    private ElementReference divElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && infoFromJs == null)
        {
            infoFromJs = await JSRuntime.InvokeAsync<string>(
                "setElementText", divElement, "Hello from interop call!");

            StateHasChanged();
        }
    }
}

Para o código de exemplo anterior, forneça uma setElementText função JavaScript dentro do elemento <head> de wwwroot/index.html (Webassembly de mais claro) ou pages/_Host. cshtml (servidor mais incrivelmente).For the preceding example code, provide a setElementText JavaScript function inside the <head> element of wwwroot/index.html (Blazor WebAssembly) or Pages/_Host.cshtml (Blazor Server). A função é chamada com IJSRuntime.InvokeAsync e retorna um valor:The function is called with IJSRuntime.InvokeAsync and returns a value:

<script>
  window.setElementText = (element, text) => {
    element.innerText = text;
    return text;
  };
</script>

Aviso

O exemplo anterior modifica o Modelo de Objeto do Documento (DOM) diretamente para fins de demonstração.The preceding example modifies the Document Object Model (DOM) directly for demonstration purposes only. A modificação direta do DOM com o JavaScript não é recomendada na maioria dos cenários porque o JavaScript pode interferir no controle de alterações de mais grande.Directly modifying the DOM with JavaScript isn't recommended in most scenarios because JavaScript can interfere with Blazor's change tracking.

Configurar o cliente do SignalR para aplicativos do Blazor ServerConfigure the SignalR client for Blazor Server apps

Às vezes, você precisa configurar o cliente SignalR usado por aplicativos do Blazor Server.Sometimes, you need to configure the SignalR client used by Blazor Server apps. Por exemplo, talvez você queira configurar o registro em log no cliente SignalR para diagnosticar um problema de conexão.For example, you might want to configure logging on the SignalR client to diagnose a connection issue.

Para configurar o cliente do SignalR no arquivo pages/_Host. cshtml :To configure the SignalR client in the Pages/_Host.cshtml file:

  • Adicione um atributo autostart="false" à marca de <script> para o script mais incrivelmente. Server. js .Add an autostart="false" attribute to the <script> tag for the blazor.server.js script.
  • Chame Blazor.start e passe um objeto de configuração que especifica o construtor de SignalR.Call Blazor.start and pass in a configuration object that specifies the SignalR builder.
<script src="_framework/blazor.server.js" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      builder.configureLogging("information"); // LogLevel.Information
    }
  });
</script>

Recursos adicionaisAdditional resources