Pré-renderizar e integrar componentes ASP.NET Core Razor

Este artigo explica os cenários Razor de integração de componentes para Blazor aplicativos, incluindo a pré-renderização de Razor componentes no servidor.

Importante

As alterações de estrutura entre versões da ASP.NET Core levaram a diferentes conjuntos de instruções neste artigo. Antes de usar as diretrizes deste artigo, confirme se o seletor da versão do documento nesta página corresponde à versão de ASP.NET Core que você pretende usar para seu aplicativo.

RazorComponentes podem ser integrados aos aplicativosRazor Pages e MVC em uma Blazor WebAssemblysolução hospedada. Componentes podem ser pré-renderizados ao mesmo tempo após a renderização da página ou exibição.

A pré-renderização pode melhorar a SEO (Otimização do Mecanismo de Pesquisa), ao renderizar conteúdos de resposta ao HTTP inicial no quais os mecanismos de pesquisa podem usar para calcular a classificação da página.

Configuração da solução

Configurações de pré-renderização

Para configurar a pré-renderização de um aplicativo hospedadoBlazor WebAssembly:

1. Hospede oBlazor WebAssembly aplicativo em um aplicativo ASP.NET Core. Um aplicativo independenteBlazor WebAssembly pode ser adicionado a uma solução ASP.NET Core assim como a um aplicativo hospedadoBlazor WebAssembly, criado a partir do Blazor WebAssembly modelo de projeto com a opção hospedada:

   • Visual Studio: na caixa de diálogoInformações adicionais, marque a opção ASP.NET Core Hospedado ao criar oBlazor WebAssembly aplicativo. Nos exemplos deste artigo, a solução é denominadaBlazorHosted.
   • Shell de comando da CLI do Visual Studio Code/.NET: dotnet new blazorwasm -ho (use a opção -ho|--hosted). Use a opção -o|--output {LOCATION} para criar uma pasta para a solução e definir os namespaces da solução de projeto. Nos exemplos deste artigo, a solução é denominada BlazorHosted(dotnet new blazorwasm -ho -o BlazorHosted).

   Nos exemplos deste artigo, o nome da solução hospedada (nome do assembly) é BlazorHosted. O namespace do projeto do cliente é BlazorHosted.Cliente o namespace do projeto do servidor éBlazorHosted.Server.

2. Excluir arquivo wwwroot/index.html do projeto Blazor WebAssemblyClient .

3. Client No projeto, exclua as seguintes linhas emProgram.cs:

   - builder.RootComponents.Add<App>("#app");
   - builder.RootComponents.Add<HeadOutlet>("head::after");
   

4. Adicionar _Host.cshtml arquivo à pasta Pages do projeto Server . É possível obter os arquivos de um projeto criado a partir do modelo usando oBlazor Server Visual Studio ou a CLI do .NET com o dotnet new blazorserver -o BlazorServercomando em um shell de comando (a opção -o BlazorServer cria uma pasta para o projeto). Depois de colocar os arquivos na pasta Server do projeto Pages, faça as seguintes alterações nos arquivos.

   Faça as seguintes alterações no arquivo_Host.cshtml:

   • Atualize o namespace Pages na parte superior do arquivo para corresponder ao namespace das páginas Server do aplicativo. O espaço reservado {APP NAMESPACE} no exemplo a seguir representa o namespace das páginas do aplicativo doador que forneceu o arquivo_Host.cshtml:

     Excluir:

     - @namespace {APP NAMESPACE}.Pages
     

     Adicionar:

     @namespace BlazorHosted.Server.Pages
     

   • Adicionar uma diretriz@usingpara o projetoClient na parte superior do arquivo:

     @using BlazorHosted.Client
     

   • Atualize os links da folha de estilos para apontar para as folhas de estilos do projeto WebAssembly. No exemplo a seguir, o namespace do projeto do cliente é BlazorHosted.Client. O espaço reservado {APP NAMESPACE}representa o namespace do aplicativo doador que forneceu o arquivo _Host.cshtml. Atualize o Auxiliar de Marca de Componente (<component>tag) para o HeadOutlet componente pré-renderizar o componente.

     Excluir:

     - <link href="css/site.css" rel="stylesheet" />
     - <link href="{APP NAMESPACE}.styles.css" rel="stylesheet" />
     - <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
     

     Adicionar:

     <link href="css/app.css" rel="stylesheet" />
     <link href="BlazorHosted.Client.styles.css" rel="stylesheet" />
     <component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />
     

     Observação

     Deixe o elemento <link> de solicitação da folha de estilos Bootstrap (css/bootstrap/bootstrap.min.css) no lugar.

   • Atualize a origem doBlazor script para usar o scriptBlazor WebAssembly do cliente:

     Excluir:

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

     Adicionar:

     <script src="_framework/blazor.webassembly.js"></script>
     

   • Atualize o render-mode do Auxiliar de Marca de Componente para pré-renderizar o componente raiz App com:WebAssemblyPrerendered

     Excluir:

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

     Adicionar:

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

     Importante

     A pré-renderização não é compatível com pontos de extremidade de autenticação (/authentication/ segmento de caminho). Para obter mais informações, consulte Cenários de segurança adicionais de Blazor WebAssembly no ASP.NET Core.

