ASP.NET Fundamentos do Blazor básico

Fundamentos artigos fornecem orientação sobre conceitos de Blazor fundamentais. Alguns dos conceitos estão ligados a uma compreensão básica de componentes Razor, que são descritos mais detalhadamente na próxima seção deste artigo e abordados em detalhes 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 acontece no cliente ou no lado do cliente. Diz-se que a atividade que ocorre num servidor ocorre no servidor ou do lado servidor .

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

• A renderização do lado do cliente (CSR) significa que a marcação HTML final é gerada pelo tempo de execução do .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 é assumida. Não existe esse conceito de renderização estática do lado do cliente. Assume-se que a renderização do lado do cliente (CSR) é interativa, pelo que "interativa renderização do lado do cliente" e "interativa CSR" não são utilizados pela indústria ou na documentação Blazor.

• 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. SSR pode ser de duas variedades:

  • SSR estático: O servidor produz HTML estático que não permite a interatividade do utilizador ou a manutenção do Razor estado do componente.
  • Interactive SSR: Blazor eventos permitem a interatividade dos utilizadores e Razor o estado do componente é mantido pela estrutura Blazor.

• de 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 emite a interface HTML da página o mais rapidamente possível em resposta à solicitação inicial, tornando o aplicativo mais responsivo para os usuários. A prerenderização também pode melhorar a Search Engine Optimization (SEO), renderizando conteúdo para a resposta HTTP inicial que os mecanismos de pesquisa usam para calcular o Page Rank. A pré-renderização é sempre seguida pela renderização final, seja no servidor ou no cliente.

Componentes Razor

Blazor aplicativos são baseados em componentes Razor, muitas vezes referidos como apenas componentes . Um componente é um elemento da interface do usuário, como uma página, caixa de diálogo ou formulário de entrada de dados. Os componentes são classes .NET C# incorporadas em 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. Razor é uma sintaxe para combinar marcação HTML com código C# projetado para produtividade do desenvolvedor. Os ficheiros Razor usam a extensão de ficheiro .razor.

Embora alguns desenvolvedores Blazor e recursos on-line usem o termo "componentesBlazor", a documentação evita esse termo e usa universalmente "componentesRazor" ou "componentes".

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

• Geralmente, os exemplos aderem às convenções de codificação e diretrizes de engenharia ASP.NET Core/C#. Para obter mais informações, consulte os seguintes recursos:
  • Diretrizes de engenharia do framework ASP.NET Core (dotnet/aspnetcore repositório no GitHub)
  • Convenções de codificação em C# (guia em C#)
• Código do projeto, caminhos e nomes de arquivos, nomes de modelos de projeto e outros termos especializados estão em inglês dos Estados Unidos e geralmente cercados por código.
• Os componentes são geralmente referidos pelo nome da classe C# (caso Pascal) seguido pela palavra "componente". Por exemplo, um componente típico de upload de arquivos é chamado de componente "FileUpload".
• Normalmente, o nome da classe C# de um componente é o mesmo que o nome do arquivo.
• Os componentes roteáveis geralmente definem as suas URLs relativas com base no 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 de roteamento e navegação.
• Quando várias versões de um componente são usadas, elas são numeradas sequencialmente. Por exemplo, o componente FileUpload3 é atingido 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 exemplo. Por exemplo, private é indicado para declarar um campo chamado maxAllowedFiles como private int maxAllowedFiles = 3;.
• Os valores de do parâmetro Component levam com um símbolo de Razor reservado @, mas não é obrigatório. Literais (por exemplo, valores booleanos), palavras-chave (por exemplo, this) e null como valores de parâmetros de componentes 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.
• As classes 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 da estrutura ASP.NET Core .
• Em exemplos que usam construtores primários (C# 12 ou posterior), os parâmetros do construtor primário são normalmente usados diretamente pelos membros da classe. Em exemplos de artigos, as linhas de código são divididas para reduzir a rolagem horizontal. Essas quebras não afetam a execução, mas podem ser removidas quando coladas no seu projeto.

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

A seguir está um exemplo de componente de contador e parte de um aplicativo criado a partir de um modelo de projeto Blazor. A cobertura detalhada dos componentes encontra-se nos artigos Componentes mais adiante na documentação. O exemplo a seguir demonstra os conceitos de componentes vistos nos artigos do Fundamentals antes de chegar aos Components artigos mais adiante 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 o seu percurso com a diretiva @page em primeira linha.
• Define o título da página e o cabeçalho.
• Renderiza a contagem atual com @currentCount. currentCount é uma variável inteira definida no código C# do bloco @code.
• Exibe um botão para acionar o método IncrementCount, que também é encontrado no bloco @code e aumenta o valor da variável currentCount.

Modelo de objeto de documento (DOM)

As referências ao Document Object Model usam a abreviatura DOM.

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

• Introdução ao DOM (documentação MDN)
• Especificação de modelo de objeto de documento (W3C) de nível 1

Subconjunto de APIs .NET para aplicativos Blazor WebAssembly

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

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

• Bibliotecas de classes: Analisador de compatibilidade de navegadores cliente
• Anotando APIs como não suportadas 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 exemplos de repositório GitHub (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.

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

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

BasicTestApp em ASP.NET fonte de referência principal (dotnet/aspnetcore)

Para descarregar as aplicações de exemplo:

• Faça o download do arquivo ZIP do repositório de amostras Blazor.
• Descompacte o arquivo.

Múltiplos de bytes

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

Pedidos de suporte

Somente questões relacionadas à documentação são apropriadas para o repositório dotnet/AspNetCore.Docs. Para suporte ao produto, não abra um problema de documentação. Procure assistência através de um ou mais dos seguintes canais de apoio:

• Stack Overflow (marcado: blazor)
• Equipe Geral ASP.NET Core Slack
• Blazor Gitter

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

• Explicação clara do problema: Siga as instruções no modelo de problema do GitHub fornecido pela unidade de produto ao abrir o problema.
• Projeto de reprodução mínima: Coloque um projeto no GitHub para os engenheiros da unidade de produto baixarem e executarem. Ligue o projeto ao comentário inicial do problema.

Para um problema potencial com um artigo Blazor, abra um problema de documentação. Para abrir um problema de documentação, use o link de feedback Abrir um problema de documentação na parte inferior do artigo. Os metadados adicionados ao seu problema fornecem dados de acompanhamento e enviam automaticamente pings ao autor do artigo. Se o assunto foi discutido com a unidade de produto antes de abrir o 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 o Visual Studio, use os gestos "Reportar um Problema" ou "Sugerir uma Funcionalidade" no Visual Studio, que abrem problemas internos para o Visual Studio. Para obter mais informações, consulte Visual Studio Feedback.

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

Os problemas do GitHub da documentação Blazor são automaticamente marcados para triagem do projeto Blazor.Docs (repositório GitHubdotnet/AspNetCore.Docs). Por favor, aguarde um pouco para uma resposta, especialmente nos fins de semana e feriados. Normalmente, os autores da documentação respondem dentro de 24 horas nos dias úteis.

Links da comunidade para recursos Blazor

Para aceder a um conjunto de ligações para recursos Blazor mantidos pela comunidade, visite Incrível Blazor.