Visão geral de conceitos básicos do ASP.NET Core

Note

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

Warning

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 do .NET 10 deste artigo.

Este artigo fornece uma visão geral dos conceitos básicos para a criação de aplicativos ASP.NET Core, incluindo DI (injeção de dependência), configuração e middleware.

Para obter orientação sobre Blazor fundamentos, que adicionam ou substituem a orientação no artigo, veja os fundamentos do ASP.NET CoreBlazor.

O arquivo Program

Aplicativos ASP.NET Core criados a partir dos modelos de projeto do framework contêm código de inicialização no arquivo Program (Program.cs). O arquivo Program é onde:

  • Os serviços exigidos pelo aplicativo são configurados.
  • O pipeline de tratamento de solicitações do aplicativo é definido como uma série de componentes de middleware.

O código de inicialização do aplicativo a seguir dá suporte a dois tipos de aplicativo:

// Initialize a new instance of the WebApplicationBuilder class 
// with preconfigured defaults
var builder = WebApplication.CreateBuilder(args);

// Add services for Blazor (Razor components)
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// Build the app
var app = builder.Build();

// Use exception-handling middleware and HSTS middleware
// when in the Development environment
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePagesWithReExecute("/not-found", createScopeForStatusCodePages: true);

// Use HTTPS redirection middleware to automatically
// redirect requests from HTTP to HTTPS
app.UseHttpsRedirection();

// Map static assets endpoints
app.MapStaticAssets();

// Map a Minimal API endpoint for requests to '/hi'
app.MapGet("/hi", () => "Hello!");

// Add endpoints for Blazor
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

// Run the app
app.Run();

Note

Com configuração adicional no arquivo Program, os aplicativos ASP.NET Core podem oferecer suporte a Razor Páginas, MVC e API da Web com controladores.

O código de inicialização do aplicativo a seguir dá suporte a dois tipos de aplicativo:

// Initialize a new instance of the WebApplicationBuilder class 
// with preconfigured defaults
var builder = WebApplication.CreateBuilder(args);

// Add services for Blazor (Razor components)
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// Build the app
var app = builder.Build();

// Use exception-handling middleware and HSTS middleware
// when in the Development environment
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePagesWithReExecute("/not-found", createScopeForStatusCodePages: true);

// Use HTTPS redirection middleware to automatically
// redirect requests from HTTP to HTTPS
app.UseHttpsRedirection();

// Add antiforgery middleware
app.UseAntiforgery();

// Map static assets endpoints
app.MapStaticAssets();

// Map a Minimal API endpoint for requests to '/hi'
app.MapGet("/hi", () => "Hello!");

// Add endpoints for Blazor
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

// Run the app
app.Run();

Note

Com configuração adicional no arquivo Program, os aplicativos ASP.NET Core podem oferecer suporte a Razor Páginas, MVC e API da Web com controladores.

O código de inicialização do aplicativo a seguir dá suporte a vários tipos de aplicativo:

// Initialize a new instance of the WebApplicationBuilder class 
// with preconfigured defaults
var builder = WebApplication.CreateBuilder(args);

// Add services for Blazor (Razor components), Razor Pages, and MVC
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

// Build the app
var app = builder.Build();

// Configure the HTTP request pipeline

// Use exception-handling middleware and HSTS middleware
// when in the Development environment
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use HTTPS redirection middleware to automatically
// redirect requests from HTTP to HTTPS
app.UseHttpsRedirection();

// Use static files middleware to serve static assets
app.UseStaticFiles();

// Use authorization middleware
app.UseAuthorization();

// Add antiforgery middleware
app.UseAntiforgery();

// Map a Minimal API endpoint for requests to '/hi'
app.MapGet("/hi", () => "Hello!");

// Configures the standard conventional route for MVC
app.MapDefaultControllerRoute();

// Add endpoints for Razor Pages
app.MapRazorPages();

// Add endpoints for Blazor
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

// Run the app
app.Run();

O seguinte código de inicialização do aplicativo dá suporte a:

// Initialize a new instance of the WebApplicationBuilder class 
// with preconfigured defaults
var builder = WebApplication.CreateBuilder(args);

// Add services for Razor Pages and MVC
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

// Build the app
var app = builder.Build();

// Configure the HTTP request pipeline