5. Program.cs No arquivo do Server projeto, altere o ponto de extremidade do fallback doindex.html arquivo para a _Host.cshtml página:

   Excluir:

   - app.MapFallbackToFile("index.html");
   

   Adicionar:

   app.MapFallbackToPage("/_Host");
   

6. Caso os projetosClient e Server utilizem um ou mais serviços em comum durante a pré-renderização, considere que os registros de serviço em um método podem ser chamados de ambos os projetos. Para saber mais, confira Injeção de dependência do Blazor no ASP.NET Core.

7. Execute o projeto Server. O aplicativo hospedado Blazor WebAssembly é pré-renderizado pelo Server projeto para clientes.

Configurações para incorporarRazor componentes em páginas e exibições

As seções e exemplos a seguir para incorporarRazor componentes do ClientBlazor WebAssembly aplicativo às páginas e exibições do aplicativo de servidor exigem configuração adicional.

O projeto Server deve ter os seguintes arquivos e pastas.

RazorPages:

• Pages/Shared/_Layout.cshtml
• Pages/Shared/_Layout.cshtml.css
• Pages/_ViewImports.cshtml
• Pages/_ViewStart.cshtml

MVC:

• Views/Shared/_Layout.cshtml
• Views/Shared/_Layout.cshtml.css
• Views/_ViewImports.cshtml
• Views/_ViewStart.cshtml

Os arquivos anteriores podem ser obtidos ao gerar um aplicativo usando os modelos de projeto do ASP.NET Core:

• Novas ferramentas de criação de projeto do Visual Studio.
• Ao abrir um shell de comando e executar dotnet new webapp -o {PROJECT NAME} (Razor Pages) ou dotnet new mvc -o {PROJECT NAME} (MVC). A opção -o|--output com um valor para o {PROJECT NAME} espaço reservado fornece um nome e cria uma pasta para o aplicativo.

Atualize os namespaces no arquivo importado _ViewImports.cshtml para corresponder aos usados pelo projeto Server que recebe os arquivos.

Pages/_ViewImports.cshtml (PagesRazor):

@using BlazorHosted.Server
@namespace BlazorHosted.Server.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Views/_ViewImports.cshtml (MVC):

@using BlazorHosted.Server
@using BlazorHosted.Server.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Atualize o arquivo importado do layout Pages/Shared/_Layout.cshtml para Razor Pages ou Views/Shared/_Layout.cshtmlpara MVC.

Primeiramente, exclua o título e a folha de estilos do projeto do doador, que está RPDonor.styles.css no exemplo a seguir. O espaço reservado {PROJECT NAME} representa o nome do aplicativo do projeto do doador.

- <title>@ViewData["Title"] - {PROJECT NAME}</title>
- <link rel="stylesheet" href="~/RPDonor.styles.css" asp-append-version="true" />

Inclua os estilos do projeto Client no arquivo de layout. No exemplo a seguir, o namespace Client do projeto do cliente é BlazorHosted.Client. O elemento <title> pode ser atualizado ao mesmo tempo.

Coloque as seguintes linhas no conteúdo <head> do arquivo de layout:

<title>@ViewData["Title"] - BlazorHosted</title>
<link href="css/app.css" rel="stylesheet" />
<link rel="stylesheet" href="BlazorHosted.Client.styles.css" asp-append-version="true" />
<component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />

O layout importado contém doisHome (Index página) e Privacy links de navegação. Para fazer com que os Home links sigam para o aplicativo hospedadoBlazor WebAssembly, altere os hiperlinks:

