Fundamentos do ASP.NET Core Blazor

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 o código HTML que os navegadores exibem.

• Client-side rendering (CSR) significa que a marcação HTML final é gerada pelo runtime .NET 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.

• Server-side rendering (SSR) significa que a marcação HTML final é gerada pelo runtime 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 HTML da página o mais rápido possível em resposta à solicitação inicial, o que faz o aplicativo parecer mais responsivo para os usuários. A pré-renderização também pode melhorar a SEO (Otimização para Motores de Busca) ao renderizar conteúdo na resposta HTTP inicial que os mecanismos de pesquisa usam para calcular o ranking da página. A pré-renderização é sempre seguida pela renderização final, seja no servidor ou no cliente.

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 .NET classes C# integradas a assemblies .NET.

Razor refere-se a como os componentes geralmente são escritos na forma de uma página de marcação Razor para lógica e 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:

• Em geral, os exemplos aderem às convenções de codificação ASP.NET Core/C# e às diretrizes de engenharia. Para mais informações, consulte os seguintes recursos:
  • Diretrizes de engenharia do framework ASP.NET Core (dotnet/aspnetcore repositório GitHub)
  • Convenções de codificação em C# (guia de C#)
• Código do projeto, caminhos de arquivo e nomes, nomes de modelo do projeto e outros termos especializados estão em inglês dos Estados Unidos e geralmente cercados 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 ASP.NET Core Blazor roteamento.
• 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.
• Razor diretivas 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.
• Embora não sejam necessários para membros private, os modificadores de acesso são usados em exemplos de artigos e aplicativos de amostra. 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 você quiser.
• As classes em C# usam a palavra-chave this e evitam prefixar com um sublinhado (_) os campos que são atribuídos em construtores, o que difere das diretrizes de engenharia do framework ASP.NET Core.
• Em exemplos que usam construtores primários (C# 12 ou mais recente), os parâmetros do construtor primário normalmente são usados diretamente pelos membros da classe. Nos exemplos de artigo, as linhas de código são divididas para reduzir a rolagem horizontal. Essas quebras não afetam a execução e podem ser removidas ao serem coladas no seu projeto.

Informações adicionais sobre a sintaxe do componente Razor são fornecidas na seção Razor sintaxe de componentes ASP.NET Core Razor.

Veja a seguir um exemplo de componente de contador que faz 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:

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

<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 cabeçalho da 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.

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:

• Introdução ao DOM (documentação do MDN)
• Especificação do Modelo de Objeto do Documento Nível 1 (W3C).

Subconjunto de APIs de .NET para aplicativos Blazor WebAssembly

Uma lista selecionada de APIs de .NET específicas com suporte no navegador para Blazor WebAssembly não está disponível. No entanto, você pode procurar manualmente por uma lista de APIs .NET anotadas com [UnsupportedOSPlatform("browser")] para descobrir APIs .NET que não têm suporte no WebAssembly.

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

• Bibliotecas de Classes: analisador de compatibilidade do navegador do lado do cliente
• Annotando APIs como sem suporte em plataformas específicas (dotnet/designs repositório GitHub

Aplicativos de exemplo

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

Blazor repositório de amostras do GitHub (dotnet/blazor-samples)

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

Os aplicativos de exemplo contêm apenas um subconjunto de exemplos de artigos para Blazor demonstrações de funcionalidades. Quando um exemplo de código mostrado por um artigo não está em um ou mais dos aplicativos de exemplo, você geralmente pode colocar o código de exemplo em um aplicativo de teste local para uma demonstração.

Para obter mais informações, uma lista dos exemplos no repositório e as instruções de download, consulte o arquivo README do repositório GitHub de exemplos.

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

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

Múltiplos de bytes

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

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:

• Stack Overflow (etiquetado com: blazor)
• General ASP.NET Core Slack Team
• Blazor Gitter

Para um eventual bug no framework ou comentários sobre o produto, registre um problema no produto ASP.NET Core em dotnet/aspnetcore problemas. Os relatórios de bug geralmente exigem o seguinte:

• Explicação clara do problema: siga as instruções no modelo de issue do GitHub fornecido pela equipe do produto ao criar a issue.
• Projeto de reprodução mínima: coloque um projeto no GitHub para que os engenheiros da unidade de produto possam baixar e executar. 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 link de comentários Abrir um problema de documentação na parte inferior do artigo. Os metadados adicionados ao seu problema fornecem dados de rastreamento e pingam automaticamente o autor do artigo. Se o assunto foi discutido com a unidade do produto antes da abertura do problema de documentação, coloque um link cruzado para o problema de engenharia no comentário de abertura do problema de documentação.

Para problemas ou comentários sobre Visual Studio, use os gestos Reportar um problema ou Suggest a Feature de dentro Visual Studio, que abrem problemas internos para Visual Studio. Para obter mais informações, consulte Visual Studio Feedback.

Para problemas com Visual Studio Code, peça apoio em fóruns de apoio à comunidade. Para relatórios de bugs e comentários do produto, abra um problema no repositório microsoft/vscode GitHub.

Problemas no GitHub para a documentação de Blazor são automaticamente marcados para triagem no projeto Blazor.Docs (dotnet/AspNetCore.Docs repositório do GitHub). 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.

Links da comunidade para recursos Blazor

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