// Use exception-handling middleware and HSTS middleware
// when in the Development environment
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use HTTPS redirection middleware to automatically
// redirect requests from HTTP to HTTPS
app.UseHttpsRedirection();

// Use static files middleware to serve static assets
app.UseStaticFiles();

// Use authorization middleware
app.UseAuthorization();

// Map a Minimal API endpoint for requests to '/hi'
app.MapGet("/hi", () => "Hello!");

// Configures the standard conventional route for MVC
app.MapDefaultControllerRoute();

// Add endpoints for Razor Pages
app.MapRazorPages();

// Run the app
app.Run();

A classe Startup

A Startup classe (Startup.cs) é onde:

  • Os serviços exigidos pelo aplicativo são configurados no ConfigureServices método.
  • O fluxo de processamento de solicitações do aplicativo é definido no método Configure como uma sequência de componentes de middleware.

O seguinte código de inicialização do aplicativo dá suporte a:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<RazorPagesMovieContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

        services.AddControllersWithViews();
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute();
            endpoints.MapRazorPages();
        });
    }
}

Para obter mais informações, consulte Inicialização de aplicativo no ASP.NET Core e inicialização no ASP.NET CoreBlazor.

Injeção de dependência (serviços)

O ASP.NET Core apresenta recursos internos de injeção de dependência (DI), que disponibilizam os serviços configurados em todo o aplicativo para inversão de controle (IoC).

Quando o WebApplicationBuilder é instanciado ao chamar WebApplication.CreateBuilder, os serviços fornecidos pelo framework são adicionados automaticamente, como serviços de configuração e de log:

var builder = WebApplication.CreateBuilder(args);

Serviços adicionais são adicionados ao contêiner de DI com WebApplicationBuilder.Services. O exemplo a seguir registra os serviços Blazor:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
builder.Services.AddServerSideBlazor();

O framework de DI fornece instâncias dos serviços solicitados em tempo de execução. Em aplicativos Blazor, os serviços geralmente são resolvidos a partir da DI no tempo de execução usando a diretiva @inject em um arquivo Razor de componente (.razor). No exemplo a seguir, o componente usa a abstração NavigationManager para obter uma instância do gerenciador de navegação, que é usada para consultar e gerenciar a navegação de URI, a fim de levar o usuário para uma página de produtos em /products quando o botão é selecionado:

@inject NavigationManager Navigation

<button @onclick="NavigateToProductList">
    Products
</button>

@code {
    private void NavigateToProductList()
    {
        Navigation.NavigateTo("/products");
    }
}

Outra maneira de resolver um serviço de DI é por meio da injeção via construtor. No exemplo a seguir, o construtor primário (C# 12 ou posterior) recebe parâmetros dos tipos AppDbContext e ILogger<OrderProcessor> e os resolve em tempo de execução nas variáveis context e logger (as instâncias das abstrações de banco de dados e de registro em log). A instância do contexto do banco de dados é usada para processar todos os pedidos em que o campo IsProcessed está false no banco de dados, e cada pedido processado é registrado como informação com seu ID de pedido (OrderId), usando a instância do logger:

public class OrderProcessor(AppDbContext context, ILogger<OrderProcessor> logger)
{
    public async Task ProcessPendingOrdersAsync()
    {
        var orders = await context.Orders
            .Where(o => !o.IsProcessed)
            .ToListAsync();

        foreach (var order in orders)
        {
            order.IsProcessed = true;
            logger.LogInformation("Processed order ID {OrderId}.", order.Id);
        }

        await context.SaveChangesAsync();
    }
}

Você também pode injetar dependências diretamente nos parâmetros lambda dos pontos de extremidade de Minimal API. No exemplo a seguir, uma lista de itens todo é retornada do /todos ponto de extremidade. Uma instância de logger para ILogger<Program> registra informações, e a instância de banco de dados de AppDbContext é usada para obter do banco de dados a lista de itens de tarefas a ser incluída na resposta:

app.MapGet("/todos", async (AppDbContext context, ILogger<Program> logger) =>
{
    logger.LogInformation("Fetching todos using inline handler injection.");
    var todos = await context.Todos.ToListAsync();

    return Results.Ok(todos);
});

Quando o Host.CreateDefaultBuilder é chamado no arquivo Program, uma nova instância da classe HostBuilder é inicializada automaticamente com serviços fornecidos pelo framework, como serviços de configuração e logging:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Serviços adicionais são adicionados à coleção de serviços do contêiner de DI (IServiceCollection) no método Startup.ConfigureServices (Startup.cs). O exemplo a seguir registra os serviços MVC e Razor Pages:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
    services.AddRazorPages();
}