- <a class="navbar-brand" asp-area="" asp-page="/Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-page="/Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

Em um arquivo de layout MVC:

- <a class="navbar-brand" asp-area="" asp-controller="Home" 
-     asp-action="Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-controller="Home" 
-     asp-action="Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

Atualize o nome do aplicativo do elemento <footer>. O exemplo a seguir usa o nome do aplicativoBlazorHosted:

- &copy; {DATE} - {DONOR NAME} - <a asp-area="" asp-page="/Privacy">Privacy</a>
+ &copy; {DATE} - BlazorHosted - <a asp-area="" asp-page="/Privacy">Privacy</a>

No exemplo anterior, o {DATE} espaço reservado representa a data de direitos autorais em um aplicativo gerado a partir do Razor modelo de projeto do Pages ou MVC.

Para fazer com que o Privacy link leve a uma página de privacidade (Razor Pages), adicione uma página de privacidade ao Server projeto.

Pages/Privacy.cshtmlNo projetoServer:

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Para uma visualização de privacidade baseada em MVC, crie um modo de exibição de privacidade no Server projeto.

View/Home/Privacy.cshtmlNo projetoServer:

@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Home No controle do aplicativo MVC, retorne a exibição.

Adicione o seguinte código ao Controllers/HomeController.cs:

public IActionResult Privacy()
{
    return View();
}

Ao importar arquivos de um aplicativo doador, atualize todos os namespaces nos arquivos para corresponder ao do projeto Server (por exemplo,BlazorHosted.Server).

Importe ativos estáticos para o projeto Server da pasta do projeto do doador wwwroot:

• wwwroot/css pasta e conteúdo
• wwwroot/js pasta e conteúdo
• wwwroot/lib pasta e conteúdo

Se o projeto do doador for criado a partir de um modelo de projeto ASP.NET Core e os arquivos não forem modificados, será possível copiar wwwroot a pasta completa do projeto do doador para o Server projeto e remover o arquivo de favicon ícone.

Aviso

Evite colocar o recurso estático nas pastas Client eServerwwwroot. Se o mesmo arquivo estiver presente em ambas as pastas, uma exceção será gerada porque os recursos estáticos compartilham o mesmo diretório raiz na rede. Portanto, hospede um recurso estático em qualquer uma das wwwroot pastas, não em ambas.

Ao adotar a configuração anterior, encorporeRazor componentes nas páginas ou exibições do Serverprojeto. Use as diretrizes nas seguintes seções deste artigo:

• Renderizar componentes em uma página ou exibição com o Auxiliar de Marca de Componente
• Renderizar componentes em uma página ou exibição com um seletor CSS

Renderizar componentes em uma página ou exibição com o Auxiliar de Marca de Componente

Depois de configurar a solução, inclusive a configuração adicional, o Auxiliar de Marca de Componentedará suporte aos dois modos de renderização para renderizar um componente de um Blazor WebAssembly aplicativo em uma página ou exibição:

• WebAssembly
• WebAssemblyPrerendered

No exemplo do Pages a seguirRazor, o Countercomponente é renderizado em uma página. Para tornar o componente interativo, o script Blazor WebAssembly é incluído na seção de renderização da página . Para evitar usar o namespace completo para o Counter componente com o Auxiliar de Marca de Componente ({ASSEMBLY NAME}.Pages.Counter), adicione uma @using diretriz para o namespace do Pages projeto do cliente. No exemplo a seguir, o namespace Client do projeto do cliente é BlazorHosted.Client.

No projeto Server, Pages/RazorPagesCounter1.cshtml:

@page
@using BlazorHosted.Client.Pages

<component type="typeof(Counter)" render-mode="WebAssemblyPrerendered" />

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Execute o projeto Server. Navegue até a página Razor em /razorpagescounter1. O componente pré-renderizadoCounter é encorpado na página.

RenderMode configura-se quando o componente:

• É pré-renderizado na página.
• É renderizado como HTML estático na página ou se as informações necessárias para inicializar um Blazor aplicativo do agente do usuário estão inclusas.

Para mais informações sobre o Auxiliar de Marca de Componente, incluindo a passagem de parâmetros e RenderMode a configuração, confira o Auxiliar de Marca de Componente no ASP.NET Core.

