Conceitos básicos do ASP.NET Core Blazor

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 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 informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Artigos de conceitos básicos fornecem diretrizes sobre conceitos fundamentais de Blazor. Alguns dos conceitos estão conectados a uma compreensão básica dos componentes Razor, que são descritos com mais detalhes na próxima seção deste artigo e abordados detalhadamente nos artigos de Componentes.

Conceitos de renderização de cliente e servidor

Ao longo da documentação Blazor, diz-se que a atividade que ocorre no sistema do usuário ocorre no cliente ou lado do cliente. Diz-se que a atividade que ocorre em um servidor ocorre no servidor ou lado do servidor.

O termo renderização significa produzir a marcação HTML que os navegadores exibem.

  • A renderização no lado do cliente (CSR) significa que a marcação HTML final é gerada pelo runtime Blazor WebAssembly no cliente. Nenhum HTML para a interface do usuário gerada pelo cliente do aplicativo é enviado de um servidor para o cliente para esse tipo de renderização. A interatividade do usuário com a página é presumida. Não existe o conceito de renderização estática do lado do cliente. Presume-se que a CSR seja interativa, portanto, a "renderização do lado do clienteinterativa" e a "CSR interativa" não são usadas pelo setor ou pela documentação Blazor.

  • A renderização do lado do servidor (SSR) significa que a marcação HTML final é gerada pelo runtime do ASP.NET Core no servidor. O HTML é enviado ao cliente através de uma rede para exibição pelo navegador do cliente. Nenhum HTML para a interface do usuário gerada pelo servidor do aplicativo é criado pelo cliente para esse tipo de renderização. O SSR pode ser de duas variedades:

    • SSR estática: o servidor produz HTML estático que não fornece interatividade do usuário nem mantém o estado do componente Razor.
    • SSR interativa: os eventos Blazor permitem a interatividade do usuário e o estado do componente Razor é mantido pela estrutura Blazor.

  • A pré-renderização é o processo de renderizar inicialmente o conteúdo da página no servidor sem habilitar manipuladores de eventos para controles renderizados. O servidor gera a interface do usuário HTML da página o mais rápido possível em resposta à solicitação inicial, o que dá a sensação de que o aplicativo é mais responsivo aos usuários. A pré-renderização também 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 usam para calcular a classificação da página. A pré-renderização é sempre seguida pela renderização final, seja no servidor ou no cliente.

Conceitos de renderização estática e interativa

Razor componentes são renderizados estaticamente ou renderizados interativamente renderizados.

Renderização estática ou estática é um cenário do lado do servidor que significa que o componente é renderizado sem a capacidade de interação entre o usuário e o código .NET/C#. Os eventos JavaScript e HTML DOM permanecem inalterados, mas nenhum evento de usuário no cliente pode ser processado com o .NET em execução no servidor.

Renderização interativa ou interativa significa que o componente tem a capacidade de processar eventos .NET por meio de código C#. Os eventos .NET são processados no servidor pelo tempo de execução do ASP.NET Core ou no navegador no cliente pelo tempo de execução do Blazor baseado em WebAssembly.

Mais informações sobre esses conceitos e como controlar a renderização estática e interativa são encontradas no ASP.NET Core Blazor modos de renderização artigo mais adiante na documentação Blazor.

Componentes Razor

Aplicativos Blazor são baseados em componentes Razor, geralmente chamados apenas de componentes. Um componente é um elemento da interface do usuário, como uma página, uma caixa de diálogo ou um formulário de entrada de dados. Os componentes são classes C# do .NET incorporados a assemblies .NET.

Razor refere-se a como os componentes geralmente são gravados no formulário de uma página de marcação Razor para a lógica e a composição da interface do usuário do lado do cliente. O Razor é uma sintaxe para a combinação de marcação HTML com o código C# projetada para melhorar a produtividade do desenvolvedor. Arquivos Razor usam a extensão de arquivo .razor.

Embora alguns desenvolvedores de Blazor e recursos online usem o termo "componentes Blazor", a documentação evita esse termo e usa universalmente "componentes Razor" ou "componentes".

