Compartilhar via

Integrar componentes Razor do ASP.NET Core com MVC ou Pages Razor

Observação

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

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, consulte a Política de Suporte do .NET e do .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

Componentes do Razor podem ser incorporados em Páginas do Razor ou aplicativos MVC. Quando a página ou exibição é renderizada, os componentes podem ser pré-renderizados ao mesmo tempo.

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 de versão do documento na parte superior deste artigo corresponde à versão do ASP.NET Core que você pretende usar para seu aplicativo.

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:

Configuração

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

  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 subaplicativo, consulte o caminho base do aplicativo 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> tag ao blazor.server.js script imediatamente antes da seção de renderização Scripts (@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. Adicione o ponto de extremidade Blazor do Hub aos pontos de extremidade Program.cs onde rotas são 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 (Pages Razor) 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. Quando a exibição Index é carregada, o componente Counter é pré-renderizado na página. 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 quando o componente App:

    • É 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 componente RoutableCounter baseado no componente Counter presente nos modelos de projeto Blazor.

    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. Adicione uma _Host exibição 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 quando o componente App:

    • É 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 componente RoutableCounter baseado no componente Counter presente nos modelos de projeto Blazor.

    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 componente Counter.

<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ções de Componente no ASP.NET Core.

Renderizar componentes não interativos

Na página a seguir Razor, o componente Counter é renderizado estaticamente com um valor inicial especificado 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ções 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 marcador de posição {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 dos aplicativos Blazor que estão ServerPrerendered em um aplicativo Blazor Server:

<body>
    ...

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

Decida qual estado persistir usando o serviço PersistentComponentState. O atributo [SupplyParameterFromPersistentComponentState] aplicado a uma propriedade registra um retorno de chamada para persistir o estado durante a pré-geração e o carrega quando o componente é renderizado interativamente ou o serviço é instanciado.

No exemplo a seguir, o espaço reservado {TYPE} representa o tipo de dados a persistir (por exemplo, WeatherForecast[]).

@code {
    [SupplyParameterFromPersistentComponentState]
    public {TYPE} Data { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Data ??= await ...;
    }
}

No exemplo a seguir, o componente WeatherForecastPreserveState 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.

WeatherForecastPreserveState.razor:

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

<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 {
    [SupplyParameterFromPersistentComponentState]
    public WeatherForecast[]? Forecasts { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Forecasts ??= await WeatherForecastService.GetForecastAsync(
            DateOnly.FromDateTime(DateTime.Now));
    }
}

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. O estado é recuperado quando o aplicativo é retomado. Faça a chamada ao final do código de inicialização para evitar uma possível condição de corrida durante o desligamento 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()
    {
        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

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

        return Task.CompletedTask;
    }

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

No exemplo a seguir, o componente WeatherForecastPreserveState 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()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(
                    DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), 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.

O estado pré-renderizado persistente é transferido para o cliente, onde é usado para restaurar o estado do componente. ASP.NET Core Data Protection garante que os dados sejam transferidos com segurança nos Blazor Server aplicativos.

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

Um estado pré-renderizado grande pode exceder Blazoro 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 interface do usuário de reconexão no cliente aparece 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 da mensagem SignalR. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos Blazor Server adicionais

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:

Configuração

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

Importante

O uso de uma página de layout (_Layout.cshtml) com um Auxiliar de Marca de Componente para um componente HeadOutlet é necessário para controlar o conteúdo <head>, como o título da página (componente PageTitle) e outros elementos de cabeçalho (componente HeadContent). Para mais informações, confira o Controle de conteúdo de cabeçalhoBlazor em aplicativos do ASP.NET Core.

  1. No arquivo de layout do projeto:

    • Adicionar a seguinte <base> marca e HeadOutlet o Auxiliar de Marca de Componente ao <head> elemento em Pages/Shared/_Layout.cshtml (RazorPages) ou Views/Shared/_Layout.cshtml (MVC):

      <base href="~/" />
<component type="typeof(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 subaplicativo, consulte o caminho base do aplicativo 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 imediatamente antes da Scripts seção de renderização (@await RenderSectionAsync(...)) no layout do aplicativo.

      Pages/Shared/_Layout.cshtml (Pages Razor) ou Views/Shared/_Layout.cshtml (MVC):

      <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.

  2. 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}

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

    builder.Services.AddServerSideBlazor();

  4. Adicione o ponto de extremidade Blazor do Hub aos pontos de extremidade Program.cs onde rotas são 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 (Pages Razor) 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. Quando a exibição Index é carregada, o componente Counter é pré-renderizado na página. 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.

    Pages/_Host.cshtml:

    @page "/blazor"
@namespace {APP NAMESPACE}.Pages.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

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

    Neste cenário, os componentes utilizam o arquivo _Layout.cshtml compartilhado para o layout.

    Importante

    O uso de uma página de layout (_Layout.cshtml) com um Auxiliar de Marca de Componente para um componente HeadOutlet é necessário para controlar o conteúdo <head>, como o título da página (componente PageTitle) e outros elementos de cabeçalho (componente HeadContent). Para mais informações, confira o Controle de conteúdo de cabeçalhoBlazor em aplicativos do ASP.NET Core.

    RenderMode configura quando o componente App:

    • É 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 componente RoutableCounter baseado no componente Counter presente nos modelos de projeto Blazor.

    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. Adicione uma _Host exibição ao projeto com o seguinte conteúdo.

    Views/Home/_Host.cshtml:

    @namespace {APP NAMESPACE}.Views.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

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

    Os componentes usam o arquivo _Layout.cshtml compartilhado para o layout.

    Importante

    O uso de uma página de layout (_Layout.cshtml) com um Auxiliar de Marca de Componente para um componente HeadOutlet é necessário para controlar o conteúdo <head>, como o título da página (componente PageTitle) e outros elementos de cabeçalho (componente HeadContent). Para mais informações, confira o Controle de conteúdo de cabeçalhoBlazor em aplicativos do ASP.NET Core.

    RenderMode configura quando o componente App:

    • É 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 componente RoutableCounter baseado no componente Counter presente nos modelos de projeto Blazor.

    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 componente Counter.

<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ções de Componente no ASP.NET Core.

Importante

O uso de uma página de layout (_Layout.cshtml) com um Auxiliar de Marca de Componente para um componente HeadOutlet é necessário para controlar o conteúdo <head>, como o título da página (componente PageTitle) e outros elementos de cabeçalho (componente HeadContent). Para mais informações, confira o Controle de conteúdo de cabeçalhoBlazor em aplicativos do ASP.NET Core.

Renderizar componentes não interativos

Na página a seguir Razor, o componente Counter é renderizado estaticamente com um valor inicial especificado 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ções de Componente no ASP.NET Core.

Importante

O uso de uma página de layout (_Layout.cshtml) com um Auxiliar de Marca de Componente para um componente HeadOutlet é necessário para controlar o conteúdo <head>, como o título da página (componente PageTitle) e outros elementos de cabeçalho (componente HeadContent). Para mais informações, confira o Controle de conteúdo de cabeçalhoBlazor em aplicativos do 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 marcador de posição {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 resolver esses problemas, Blazor oferece suporte ao estado persistente em uma página pré-renderizada, usando o Auxiliar de Marca de Estado do Componente Persistente. Adicionar a marca do Auxiliar de Marca, <persist-component-state />, dentro da marca de fechamento </body>.

Pages/_Layout.cshtml:

<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. O estado é recuperado quando o aplicativo é retomado. Faça a chamada ao final do código de inicialização para evitar uma possível condição de corrida durante o desligamento do aplicativo.

No exemplo a seguir, o componente WeatherForecastPreserveState 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"
@implements IDisposable
@using BlazorSample.Shared
@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()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateTime.Now);
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), 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.