Trabalho adicional pode ser necessário a depender dos recursos estáticos que os componentes usam e como as páginas de layout são organizadas em um aplicativo. Normalmente, os scripts são adicionados à seção de renderização de uma página ou exibição Scriptse folhas de estilo são adicionadas ao conteúdo do elemento do <head> layout.

Definir conteúdo filho por meio de um fragmento de renderização

O Auxiliar de Marca de Componente não dá suporte ao recebimento de um RenderFragment representante para conteúdo filho (por exemplo, param-ChildContent="..."). É recomendável criar um componente Razor (.razor) que referencie o componente que você deseja renderizar com o conteúdo filho que você deseja passar e, em seguida, invoque o componente da página ou exibição Razor.

Garantir que os componentes pré-renderizados de nível superior não sejam cortados na publicação

Se um Auxiliar de Marca de Componente fizer referência direta a um componente de uma biblioteca que está sujeito a corte na publicação, o componente poderá ser cortado durante a publicação porque não há referências a ele no código do aplicativo do cliente. Como resultado, o componente não é pré-renderizado, deixando um espaço em branco na saída. Se for o caso, instrua o corte a preservar o componente de biblioteca adicionando um DynamicDependency atributo a qualquer classe no aplicativo do cliente. Para preservar um componente chamado SomeLibraryComponentToBePreserved, adicione o seguinte a qualquer componente:

@using System.Diagnostics.CodeAnalysis
@attribute [DynamicDependency(DynamicallyAccessedMemberTypes.All, 
    typeof(SomeLibraryComponentToBePreserved))]

A abordagem anterior geralmente não é necessária porque, na maioria dos casos, o aplicativo pré-renderiza seus componentes (que não são cortados), o que, por sua vez, referencia componentes de bibliotecas (fazendo com que eles também não sejam cortados). DynamicDependency Apenas use explicitamente para pré-renderizar um componente de biblioteca diretamente quando a biblioteca estiver sujeita a corte.

Renderizar componentes em uma página ou exibição com um seletor CSS

Depois deconfigurar a solução, incluindo a configuração adicional, adicione componentes raiz ao Client projeto de uma solução hospedada Blazor WebAssembly no Program.cs arquivo. No exemplo a seguir, o Counter componente é declarado como um componente raiz com um seletor CSS que seleciona o elemento comid as combinaçõescounter-component. No exemplo a seguir, o namespace Client do projeto do cliente é BlazorHosted.Client.

No Program.cs arquivo do projeto Client, adicione o namespace para os componentes do Razor projeto na parte superior do arquivo:

using BlazorHosted.Client.Pages;

Depois que o builder estiver estabelecido em Program.cs, adicione o Counter componente como um componente raiz:

builder.RootComponents.Add<Counter>("#counter-component");

No exemplo do Pages a seguirRazor, o Countercomponente é renderizado em uma página. Para tornar o componente interativo, o script Blazor WebAssembly é incluído na seção de renderização da página .

No projeto Server, Pages/RazorPagesCounter2.cshtml:

@page

<div id="counter-component">Loading...</div>

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Execute o projeto Server. Navegue até a página Razor em /razorpagescounter2. O componente pré-renderizadoCounter é encorpado na página.

Trabalho adicional pode ser necessário a depender dos recursos estáticos que os componentes usam e como as páginas de layout são organizadas em um aplicativo. Normalmente, os scripts são adicionados à seção de renderização de uma página ou exibição Scriptse folhas de estilo são adicionadas ao conteúdo do elemento do <head> layout.

Observação

O exemplo anterior gera umJSException se umBlazor WebAssembly aplicativo for pré-renderizado e integrado aos Razor aplicativos Pages ou MVC simultaneamente com o uso de um seletor CSS. Navegar até um dos Client componentes do Razor projeto ou navegar até uma página ou exibição do Server com um componente encorporado lança um ou mais JSException.

Este é um comportamento normal porque a pré-renderização e a integração de um Blazor WebAssembly aplicativo com componentes roteáveis Razor são incompatíveis com o uso de seletores CSS.

Se você estiver trabalhando com os exemplos nas seções anteriores e quiser apenas conferir o trabalho do seletor de CSS em seu aplicativo de amostra, comente a especificação do App componente raiz do Client arquivo do Program.cs projeto:

- builder.RootComponents.Add<App>("#app");
+ //builder.RootComponents.Add<App>("#app");

Navegue até a página ou exibição com o componente encorporado Razor que usa um seletor CSS (tal como/razorpagescounter2 o exemplo anterior). A página ou exibição carrega com o componente encorporado e as funções de componente são incorporadas conforme o esperado.

