Ler em inglês

Compartilhar via

Integrar ASP.NET componentes principais Razor com MVC ou Razor Pages

  • Artigo

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.

Razor podem ser integrados em Razor aplicativos Pages ou MVC. Componentes podem ser pré-renderizados ao mesmo tempo após a renderização da página ou exibição.

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

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

  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:

    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:

      CSHTML 
      <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(...)):

      HTML 
      <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:

    C# 
    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):

    C# 
    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):

    razor 
    <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:

    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:

    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:

    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:

    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:

    C# 
    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:

    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:

    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:

    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:

    C# 
    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:

    C# 
    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:

    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:

CSHTML 
<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:

CSHTML 
<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.
CSHTML 
@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 um dos Blazor aplicativos que estão ServerPrerendered em um Blazor Server aplicativo:

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. 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).
razor 
@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 com base no modelo de Blazor 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:

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.

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 grande tamanho de estado pré-renderizado pode exceder Blazoro limite de tamanho da mensagem do SignalR 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 daSignalR mensagem. 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

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

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 oControle 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):

      CSHTML 
      <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 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 imediatamente antes da Scripts seção de renderização (@await RenderSectionAsync(...)) no layout do aplicativo.

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

      HTML 
      <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:

    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:

    C# 
    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):

    C# 
    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):

    razor 
    <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:

    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:

    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:

    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:

    CSHTML 
    @page "/blazor"
@namespace {APP NAMESPACE}.Pages.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 oControle de Conteúdo de CabeçalhoBlazor em aplicativos do ASP.NET Core.

    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:

    C# 
    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:

    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:

    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.

    Views/Home/_Host.cshtml:

    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 oControle de Conteúdo de CabeçalhoBlazor em aplicativos do ASP.NET Core.

    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:

    C# 
    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:

    C# 
    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:

    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:

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

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 oControle de Conteúdo de CabeçalhoBlazor em aplicativos do 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:

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

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 oControle 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 espaço reservado {APP NAMESPACE} é o namespace do projeto. Components representa o nome da pasta.
CSHTML 
@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:

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. Há recuperação do estado com a retomada do aplicativo.

O exemplo a seguir é uma versão atualizada do FetchData componente com base no modelo de Blazor 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:

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()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistForecasts);

        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            "fetchdata", out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(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.

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 grande tamanho de estado pré-renderizado pode exceder Blazoro limite de tamanho da mensagem do SignalR 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 daSignalR mensagem. 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 Pages ou MVC existente Razor pode integrar Razor componentes 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):

      HTML 
      <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 subaplicação, siga as diretrizes na seção Caminho Base do aplicativo do artigo Hospedar e implantar ASP.NET CoreBlazor.

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

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

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

    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.

    No Startup.cs:

    C# 
    services.AddServerSideBlazor();

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

    Startup.cs:

    C# 
    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 (Razor Pages) ou Views/Shared/Counter.razor (MVC):

    razor 
    <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:

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

    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:

    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 ASP.NET Core 5.0.1 e para qualquer lançamento adicional do 5.x, o componente Router inclui o parâmetro PreferExactMatches definido como @true. Para obter mais informações, consulte Migrar do ASP.NET Core 3.1 para o 5.0.

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

    Pages/_Host.cshtml:

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

    C# 
    endpoints.MapFallbackToPage("/_Host");

    O exemplo a seguir mostra a linha adicionada na configuração do ponto de extremidade de um aplicativo típico:

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

  5. Adicionar componentes roteáveis ao projeto.

    Pages/RoutableCounter.razor:

    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:

    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 ASP.NET Core 5.0.1 e para qualquer lançamento adicional do 5.x, o componente Router inclui o parâmetro PreferExactMatches definido como @true. Para obter mais informações, consulte Migrar do ASP.NET Core 3.1 para o 5.0.

  3. Adicionar exibição_Host ao projeto com o seguinte conteúdo.

    Views/Home/_Host.cshtml:

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

    C# 
    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:

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

    O exemplo a seguir mostra a linha adicionada na configuração do ponto de extremidade de um aplicativo típico:

    C# 
    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:

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

CSHTML 
<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 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:

CSHTML 
<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 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.
CSHTML 
@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 grande tamanho de estado pré-renderizado pode exceder Blazoro limite de tamanho da mensagem do SignalR 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 daSignalR mensagem. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos Blazor Server adicionais

Razor podem ser integrados em Razor aplicativos Pages ou 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:

Configuração

Um aplicativo Pages ou MVC existente Razor pode integrar Razor componentes 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):

      diff 
      + <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 subaplicação, siga as diretrizes na seção Caminho Base do aplicativo do artigo Hospedar e implantar ASP.NET CoreBlazor.

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

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

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

    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:

    C# 
    services.AddServerSideBlazor();

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

    Startup.cs:

    C# 
    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 (Razor Pages) ou Views/Shared/Counter.razor (MVC):

    razor 
    <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:

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

    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:

    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:

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

    C# 
    endpoints.MapFallbackToPage("/_Host");

    O exemplo a seguir mostra a linha adicionada na configuração do ponto de extremidade de um aplicativo típico:

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

  5. Adicionar componentes roteáveis ao projeto.

    Pages/RoutableCounter.razor:

    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:

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

    Views/Home/_Host.cshtml:

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

    C# 
    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:

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

    O exemplo a seguir mostra a linha adicionada na configuração do ponto de extremidade de um aplicativo típico:

    C# 
    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:

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

CSHTML 
<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 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:

CSHTML 
<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 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.
CSHTML 
@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 grande tamanho de estado pré-renderizado pode exceder Blazoro limite de tamanho da mensagem do SignalR 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 daSignalR mensagem. AVISO: aumentar o limite pode aumentar o risco de ataques de negação de serviço (DoS).

Recursos Blazor Server adicionais