Normalmente, os serviços são resolvidos da DI usando injeção de construtor. Com a injeção de construtor, uma classe declara um parâmetro de construtor do tipo necessário ou de uma interface. O framework de DI fornece uma instância do serviço em tempo de execução.

Se o contêiner de DI interno não atender às suas necessidades, um contêiner de IoC de terceiros poderá ser usado.

Para obter mais informações, consulte Injeção de dependência no ASP.NET Core e ASP.NET Core Blazor injeção de dependência.

Environments

Os ambientes de execução estão disponíveis em ASP.NET Core, como:

  • Development: quando o aplicativo está em desenvolvimento local.
  • Staging: quando o aplicativo é preparado para implantação.
  • Production: quando o aplicativo ativo está em execução para os usuários.

Especifique o ambiente em que um aplicativo está sendo executado definindo a ASPNETCORE_ENVIRONMENT variável de ambiente no host em que o aplicativo está em execução. ASP.NET Core lê a variável de ambiente na inicialização do aplicativo e armazena o valor para controlar a execução de código em torno do aplicativo.

O código do desenvolvedor pode verificar se há um determinado ambiente. No exemplo de arquivo a seguir Program , o código no bloco de execução só é executado quando o aplicativo não está em execução no Development ambiente:

if (!app.Environment.IsDevelopment())
{
    ...
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (!env.IsDevelopment())
    {
        ...
    }

    ...
}

Para obter mais informações, consulte ambientes de tempo de execução do ASP.NET Core e ambientes do ASP.NET CoreBlazor.

Middleware

O pipeline de tratamento de solicitações é composto como uma série de componentes de middleware. Cada componente executa operações em um HttpContext e invoca o próximo middleware no pipeline ou encerra a solicitação.

Por convenção, os componentes de middleware são adicionados ao pipeline invocando um método de extensão que começa com "Use". No exemplo a seguir, que representa parte de um pipeline de processamento de solicitações, são invocados os middlewares para tratamento de exceções (UseExceptionHandler), protocolo HTTP Strict Transport Security (HSTS) (UseHsts) e redirecionamento de HTTPS (UseHttpsRedirection). Dois dos middlewares só são disparados quando o aplicativo não está em desenvolvimento local no Development ambiente, como quando o aplicativo é preparado para implantação (o Staging ambiente) ou em produção (o Production ambiente):

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