RazorComponentes podem ser incorporados aosRazoraplicativos Pages e MVC. Componentes podem ser pré-renderizados ao mesmo tempo após a renderização da página ou exibição.

A pré-renderização pode melhorar a SEO (Otimização do Mecanismo de Pesquisa), ao renderizar conteúdos de resposta ao HTTP inicial no quais os mecanismos de pesquisa podem usar para calcular a classificação da página.

Depois de configurar o projeto, use as diretrizes nas seguintes seções, dependendo dos requisitos do projeto:

• Para componente diretamente roteáveis a partir de solicitações do usuário. Siga estas diretrizes quando os visitantes solicitarem HTTP no navegador para um componente com uma @page diretiva.
  • Usar componentes roteáveis em umRazor aplicativo Pages
  • Usar componentes roteáveis em um aplicativo MVC
• Para componentes que não são diretamente roteáveis a partir de solicitações do usuário, confira a seção Renderizar componentes de uma página ou exibição. Siga estas diretrizes quando o aplicativo encorporar componentes em páginas e exibições existentes com o Auxiliar de Marca de Componente.

Configuração

Usar as diretrizes a seguir para integrar Razor componentes em páginas e exibições de um aplicativo Pages ou MVC existenteRazor.

1. Adicionar um arquivo de importações à pasta raiz do projeto com o conteúdo a seguir. Alterar o {APP NAMESPACE} espaço reservado para o namespace do projeto.

   _Imports.razor:

   @using System.Net.Http
   @using Microsoft.AspNetCore.Authorization
   @using Microsoft.AspNetCore.Components.Authorization
   @using Microsoft.AspNetCore.Components.Forms
   @using Microsoft.AspNetCore.Components.Routing
   @using Microsoft.AspNetCore.Components.Web
   @using Microsoft.AspNetCore.Components.Web.Virtualization
   @using Microsoft.JSInterop
   @using {APP NAMESPACE}
   

2. No arquivo de layout do projeto (Pages/Shared/_Layout.cshtml em Razor aplicativos Pages ou em aplicativos MVC Views/Shared/_Layout.cshtml):

   • Adicionar a seguinte <base> marca e HeadOutlet o Auxiliar de Marca de Componente ao <head> elemento:

     <base href="~/" />
     <component type="typeof(Microsoft.AspNetCore.Components.Web.HeadOutlet)" 
         render-mode="ServerPrerendered" />
     

     O href valor (o caminho base do aplicativo) no exemplo anterior pressupõe que o aplicativo reside no caminho da URL raiz (/). Se o aplicativo for um subaplicação, siga as diretrizes na seção Caminho Base do aplicativo do artigo Hospedar e implantar ASP.NET CoreBlazor.

     O componente HeadOutlet é usado para renderizar o conteúdo de cabeçalho (<head>) para títulos de página (componente PageTitle) e outros elementos de cabeçalho (componente HeadContent) definidos por componentes Razor. Para mais informações, confira o Controle de conteúdo de cabeçalhoBlazor em aplicativos do ASP.NET Core.

   • Adicionar uma: <script> marca para o blazor.server.js script de imediato, antes da Scripts seção renderizar (@await RenderSectionAsync(...)):

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

     A estrutura adiciona o script blazor.server.js ao aplicativo. Não é necessário adicionar manualmente um arquivo de script blazor.server.js ao aplicativo.

   Observação

   Normalmente, o layout é carregado por meio de um arquivo _ViewStart.cshtml.

3. Registre os serviços no lugar em que Blazor Server os Program.cs serviços estão registrados:

   builder.Services.AddServerSideBlazor();
   

4. Adicionar o ponto de extremidade Hub Blazor aos pontos de extremidade Program.cs das rotas mapeadas. Coloque a seguinte linha após a chamada para MapRazorPages (Pages Razor) ou MapControllerRoute (MVC):

   app.MapBlazorHub();
   