O estado pré-renderizado persistente é transferido para o cliente, onde é usado para restaurar o estado do componente. ASP.NET Core Data Protection garante que os dados sejam transferidos com segurança nos Blazor Server aplicativos.

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

Um estado pré-renderizado grande pode exceder Blazoro 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 interface do usuário de reconexão no cliente aparece 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 da mensagem SignalR. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos Blazor Server adicionais

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:

Configuração

Um aplicativo MVC ou Pages Razor existente pode integrar componentes Razor em páginas ou exibições:

  1. No arquivo de layout do projeto:

    • Adicionar a seguinte <base> marca ao <head> elemento em Pages/Shared/_Layout.cshtml (Razor Pages) ou Views/Shared/_Layout.cshtml (MVC):

      <base href="~/" />

      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 subaplicativo, consulte o caminho base do aplicativo ASP.NET CoreBlazor.

    • Adicionar uma marca <script> para o script blazor.server.js imediatamente antes da seção de renderização Scripts.

      Pages/Shared/_Layout.cshtml (Pages Razor) ou Views/Shared/_Layout.cshtml (MVC):

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

    @await RenderSectionAsync("Scripts", required: false)
</body>

      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.

  2. 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.JSInterop
@using {APP NAMESPACE}

  3. Registre os Blazor Server serviços emStartup.ConfigureServices.

    Em Startup.cs:

    services.AddServerSideBlazor();

  4. Adicionar o ponto de extremidade do Hub Blazor aos pontos de extremidade (app.UseEndpoints) de Startup.Configure.

    Startup.cs:

    endpoints.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 (Pages Razor) 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";
}

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

    No exemplo anterior, substitua o espaço reservado {APP NAMESPACE} pelo namespace do aplicativo.

    MVC:

    Na exibição do Index projeto de um aplicativo MVC, adicione o Counter namespace do componente e encorpore o componente na exibição. Quando a exibição Index é carregada, o componente Counter é pré-renderizado na página. 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";
}

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

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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Observação

    Com a versão do .NET 5.0.1 e para quaisquer versões adicionais de 5.x, o Router componente inclui o PreferExactMatches parâmetro definido como @true. Para obter mais informações, consulte Migrar do ASP.NET Core 3.1 para o .NET 5.

  3. Adicionar uma página_Host ao projeto com o seguinte conteúdo.

    Pages/_Host.cshtml:

    @page "/blazor"