A documentação do Blazor adota várias convenções para mostrar e discutir componentes:

  • Código do projeto, caminhos de arquivo e nomes, nomes de modelo de projeto e outros termos especializados estão em inglês dos Estados Unidos e geralmente são limitados por código.
  • Os componentes geralmente são referenciados pelo nome da classe C# (Pascal case) seguido pela palavra "componente". Por exemplo, um componente de upload de arquivo típico é chamado de "componente FileUpload".
  • Normalmente, o nome da classe C# de um componente é o mesmo que seu nome de arquivo.
  • Os componentes roteáveis geralmente definem suas URLs relativas como o nome da classe do componente em kebab case. Por exemplo, um componente FileUpload inclui a configuração de roteamento para alcançar o componente renderizado na URL relativa /file-upload. O roteamento e a navegação são abordados em Roteamento e navegação do ASP.NET Core Blazor.
  • Quando várias versões de um componente são usadas, elas são numeradas sequencialmente. Por exemplo, o componente FileUpload3 é alcançado em /file-upload-3.
  • As diretivas Razor na parte superior de uma definição de componente (.razor file) são colocadas na seguinte ordem: @page, @rendermode (.NET 8 ou posterior), instruções @using, outras diretivas em ordem alfabética. Informações adicionais sobre a ordenação de diretivas Razor podem ser encontradas na seção de Razorsintaxe de componentes do Razor do ASP.NET Core.
  • Modificadores de acesso são usados em exemplos de artigo. Por exemplo, os campos são private por padrão, mas estão presentes explicitamente no código do componente. Por exemplo, private é declarado para declarar um campo chamado maxAllowedFiles como private int maxAllowedFiles = 3;.
  • Os valores do parâmetro do componentelevam a um Razor símbolo@ reservado, mas isso não é necessário. Literais (por exemplo, valores boolianos), palavras-chave (por exemplo, this) e null como valores de parâmetro do componente não são prefixados com @, mas isso também é apenas uma convenção de documentação. Seu próprio código pode prefixar literais com @, se desejar.
  • Geralmente, os exemplos aderem às convenções de codificação e às diretrizes de engenharia do ASP.NET Core/C#. Para obter mais informações, consulte os seguintes recursos:

Veja a seguir um componente de contador de exemplo e parte de um aplicativo criado a partir de um modelo de projeto Blazor. A cobertura de componentes detalhada é encontrada nos artigos de Componentes posteriormente na documentação. O exemplo a seguir demonstra os conceitos de componente vistos nos artigos de Conceitos básicos antes de chegar aos artigos de Componentes posteriormente na documentação.

Counter.razor:

O componente pressupõe que um modo de renderização interativo seja herdado de um componente pai ou aplicado globalmente ao aplicativo.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<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++;
    }
}

@page "/counter"

<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++;
    }
}

O componente Counter anterior:

  • Define sua rota com a diretiva @page na primeira linha.
  • Define o título e o título de página.
  • Renderiza a contagem atual com @currentCount. currentCount é uma variável inteira definida no código C# do bloco @code.
  • Exibe um botão para disparar o método IncrementCount, que também é encontrado no bloco @code e aumenta o valor da variável currentCount.

Modos de renderização

Os artigos no nó Fundamentos fazem referência ao conceito de modos de renderização. Este assunto é abordado em detalhes no artigo ASP.NET Core Blazor modos de renderização no nó Componentes, que aparece após o nó Fundamentos dos artigos.

Para que as primeiras referências neste nó de artigos forneçam conceitos de modo, basta observar o seguinte neste momento:

Cada componente em um Blazor Web App adota um modo de renderização para determinar o modelo de hospedagem que ele usa, onde é renderizado e se é ou não renderizado estaticamente no servidor, renderizado com interatividade do usuário no servidor ou renderizado para interatividade do usuário no cliente (geralmente com pré-renderização no servidor).

Aplicativos Blazor Server e Blazor WebAssembly para versões do ASP.NET Core anteriores ao .NET 8 permanecem fixados em conceitos de modelo de hospedagem e não em modos de renderização. Os modos de renderização são aplicados conceitualmente a Blazor Web Apps no .NET 8 ou posterior.

A tabela a seguir mostra os modos de renderização disponíveis para a renderização de componentes Razor em um aplicativo Web Blazor. Os modos de renderização são aplicados a componentes com a diretiva @rendermode na instância do componente ou na definição do componente. Também é possível definir um modo de renderização para todo o aplicativo.

Nome Descrição Local de renderização Interativo
Servidor estático Renderização do lado do servidor estática (SSR estática) Servidor
Servidor interativo Renderização do lado do servidor interativa (SSR interativa) usando Blazor Server Servidor
WebAssembly interativo Renderização do lado do cliente (CSR) usando Blazor WebAssembly† Cliente
Auto interativo SSR interativa usando Blazor Server inicialmente e, em seguida, CSR em visitas subsequentes depois que o pacote Blazor é baixado Servidor, depois o cliente

†A renderização do lado do cliente (CSR) é considerada interativa. A "renderização do lado do cliente interativa" e a "CSR interativa" não são usadas pelo setor ou na documentação Blazor.

As informações anteriores sobre modos de renderização são tudo o que você precisa saber para entender os artigos do nó Fundamentos. Se você é novo em Blazor e ler Blazor artigos em ordem no índice, pode adiar o consumo de informações detalhadas sobre modos de renderização até chegar ao artigo ASP.NET Core Blazor modos de renderização no nó Componentes.