5. Integrar componentes em qualquer página ou exibição. Por exemplo, adicione um componente Counter à pasta do projeto Shared.

   Pages/Shared/Counter.razor (Razor Pages) ou Views/Shared/Counter.razor (MVC):

   <h1>Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

   Razor Pages :

   Na página do Index projeto de um Razor aplicativo Pages, adicione oCounter namespace do componente e encorpore o componente na página. Ao carregar a Index página, o Counter componente é pré-renderizado. No exemplo a seguir, substitua o espaço reservado {APP NAMESPACE} pelo namespace do projeto.

   Pages/Index.cshtml:

   @page
   @using {APP NAMESPACE}.Pages.Shared
   @model IndexModel
   @{
       ViewData["Title"] = "Home page";
   }
   
   <component type="typeof(Counter)" render-mode="ServerPrerendered" />
   

   MVC:

   Na exibição do Index projeto de um aplicativo MVC, adicione o Counter namespace do componente e encorpore o componente na exibição. Ao carregar a exibiçãoIndex, o Counter componente é pré-renderizado. No exemplo a seguir, substitua o espaço reservado {APP NAMESPACE} pelo namespace do projeto.

   Views/Home/Index.cshtml:

   @using {APP NAMESPACE}.Views.Shared
   @{
       ViewData["Title"] = "Home Page";
   }
   
   <component type="typeof(Counter)" render-mode="ServerPrerendered" />
   

Para mais informações, confira a seção Renderização de componentes de uma página ou exibição.

Usar componentes roteáveis em um Razor aplicativo Pages

Esta seção refere-se à adição de componentes que são diretamente roteáveis a partir de solicitações do usuário.

Para dar suporte aos componentes roteáveis Razor emRazor aplicativos Pages:

1. Confira as diretrizes na seção de Configuração.

2. Adicionar um App componente à raiz do projeto com o conteúdo a seguir.

   App.razor:

   @using Microsoft.AspNetCore.Components.Routing
   
   <Router AppAssembly="typeof(App).Assembly">
       <Found Context="routeData">
           <RouteView RouteData="routeData" />
       </Found>
       <NotFound>
           <PageTitle>Not found</PageTitle>
           <p role="alert">Sorry, there's nothing at this address.</p>
       </NotFound>
   </Router>
   

3. Adicionar uma página_Host ao projeto com o seguinte conteúdo. Substitua o espaço reservado {APP NAMESPACE} pelo namespace do aplicativo.

   Pages/_Host.cshtml:

   @page
   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Observação

   O exemplo anterior pressupõe que o componente HeadOutlet e o Blazor script (_framework/blazor.server.js) sejam renderizados pelo layout do aplicativo. Para mais informações, confira a seção de Configuração.

   RenderMode configura-se quando o componenteApp:

   • É pré-renderizado na página.
   • É renderizado como HTML estático na página ou se as informações necessárias para inicializar um Blazor aplicativo do agente do usuário estão inclusas.

   Para mais informações sobre o Auxiliar de Marca de Componente, incluindo a passagem de parâmetros e RenderMode a configuração, confira o Auxiliar de Marca de Componente no ASP.NET Core.

4. Nos pontos de extremidade Program.cs, adicione uma rota de baixa prioridade para a página _Host como o último ponto de extremidade:

   app.MapFallbackToPage("/_Host");
   

5. Adicionar componentes roteáveis ao projeto. O exemplo a seguir é um RoutableCounter componente baseado no Counter componente nos Blazor modelos de projeto.

   Pages/RoutableCounter.razor:

   @page "/routable-counter"
   
   <PageTitle>Routable Counter</PageTitle>
   
   <h1>Routable Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

6. Execute o projeto e navegue até o componente RoutableCounter roteável em /routable-counter.

Para mais informações sobre namespaces, confira a seção Namespaces do Componente.

Usar componentes roteáveis em um aplicativo MVC

Esta seção refere-se à adição de componentes que são diretamente roteáveis a partir de solicitações do usuário.

Para dar suporte aos componentes roteáveis Razor em aplicativos MVC:

1. Confira as diretrizes na seção de Configuração.

2. Adicionar um App componente à raiz do projeto com o conteúdo a seguir.

   App.razor:

   @using Microsoft.AspNetCore.Components.Routing
   
   <Router AppAssembly="typeof(App).Assembly">
       <Found Context="routeData">
           <RouteView RouteData="routeData" />
       </Found>
       <NotFound>
           <PageTitle>Not found</PageTitle>
           <p role="alert">Sorry, there's nothing at this address.</p>
       </NotFound>
   </Router>
   