@{
    Layout = "_Layout";
}

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

    Os componentes usam o arquivo _Layout.cshtml compartilhado para o layout.

    RenderMode configura quando o componente App:

    • É 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 Startup.Configure de Startup.cs, adicione uma rota de baixa prioridade para a página _Host como o último ponto de extremidade:

    endpoints.MapFallbackToPage("/_Host");

    O exemplo a seguir mostra a linha adicionada na configuração do endpoint de um app típico.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Adicionar componentes roteáveis ao projeto.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Observação

    Com a versão do .NET 5.0.1 e para quaisquer versões adicionais de 5.x, o Router componente inclui o PreferExactMatches parâmetro definido como @true. Para obter mais informações, consulte Migrar do ASP.NET Core 3.1 para o .NET 5.

  3. Adicione uma _Host exibição ao projeto com o seguinte conteúdo.

    Views/Home/_Host.cshtml:

    @{
    Layout = "_Layout";
}

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

    Os componentes usam o arquivo _Layout.cshtml compartilhado para o layout.

    RenderMode configura quando o componente App:

    • É 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 Startup.Configure de Startup.cs, adicione uma rota de baixa prioridade para a ação do controlador que retorna à exibição _Host:

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

    O exemplo a seguir mostra a linha adicionada na configuração do endpoint de um app típico.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Adicionar componentes roteáveis ao projeto.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<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 componente Counter.

<h1>My 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ções de Componente no ASP.NET Core.

Renderizar componentes não interativos

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

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

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

Para mais informações, consulte Auxiliar de Marcações 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 marcador de posição {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.

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

Um estado pré-renderizado grande pode exceder Blazoro 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 interface do usuário de reconexão no cliente aparece 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 da mensagem SignalR. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos Blazor Server adicionais

Componentes do Razor podem ser incorporados em Páginas do Razor ou aplicativos MVC. Quando a página ou exibição é renderizada, os componentes podem ser pré-renderizados ao mesmo tempo.

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:

Configuração

Um aplicativo MVC ou Pages Razor existente pode integrar componentes Razor em páginas ou exibições:

  1. No arquivo de layout do projeto:

    • Adicionar a seguinte <base> marca ao <head> elemento em Pages/Shared/_Layout.cshtml (Razor Pages) ou Views/Shared/_Layout.cshtml (MVC):

      + <base href="~/" />

      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 subaplicativo, consulte o caminho base do aplicativo ASP.NET CoreBlazor.

    • Adicionar uma marca <script> para o script blazor.server.js imediatamente antes da seção de renderização Scripts.

      Pages/Shared/_Layout.cshtml (Pages Razor) ou Views/Shared/_Layout.cshtml (MVC):

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

    @await RenderSectionAsync("Scripts", required: false)
</body>

      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.

  2. 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.JSInterop
@using {APP NAMESPACE}

  3. Registre os Blazor Server serviços emStartup.ConfigureServices.

    Startup.cs:

    services.AddServerSideBlazor();

  4. Adicionar o ponto de extremidade do Hub Blazor aos pontos de extremidade (app.UseEndpoints) de Startup.Configure.

    Startup.cs:

    endpoints.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 (Pages Razor) 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";
}

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

    No exemplo anterior, substitua o espaço reservado {APP NAMESPACE} pelo namespace do aplicativo.

    MVC:

    Na exibição do Index projeto de um aplicativo MVC, adicione o Counter namespace do componente e encorpore o componente na exibição. Quando a exibição Index é carregada, o componente Counter é pré-renderizado na página. 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";
}

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

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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. Adicionar uma página_Host ao projeto com o seguinte conteúdo.

    Pages/_Host.cshtml:

    @page "/blazor"
@{
    Layout = "_Layout";
}

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

    Os componentes usam o arquivo _Layout.cshtml compartilhado para o layout.

    RenderMode configura quando o componente App:

    • É 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 Startup.Configure de Startup.cs, adicione uma rota de baixa prioridade para a página _Host como o último ponto de extremidade:

    endpoints.MapFallbackToPage("/_Host");

    O exemplo a seguir mostra a linha adicionada na configuração do endpoint de um app típico.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Adicionar componentes roteáveis ao projeto.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. Adicione uma _Host exibição ao projeto com o seguinte conteúdo.

    Views/Home/_Host.cshtml:

    @{
    Layout = "_Layout";
}

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

    Os componentes usam o arquivo _Layout.cshtml compartilhado para o layout.

    RenderMode configura quando o componente App:

    • É 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 Startup.Configure de Startup.cs, adicione uma rota de baixa prioridade para a ação do controlador que retorna à exibição _Host:

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

    O exemplo a seguir mostra a linha adicionada na configuração do endpoint de um app típico.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Adicionar componentes roteáveis ao projeto.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<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 componente Counter.

<h1>My 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ções de Componente no ASP.NET Core.

Renderizar componentes não interativos

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

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

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

Para mais informações, consulte Auxiliar de Marcações 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 marcador de posição {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.

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

Um estado pré-renderizado grande pode exceder Blazoro 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 interface do usuário de reconexão no cliente aparece 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 da mensagem SignalR. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos Blazor Server adicionais