Modelo de Objeto do Documento (DOM)

As referências ao Modelo de Objeto de Documento utilizam a abreviação DOM.

Para obter mais informações, consulte os seguintes recursos:

Subconjunto de APIs .NET para aplicativos Blazor WebAssembly

Não há uma lista coletada de APIs .NET específicas que dão suporte para Blazor WebAssembly no navegador. No entanto, você pode pesquisar manualmente uma lista de APIs do .NET anotadas com [UnsupportedOSPlatform("browser")] para descobrir as APIs do .NET que não têm suporte no WebAssembly.

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

Para saber mais, consulte os recursos a seguir:

Aplicativos de exemplo

Os aplicativos de exemplo de documentação estão disponíveis para inspeção e download:

Repositório GitHub de exemplos do Blazor (dotnet/blazor-samples)

Localize um aplicativo de exemplo selecionando primeiro a pasta de versão que corresponde à versão do .NET com a qual você está trabalhando.

Exemplos de aplicativos no repositório:

O repositório de amostra contém dois tipos de exemplos:

  • Os aplicativos de amostra de snippet fornecem os exemplos de código que aparecem nos artigos. Esses aplicativos compilam, mas não são necessariamente aplicativos executáveis. Esses aplicativos são úteis apenas para obter os exemplos de código que aparecem em artigos.
  • Exemplos de aplicativos para acompanhar artigos Blazor compilados e executados para os seguintes cenários:
    • Blazor Server com EF Core
    • Blazor Server e Blazor WebAssembly com SignalR
    • Blazor WebAssembly registro em log habilitado para escopos

Para obter mais informações, confira o arquivo README.md do repositório do GitHub de amostras do Blazor.

O aplicativo de teste básico do repositório do ASP.NET Core também é um conjunto útil de amostras para vários cenários do Blazor:

BasicTestApp na fonte de referência do ASP.NET Core (dotnet/aspnetcore)

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

Para baixar os aplicativos de exemplo:

Múltiplos de bytes

Os tamanhos de bytes do .NET usam prefixos de métrica para múltiplos não decimais de bytes com base em potências de 1024.

Nome (abreviação) Tamanho Exemplo
Quilobyte (KB) 1\.024 bytes 1 KB = 1.024 bytes
Megabyte (MB) 1.0242 bytes 1 MB = 1.048.576 bytes
Gigabyte (GB) 1.0243 bytes 1 GB = 1.073.741.824 bytes

Solicitações de suporte

Somente problemas relacionados à documentação são apropriados para o repositório dotnet/AspNetCore.Docs. Para suporte ao produto, não abra um problema de documentação. Busque assistência em um ou mais dos seguintes canais de suporte:

Para relatar um possível bug na estrutura ou fazer comentários sobre o produto, abra um problema para a unidade do produto ASP.NET Core em problemas do dotnet/aspnetcore. Os relatórios de bug geralmente exigem o seguinte:

  • Explicação clara do problema: siga as instruções no modelo de problema do GitHub fornecido pela unidade do produto ao abrir o problema.
  • Projeto de reprodução mínima: coloque um projeto no GitHub para que os engenheiros de unidade de produto baixem e executem. Coloque um link cruzado no comentário de abertura do problema.

Para um possível problema com um artigo o Blazor, abra um problema de documentação. Para abrir um problema de documentação, use o botão de comentários nesta página e o formulário na parte inferior do artigo e deixe os metadados ativos ao criar o comentário de abertura. Os metadados fornecem dados de rastreamento e pingam automaticamente o autor do artigo. Se o assunto foi discutido com a unidade do produto, coloque um link cruzado para o problema de engenharia no comentário de abertura da documentação.

Para problemas ou comentários no Visual Studio, use os gestos Relatar um problema ou Sugerir um recurso dentro do Visual Studio, que abrem problemas internos para o Visual Studio. Para saber mais, confira Comentários do Visual Studio.

Para problemas com o Visual Studio Code, solicite suporte em fóruns de apoio à comunidade. Para relatórios de bugs e comentários sobre produtos, abra um problema no repositório do GitHub microsoft/vscode.

Os problemas do GitHub para documentação de Blazor são marcados automaticamente para triagem no projeto Blazor.Docs (repositório do GitHub dotnet/AspNetCore.Docs). Aguarde um pouco por uma resposta, especialmente nos fins de semana e feriados. Normalmente, os autores da documentação respondem dentro de 24 horas durante a semana.

Para obter uma coleção de links para recursos Blazor mantidos pela comunidade, visite Awesome Blazor.

Observação

A Microsoft não possui, mantém nem dá suporte ao Awesome Blazor e à maioria dos produtos e serviços da comunidade descritos e vinculados lá.