3. Adicionar exibição_Host ao projeto com o seguinte conteúdo. Substitua o espaço reservado {APP NAMESPACE} pelo namespace do aplicativo.

   Views/Home/_Host.cshtml:

   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Observação

   O exemplo anterior pressupõe que o componente HeadOutlet e o Blazor script (_framework/blazor.server.js) sejam renderizados pelo layout do aplicativo. Para mais informações, confira a seção de Configuração.

   RenderMode configura-se quando o componenteApp:

   • É pré-renderizado na página.
   • É renderizado como HTML estático na página ou se as informações necessárias para inicializar um Blazor aplicativo do agente do usuário estão inclusas.

   Para mais informações sobre o Auxiliar de Marca de Componente, incluindo a passagem de parâmetros e RenderMode a configuração, confira o Auxiliar de Marca de Componente no ASP.NET Core.

4. Adicionar uma ação ao Home controlador.

   Controllers/HomeController.cs:

   public IActionResult Blazor()
   {
      return View("_Host");
   }
   

5. Nos pontos de extremidade Program.cs, adicione uma rota de baixa prioridade para a ação do controlador que retorna a exibição _Host:

   app.MapFallbackToController("Blazor", "Home");
   

6. Criar uma Pages pasta no aplicativo MVC e adicione componentes roteáveis. O exemplo a seguir é um RoutableCounter componente baseado no Counter componente nos Blazor modelos de projeto.

   Pages/RoutableCounter.razor:

   @page "/routable-counter"
   
   <PageTitle>Routable Counter</PageTitle>
   
   <h1>Routable Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

7. Execute o projeto e navegue até o componente RoutableCounter roteável em /routable-counter.

Para mais informações sobre namespaces, confira a seção Namespaces do Componente.

Renderizar componentes de uma página ou exibição

Esta seção diz respeito à adição de componentes a páginas ou exibições, em que os componentes não são diretamente roteáveis a partir de solicitações do usuário.

Para renderizar um componente de uma página ou exibição, use o Auxiliar de Marca de Componente.

Renderizar componentes interativos e dinâmicos

Componentes interativos e dinâmicos podem ser adicionados a uma Razor página ou exibição.

Ao renderizar a página ou exibição:

• O componente é pré-renderizado com a página ou exibição.
• Perda do estado inicial do componente usado para pré-renderização.
• O novo estado componente é criado quando a SignalR conexão é estabelecida.

A página Razor a seguir renderiza um Counter componente:

<h1>Razor Page</h1>

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

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

Para mais informações, consulte Auxiliar de Marca de Componente no ASP.NET Core.

Renderizar componentes não interativos

Na página a seguir Razor, o Counter componente é renderizado estaticamente com um valor inicial específico usando um formulário. Uma vez que o componente é renderizado estaticamente, o componente não é interativo:

<h1>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" />

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

Para mais informações, consulte Auxiliar de Marca de Componente no ASP.NET Core.

Namespaces de componente

Ao usar uma pasta personalizada para manter os componentes Razor do projeto, adicione o namespace que representa a pasta à página/exibição ou ao _ViewImports.cshtml arquivo. No exemplo a seguir:

• Os componentes são armazenados na pasta Components do projeto.
• O espaço reservado {APP NAMESPACE} é o namespace do projeto. Components representa o nome da pasta.

@using {APP NAMESPACE}.Components

O _ViewImports.cshtml arquivo está localizado na Pages pasta de um Razor aplicativo Pages ou na Views pasta de um aplicativo MVC.

Para mais informações, confira osComponentes Razor do ASP.NET Core.

Persistência do estado pré-renderizado

Sem a persistência do estado pré-renderizado, há perda do estado usado durante a pré-renderização e ele deve ser recriado quando o aplicativo for totalmente carregado. Se qualquer estado for configurado de forma assíncrona, a interface do usuário poderá cintilar à medida que a interface do usuário pré-renderizada for substituída por espaços reservados temporários e totalmente renderizada outra vez.

Para persistir o estado em componentes pré-renderizados, use o Auxiliar de Marcação de Estado do Componente Persistente (fonte de referência). Adicione a marca do Auxiliar de Marca, <persist-component-state />, dentro da marca de fechamento </body> da página _Host em um aplicativo que remete componentes.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Em Pages/_Host.cshtml de Blazor aplicativos que são pré-renderizados pelo WebAssembly (WebAssemblyPrerendered) em um aplicativo Blazor WebAssembly hospedado ou ServerPrerendered em um aplicativo Blazor Server:

<body>
    ...

    <persist-component-state />
</body>