app.UseHttpsRedirection();
if (env.IsDevelopment())
{
    ...
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();

O ASP.NET Core inclui um conjunto avançado de middleware interno. Você também pode criar componentes de middleware personalizados para atender às especificações especiais de processamento de solicitação de um aplicativo. Para obter mais informações, consulte ASP.NET Core middleware.

Host

Na inicialização, um aplicativo ASP.NET Core cria um host. O host encapsula todos os recursos do aplicativo, como:

  • Uma implementação do servidor HTTP
  • Componentes do middleware
  • Logging
  • Serviço de DI (injeção de dependência)
  • Configuration

Há três hosts diferentes capazes de executar um aplicativo ASP.NET Core:

Os ASP.NET Core WebApplication e WebApplicationBuilder tipos são recomendados e são usados em todos os modelos de projeto ASP.NET Core. WebApplication se comporta de forma semelhante ao Host Genérico do .NET e expõe muitas das mesmas interfaces, mas requer menos retornos de chamada para configurar. O ASP.NET Core WebHost só está disponível para compatibilidade com versões anteriores.

O exemplo a seguir cria uma instância de um WebApplication e o atribui a uma variável chamada app:

var builder = WebApplication.CreateBuilder(args);

...

var app = builder.Build();

O WebApplicationBuilder.Build método configura um host com um conjunto de opções padrão, como:

  • Usando Kestrel como servidor Web e habilitando a integração do IIS.
  • Carregando configuração de arquivos de configuração do aplicativo (por exemplo, appsettings.json), variáveis de ambiente, argumentos da linha de comando e outras fontes de configuração.
  • Configurando o log e direcionando a saída de logs para o console e os provedores de log de depuração.

Existem dois hosts:

O Host Genérico do .NET é recomendado. O ASP.NET Core Web Host só está disponível para compatibilidade com versões anteriores.

Os métodos CreateDefaultBuilder e ConfigureWebHostDefaults no exemplo a seguir configuram um host com um conjunto de opções padrão, como:

  • Usando Kestrel como servidor Web e habilitando a integração do IIS.
  • Carregando configuração de arquivos de configuração do aplicativo (por exemplo, appsettings.json), variáveis de ambiente, argumentos da linha de comando e outras fontes de configuração.
  • Configurando o log e direcionando a saída de logs para o console e os provedores de log de depuração.
public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

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

Cenários que não são da Web

O Host Genérico permite que outros tipos de aplicativos usem extensões transversais de framework, como log, injeção de dependência (DI), configuração e gerenciamento do ciclo de vida do aplicativo. Para obter mais informações, consulte Host Genérico do .NET no ASP.NET Core e Tarefas em segundo plano com serviços hospedados no ASP.NET Core.

Servers

Um aplicativo ASP.NET Core usa uma implementação do servidor HTTP para ouvir solicitações HTTP. O servidor descobre solicitações ao aplicativo como um conjunto de recursos de solicitação compostos em um HttpContext.

Para obter mais informações, consulte Implementações do servidor Web no ASP.NET Core.

Windows

O ASP.NET Core vem com as seguintes implementações de servidor:

  • O Kestrel é um servidor Web multiplataforma. Kestrel geralmente é executado em uma configuração de proxy reverso usando o IIS. No ASP.NET Core 2.0 ou posterior, o Kestrel também pode ser executado como um servidor de borda voltado para o público exposto diretamente à Internet.
  • O Servidor HTTP de IIS é um servidor do Windows que usa o IIS. Com esse servidor, o aplicativo ASP.NET Core e o IIS são executados no mesmo processo.
  • HTTP.sys é um servidor para Windows que não é usado com o IIS.

macOS e Linux

O ASP.NET Core fornece a implementação de servidor multiplataforma do Kestrel. No ASP.NET Core 2.0 ou posterior, o Kestrel também pode ser executado como um servidor de borda voltado para o público exposto diretamente à Internet. Kestrel geralmente é executado em uma configuração de proxy reverso com Nginx ou Apache.

Configuration

ASP.NET Core fornece uma estrutura de configuração que obtém configurações como pares nome-valor de um conjunto ordenado de provedores de configuração. Provedores de configuração internos estão disponíveis para uma variedade de fontes, como arquivos JSON (.json), arquivos XML (.xml), variáveis de ambiente e argumentos de linha de comando. Você pode criar provedores de configuração personalizados para dar suporte a outras fontes.

Por padrão, ASP.NET Core aplicativos são configurados para ler a partir de arquivos de configurações de aplicativo (por exemplo, appsettings.json), variáveis de ambiente e a linha de comando.

Quando a configuração do aplicativo é carregada, os valores das variáveis de ambiente substituem valores dos arquivos de configurações do aplicativo. A API opções está disponível para ler valores de configuração relacionados.

Para gerenciar dados de configuração confidenciais, como senhas no ambiente, o Development .NET fornece o Gerenciador de Segredos. Para segredos de produção, recomendamos usar Azure Key Vault.

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

Logging

O ASP.NET Core oferece suporte a uma API de registro que funciona com uma variedade de provedores de log:

  • Console
  • Debug
  • Rastreamento de Eventos no Windows
  • Log de eventos do Windows
  • TraceSource
  • Serviço de Aplicativo do Azure
  • Application Insights do Azure
  • Provedores de terceiros

Para criar logs, resolva um serviço ILogger<TCategoryName> da injeção de dependência (DI) e chame métodos de logging, como LogInformation. Um objeto logger e um provedor de console para o objeto logger são armazenados automaticamente no contêiner de DI quando o método WebApplication.CreateBuilder é chamado.

O exemplo a seguir mostra como obter uma instância de logging do DI e usá-la em um componente Weather (Weather.razor) de um aplicativo Blazor que exibe dados meteorológicos:

@inject ILogger<Weather> Logger

...

@code {
    protected override async Task OnInitializedAsync()
    {
        Logger.LogInformation("OnInitializedAsync method called!");

        ...
    }
}

Para obter mais informações, incluindo diretrizes de roteamento para aplicativos Pages e MVC Razor, consulte Registro em log no .NET e no ASP.NET Core e registro em log do ASP.NET Core Blazor.

Routing

O roteamento em ASP.NET Core é um mecanismo que mapeia solicitações de entrada para pontos de extremidade específicos em um aplicativo. Ele permite definir padrões de URL que correspondem a componentes diferentes, como componentes Razor, páginas Razor, ações do controlador MVC ou middleware.

O método UseRouting adiciona middleware de roteamento ao pipeline de solicitação. Esse middleware processa as informações de roteamento e determina o ponto de extremidade apropriado para cada solicitação. Em aplicativos que usam o Host Mínimo, UseRouting não é explicitamente chamado no código do desenvolvedor, a menos que você queira alterar a ordem de processamento de middleware.

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

Lidar com erros

O ASP.NET Core tem recursos internos para tratamento de erros, como:

  • Uma página de exceção do desenvolvedor
  • Páginas de erro personalizadas
  • Páginas de código de status estático
  • Tratamento de exceção na inicialização

Para obter mais informações, consulte Manipular erros no ASP.NET Core e manipular erros em ASP.NET Core Blazor aplicativos.

Fazer solicitações HTTP

Uma implementação de IHttpClientFactory está disponível para a criação de instâncias do HttpClient. A fábrica:

  • Fornece um local central para nomear e configurar instâncias lógicas de HttpClient. Por exemplo, conte com um cliente padrão para a maioria das solicitações de dados do aplicativo com uma API Web e registre um cliente configurado diferente para acessar GitHub.
  • Dá suporte ao registro e ao encadeamento de vários manipuladores de delegação para criar um pipeline do middleware de solicitação saída. Esse padrão é semelhante ao pipeline do middleware de entrada no ASP.NET Core. O padrão fornece um mecanismo para gerenciar interesses paralelos em relação às solicitações HTTP, incluindo o armazenamento em cache, o tratamento de erro, a serialização e o registro em log.
  • Integra-se ao Polly, uma biblioteca de terceiros popular para tratamento transitório de falhas.
  • Gerencia o pooling e o tempo de vida das instâncias de HttpClientHandler subjacentes para evitar problemas de DNS comuns que ocorrem no gerenciamento manual de tempos de vida de HttpClient.
  • Adiciona uma experiência de registro em log configurável via ILogger para todas as solicitações enviadas por meio de clientes criados pelo alocador.

Para obter mais informações, consulte solicitações HTTP com IHttpClientFactory – ASP.NET Core e Chamar uma API Web de um aplicativo ASP.NET CoreBlazor.

Raiz de conteúdo

A raiz do conteúdo é o caminho base para:

  • O executável que hospeda o aplicativo (.exe).
  • Conjuntos compilados que compõem o aplicativo (.dll).
  • Arquivos de conteúdo usados pelo aplicativo, como Razor arquivos (.cshtml, .razor), arquivos de configuração (.json, .xml) e arquivos de dados (.db).
  • A raiz web, que normalmente é a pasta wwwroot.

Durante o desenvolvimento, a raiz do conteúdo é padrão para o diretório raiz do projeto. Esse diretório também é o caminho base para os arquivos de conteúdo do aplicativo e a raiz da Web. Especifique uma raiz de conteúdo diferente definindo seu caminho ao compilar o host.

Para obter mais informações, consulte .NET Host Genérico no ASP.NET Core e servir arquivos estáticos em aplicativos ASP.NET Core.

Raiz da Web

A raiz da Web é o caminho base para arquivos de recursos estáticos e públicos, como folhas de estilos, arquivos JavaScript e imagens.

Por padrão, os arquivos estáticos são atendidos apenas do diretório raiz da Web e de seus subdiretórios. O caminho raiz da Web padrão é {CONTENT ROOT}/wwwroot, onde o marcador de posição {CONTENT ROOT} é a raiz do conteúdo. Especifique uma raiz da Web diferente definindo seu caminho ao criar o host. Você também pode impedir a publicação de arquivos em wwwroot com o item de projeto <Content> no arquivo de projeto do aplicativo.

Nos arquivos Razor.cshtml, ~/ aponta para a raiz da Web. Um caminho que começa com ~/ é conhecido como um caminho virtual.

Para obter mais informações, consulte .NET Host Genérico no ASP.NET Core e servir arquivos estáticos em aplicativos ASP.NET Core.

Como baixar uma amostra

Muitos dos artigos e tutoriais incluem links para exemplos de código.

  1. Baixe o arquivo zip do repositório ASP.NET.
  2. Descompacte o arquivo AspNetCore.Docs-main.zip.
  3. Para acessar o aplicativo de exemplo de um artigo no repositório descompactado, use o URL no link de exemplo do artigo para ajudá-lo a navegar até a pasta do exemplo. Normalmente, o link de exemplo de um artigo aparece na parte superior do artigo com o texto do link Exibir ou baixar o código de exemplo.

Para obter um único aplicativo de exemplo e apenas seu último commit, use git sparse-checkout.

No exemplo a seguir para o Blazor repositório GitHub de exemplos, o comando git sparse-checkout set especifica o caminho para a pasta do exemplo:

  • Substitua o espaço reservado {VERSION FOLDER} pela pasta da versão.
  • Substitua o marcador {SAMPLE FOLDER} pela pasta de exemplo.

Em um shell de comando, navegue até a pasta em que você deseja clonar o exemplo. Execute os seguintes comandos no shell de comando, passando o caminho da pasta version/sample para o comando git sparse-checkout set:

git clone --depth 1 --filter=blob:none https://github.com/dotnet/blazor-samples.git --sparse
cd blazor-samples
git sparse-checkout init --cone
git sparse-checkout set {VERSION FOLDER}/{SAMPLE FOLDER}

O exemplo a seguir do PowerShell obtém a amostra 10.0 Blazor Web App e a coloca na pasta Documentos do usuário usando o caminho do ~/documents PowerShell para o comando de alterar diretório (cd):

cd "~/documents"
git clone --depth 1 --filter=blob:none https://github.com/dotnet/blazor-samples.git --sparse
cd blazor-samples
git sparse-checkout init --cone
git sparse-checkout set 10.0/BlazorSample_BlazorWebApp

Diretivas do pré-processador no código de exemplo

Para demonstrar vários cenários, os aplicativos de exemplo usam as diretivas de pré-processador #define e #if-#else/#elif-#endif para compilar e executar diferentes seções de código de exemplo de forma seletiva. Para esses exemplos que usam essa abordagem, defina a diretiva #define na parte superior dos arquivos em C# para definir o símbolo associado ao cenário que deseja executar. Alguns exemplos podem exigir que você defina o símbolo na parte superior de vários arquivos para executar um cenário.

Por exemplo, a seguinte lista de símbolo #define indica que quatro cenários estão disponíveis (um cenário por símbolo). A configuração da amostra atual executa o cenário TemplateCode:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Para alterar a amostra que executará o cenário ExpandDefault, defina o símbolo ExpandDefault e deixe os símbolos restantes comentados de fora:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Para obter mais informações sobre como usar diretivas de pré-processador C# para compilar seletivamente as seções de código, consulte #define (Referência C#) e #if (Referência C#) .

Regiões no código de exemplo

Alguns aplicativos de exemplo contêm seções de código cercadas por diretivas #region e #endregion C#. O sistema de compilação de documentação injeta essas regiões nos tópicos da documentação renderizada.

Os nomes de região geralmente contêm a palavra "snippet". O exemplo a seguir mostra uma região chamada snippet_WebHostDefaults:

#region snippet_WebHostDefaults
Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });
#endregion

O snippet de código C# anterior é referenciado no arquivo markdown do tópico com a seguinte linha:

[!code-csharp[](sample/SampleApp/Program.cs?name=snippet_WebHostDefaults)]

Você pode ignorar ou remover com segurança as diretivas #region e #endregion que cercam o código. Não altere o código dentro dessas diretivas se você planeja executar os cenários de exemplo descritos no tópico.

Para obter mais informações, consulte Contribua para a documentação do ASP.NET: trechos de código.

Modelo de Objeto do Documento (DOM)

As referências ao Modelo de Objeto do Documento ao longo deste conjunto de documentação usam o DOM de abreviação.

Para obter mais informações, consulte Introdução ao DOM (documentação do MDN) e à especificação do modelo de objeto de documento de nível 1 (W3C).

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 bugs 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 da unidade de produto possam baixar e executar. Coloque um link cruzado no comentário de abertura do problema.

Em caso de possível problema em um artigo, abra uma issue 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.

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.

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 obter mais informações, consulte Visual Studio Feedback.

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.