Decida qual estado persistir usando o serviço PersistentComponentState. PersistentComponentState.RegisterOnPersisting registra um retorno de chamada para a persistência do estado do componente antes que o aplicativo seja pausado. Há recuperação do estado com a retomada do aplicativo.

No exemplo a seguir:

• O espaço reservado {TYPE} representa o tipo de dados a ser persistido (por exemplo, WeatherForecast[]).
• O espaço reservado {TOKEN} é uma cadeia de caracteres de identificador de estado (por exemplo, fetchdata).

@implements IDisposable
@inject PersistentComponentState ApplicationState

...

@code {
    private {TYPE} data;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistData);

        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("{TOKEN}", data);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

O exemplo a seguir é uma versão atualizada do FetchData componente em um aplicativo hospedado Blazor WebAssembly com base no modelo doBlazor projeto. O componenteWeatherForecastPreserveState persiste no estado de previsão do tempo durante a pré-renderização e em seguida, recupera o estado para inicializar o componente. O Auxiliar de Marca de Estado do Componente Persistente persiste o estado do componente após todas as invocações de componente.

Pages/WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@using BlazorSample.Shared
@implements IDisposable
@inject IWeatherForecastService WeatherForecastService
@inject PersistentComponentState ApplicationState

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[] forecasts = Array.Empty<WeatherForecast>();
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistForecasts);

        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            "fetchdata", out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }
    }

    private Task PersistForecasts()
    {
        ApplicationState.PersistAsJson("fetchdata", forecasts);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Ao inicializar componentes com o mesmo estado usado durante a pré-renderização, todas as etapas de inicialização dispendiosa só são executadas uma vez. A interface do usuário renderizada também corresponde à interface do usuário pré-renderizada, portanto, nenhuma cintilação ocorre no navegador.

Recursos Blazor WebAssembly adicionais

• Gerenciamento de estado: controlar pré-renderização
• Suporte de pré-renderização com carregamento de assembly lento
• Razorobjetos do ciclo de vida do componente que são pertencentes à pré-renderização
  • inicialização de componente (OnInitialized{Async})
  • após a renderização do componente (OnAfterRender{Async})
  • Reconexão dinâmica após pré-renderização : Embora o conteúdo na seção se concentre em Blazor Server e a reconexão SignalR dinâmica , o cenário de pré-renderização nos aplicativos Blazor WebAssembly hospedados (WebAssemblyPrerendered) envolve condições e abordagens semelhantes para impedir que o código do desenvolvedor seja executado duas vezes. Para preservar o estado durante a execução do código de inicialização ao pré-renderizar, consulte a seção Persistir estado pré-renderizado deste artigo.
  • Pré-renderização com interoperabilidade do JavaScript
• Entidades de autenticação e autorização que pertencem à pré-renderização
  • aspectos gerais
  • pré-renderização com autenticação
• Hospedar e implantar: Blazor WebAssembly
• Lidar com erros: pré-renderização
• OnNavigateAsync é executado duas vezes ao pré-renderizar: Manipular eventos de navegação assíncronos com OnNavigateAsync

Tamanho do estado pré-renderizado e SignalR limite da mensagem

Um estado pré-renderizado grande pode exceder o limite de tamanho da SignalR mensagem do circuito, o que resulta no seguinte:

• O circuito SignalR falha ao inicializar com um erro no cliente: Circuit host not initialized.
• A caixa de diálogo de reconexão no cliente é exibida quando o circuito falha. Não foi possível recuperar.

Para resolver o problema, use ou uma das seguintes abordagens:

• Reduza a quantidade de dados que você está colocando no estado pré-renderizado.
• Aumente o limite daSignalR mensagem. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos Blazor Server adicionais

• Gerenciamento de estado: controlar pré-renderização
• Razorobjetos do ciclo de vida do componente que são pertencentes à pré-renderização
  • inicialização de componente (OnInitialized{Async})
  • após a renderização do componente (OnAfterRender{Async})
  • Reconexão com o estado após a pré-renderização
  • Pré-renderização com interoperabilidade do JavaScript
• autenticação e autorização: aspectos gerais
• identificar erros: pré-renderização
• Hospedar e implantar: Blazor Server
• mitigação de ameaças: XSS (Script entre sites)
• OnNavigateAsync é executado duas vezes ao pré-renderizar: Manipular eventos de navegação assíncronos com OnNavigateAsync