ASP.NET Visão geral dos fundamentos principais

Note

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

Warning

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e .NET Core. Para a versão atual, consulte a versão .NET 10 deste artigo.

Este artigo apresenta uma visão geral dos fundamentos para construir aplicações ASP.NET Core, incluindo injeção de dependências (DI), configuração e middleware.

Para obter Blazor orientações sobre fundamentos, que adicionam ou substituem as orientações deste artigo, consulte ASP.NET Core Blazor fundamentals.

O `Program` ficheiro

As aplicações ASP.NET Core criadas a partir dos modelos de projeto do framework contêm código de arranque no Program ficheiro (Program.cs). O arquivo Program é onde:

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

O seguinte código de arranque de aplicações suporta dois tipos de aplicações:

// 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 Program ficheiro, as aplicações ASP.NET Core podem suportar Razor Pages, MVC e API web com controladores.

O seguinte código de arranque de aplicações suporta dois tipos de aplicações:

// 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 Program ficheiro, as aplicações ASP.NET Core podem suportar Razor Pages, MVC e API web com controladores.

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

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

// 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 `Startup` classe

A Startup classe (Startup.cs) é onde:

Os serviços exigidos pela aplicação são configurados no ConfigureServices método.
A cadeia de processamento de pedidos da aplicação é definida no método Configure como uma série de componentes de middleware.

O seguinte código de inicialização do aplicativo suporta:

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 mais informações, consulte Arranque de aplicações no ASP.NET Core e início do ASP.NET CoreBlazor.

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

O ASP.NET Core apresenta injeção de dependências (DI) incorporada que disponibiliza serviços configurados em toda a aplicação para Inversão de Controlo (IoC).

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

var builder = WebApplication.CreateBuilder(args);

Serviços adicionais são adicionados ao contentor DI com WebApplicationBuilder.Services. O exemplo seguinte regista serviços Blazor:

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

builder.Services.AddServerSideBlazor();

A estrutura DI fornece instâncias dos serviços solicitados em tempo de execução. Em aplicações Blazor, os serviços são frequentemente resolvidos através da DI em tempo de execução, utilizando a diretiva @inject num ficheiro de componente Razor (.razor). No exemplo seguinte, o componente utiliza a NavigationManager abstração para obter uma instância do gestor de navegação, que é usado para consultar e gerir a navegação por URI, para guiar o utilizador até uma página de produtos quando /products o botão é selecionado:

@inject NavigationManager Navigation

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

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

Outra forma de resolver um serviço a partir de DI é usando injeção de construtores. No exemplo seguinte, o construtor primário (C# 12 ou posterior) pega nos parâmetros dos tipos AppDbContext e ILogger<OrderProcessor> resolve-os em tempo de execução nas context variáveis e logger (as instâncias das abstrações da base de dados e do registo). A instância de contexto da base de dados é usada para processar todas as ordens onde o IsProcessed campo está false na base de dados, e cada ordem processada é registada como informação com o seu ID de ordem (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();
    }
}

Também pode injetar dependências diretamente nos parâmetros lambda dos endpoints da API Minimal . No exemplo seguinte, é devolvida uma lista de tarefas pendentes a partir do endpoint /todos. Uma instância de registador para ILogger<Program> regista informações, e a instância da base de dados para AppDbContext é utilizada para obter da base de dados a lista de itens por fazer a incluir 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 Program ficheiro, uma nova instância da HostBuilder classe é automaticamente inicializada com serviços fornecidos pelo framework, como serviços de configuração e registo:

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 contentor DI (IServiceCollection) no Startup.ConfigureServices método (Startup.cs). O exemplo seguinte regista os serviços MVC e Razor Pages:

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

Os serviços geralmente são resolvidos do 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 uma interface. O framework DI fornece uma instância do serviço em tempo de execução.

Se o contentor DI incorporado não responder às suas necessidades, pode ser usado um contentor IoC de terceiros.

Para mais informações, consulte Injeção de dependências em ASP.NET Core e injeção de dependências ASP.NET CoreBlazor.

Environments

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

Development: Quando a aplicação está em desenvolvimento local.
Staging: Quando a aplicação está preparada para implementação.
Production: Quando a aplicação ao vivo está a correr para os utilizadores.

Especifique o ambiente em que a aplicação está a correr, definindo a ASPNETCORE_ENVIRONMENT variável ambiente no host onde a aplicação está a correr. O ASP.NET Core lê a variável de ambiente no arranque da aplicação e armazena o valor para controlar a execução do código à volta da aplicação.

O código do programador pode verificar um determinado ambiente. No exemplo seguinte Program do ficheiro, o código no bloco de execução só é executado quando a aplicação não está a correr no Development ambiente:

if (!app.Environment.IsDevelopment())
{
    ...
}

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

    ...
}

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

Middleware

O pipeline de tratamento de solicitações é composto por 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 do middleware são adicionados ao pipeline invocando um método de extensão que começa com "Use." No exemplo seguinte, representando parte de um pipeline de processamento de pedidos, são chamados middleware para o tratamento de exceções (UseExceptionHandler), protocolo HTTP Strict Transport Security (HSTS ) (UseHsts), e redirecionamento HTTPS (UseHttpsRedirection). Dois dos middlewares só são ativados quando a aplicação não está em desenvolvimento local no Development ambiente, como quando a aplicação está preparada para implementaçã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();

ASP.NET Core inclui um rico conjunto de middleware integrado. Também pode criar componentes middleware personalizados para cumprir as especificações especiais de processamento de pedidos de uma aplicação. Para mais informações, consulte middleware ASP.NET Core.

Host

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

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

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

ASP.NET Core WebApplication (também conhecido como Host Mínimo)
Host Genérico .NET
ASP.NET Core WebHost

Os tipos WebApplication e WebApplicationBuilder do ASP.NET Core são recomendados e são utilizados em todos os modelos de projetos do 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 está disponível apenas para compatibilidade retroativa.

O exemplo a seguir instancia um WebApplication e o atribui a uma variável chamada app:

var builder = WebApplication.CreateBuilder(args);

...

var app = builder.Build();

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

Usando Kestrel como servidor web e permitindo a integração com IIS.
Carregamento de configuração a partir de ficheiros de definições da aplicação (por exemplo, appsettings.json), variáveis de ambiente, argumentos de linha de comandos e outras fontes de configuração.
Configurar o registo e direcionar a saída do registo para a consola e para os fornecedores de registo de depuração.

Existem dois apresentadores:

O Host Genérico .NET é recomendado. O ASP.NET Core Web Host está disponível apenas para compatibilidade retroativa.

Os métodos CreateDefaultBuilder e ConfigureWebHostDefaults no exemplo seguinte configuram um host com um conjunto de opções por defeito, tais como:

Usando Kestrel como servidor web e permitindo a integração com IIS.
Carregamento de configuração a partir de ficheiros de definições da aplicação (por exemplo, appsettings.json), variáveis de ambiente, argumentos de linha de comandos e outras fontes de configuração.
Configurar o registo e direcionar a saída do registo para a consola e para os fornecedores de registo 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:

.NET Host Genérico no ASP.NET Core (Recomendado)
ASP.NET Core Web Host (Para compatibilidade retroativa)

Cenários não Web

O Generic Host permite que outros tipos de aplicações utilizem extensões de framework transversais, como logging, injeção de dependências (DI), configuração e gestão de vida útil da app. Para obter mais informações, consulte .NET Generic Host 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 de servidor HTTP para ouvir solicitações HTTP. O servidor apresenta as solicitações à aplicação como um conjunto de funcionalidades de pedido de integradas num HttpContext.

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

Windows

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

Kestrel é um servidor web multiplataforma. Kestrel geralmente é executado em uma configuração de proxy reverso usando IIS. No ASP.NET Core 2.0 ou posterior, Kestrel pode ser executado como um servidor de borda voltado para o público exposto diretamente à Internet.
IIS HTTP Server é um servidor para 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

ASP.NET Core fornece a Kestrel implementação de servidor multiplataforma. No ASP.NET Core 2.0 ou posterior, Kestrel 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

O ASP.NET Core fornece uma estrutura de configuração que obtém definições como pares nome-valor a partir de um conjunto ordenado de fornecedores de configuração. Estão disponíveis fornecedores de configuração incorporados para uma variedade de fontes, como ficheiros JSON (.json), ficheiros XML (.xml), variáveis de ambiente e argumentos de linha de comandos. Pode criar fornecedores de configuração personalizados para suportar outras fontes.

Por defeito, as aplicações ASP.NET Core estão configuradas para ler a partir de ficheiros de definições de aplicação (por exemplo, appsettings.json), variáveis de ambiente e da linha de comandos.

Quando a configuração da aplicação é carregada, os valores das variáveis de ambiente sobrepõem-se aos valores dos ficheiros de definições da aplicação. A API de Opções está disponível para ler valores de configuração relacionados.

Para gerir dados confidenciais de configuração, como palavras-passe no Development ambiente, o .NET fornece o Gestor de Segredos. Para segredos de produção, recomendamos usar o Azure Key Vault.

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

Configuração no ASP.NET Core
Blazor
Azure Key Vault (documentação ASP.NET Core)

Logging

O ASP.NET Core suporta uma API de registo que funciona com vários fornecedores de registo:

Console
Debug
Rastreamento de eventos no Windows
Registo de Eventos do Windows
TraceSource
Serviço de Aplicações do Azure
Aplicação Azure Insights
Fornecedores terceiros

Para criar registos, obtenha um serviço ILogger<TCategoryName> através da injeção de dependências (DI) e chame métodos de registo, como LogInformation. Um objeto de registo e um fornecedor da consola para o objeto de registo são armazenados automaticamente no contentor DI quando o método WebApplication.CreateBuilder é chamado.

O exemplo seguinte mostra como obter uma instância de registo a partir do DI e usá-la num Weather componente (Weather.razor) de uma Blazor aplicação que reporta dados meteorológicos:

@inject ILogger<Weather> Logger

...

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

        ...
    }
}

Para mais informações, incluindo orientações de roteamento para Razor aplicações Pages e MVC, consulte Logging in .NET e ASP.NET Core e logging ASP.NET CoreBlazor.

Routing

O routing no ASP.NET Core é um mecanismo que mapeia pedidos recebidos para endpoints específicos numa aplicação. Ele permite definir padrões de URL que correspondem a diferentes componentes, 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 aplicações que usam o Host Mínimo, UseRouting não é explicitamente chamado no código do programador, a menos que queiras alterar a ordem de processamento do middleware.

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

Lidar com erros

ASP.NET Core tem recursos integrados para lidar com erros, como:

Uma página de exceção do desenvolvedor
Páginas de erro personalizadas
Páginas de código de status estático
Manejo de exceções durante a inicialização

Para mais informações, consulte Lidar com erros no ASP.NET Core e Lidar com erros nas aplicações ASP.NET CoreBlazor.

Fazer solicitações HTTP

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

Fornece um ponto central para nomear e configurar instâncias lógicas de HttpClient. Por exemplo, confiar num cliente predefinido para a maioria dos pedidos de dados da aplicação com uma API web e registar um cliente configurado diferente para aceder ao GitHub.
Suporta o registo e encadeamento de múltiplos manipuladores delegados para criar um pipeline de middleware de pedidos de saída. Esse padrão é semelhante ao pipeline de middleware de entrada do ASP.NET Core. O padrão fornece um mecanismo para gerenciar preocupações transversais para solicitações HTTP, incluindo cache, tratamento de erros, serialização e registro.
Integra-se com o Polly, uma biblioteca de terceiros popular para tratamento de falhas transitórias.
Gere o pool e o tempo de vida das instâncias de HttpClientHandler subjacentes para evitar problemas comuns de DNS que ocorrem ao gerenciar manualmente os tempos de vida de HttpClient.
Adiciona uma experiência de registro configurável via ILogger para todas as solicitações enviadas através de clientes criados pela fábrica.

Para mais informações, consulte pedidos HTTP com IHttpClientFactory - ASP.NET Core e Chamar uma API web a partir de uma aplicação ASP.NET CoreBlazor.

Raiz do conteúdo

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

O executável que hospeda a aplicação (.exe).
Conjuntos compilados que compõem a aplicação (.dll).
ficheiros de conteúdo utilizados pela aplicação, como Razor ficheiros (.cshtml, .razor), ficheiros de configuração (.json, .xml) e ficheiros de dados (.db).
A raiz da Web, que normalmente é a pasta wwwroot.

Durante o desenvolvimento, a raiz de conteúdo é, por padrão, 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 o seu caminho ao construir o host.

Para mais informações, consulte .NET Generic Host no ASP.NET Core e Disponibilizar ficheiros estáticos em aplicações ASP.NET Core.

Diretório raiz da Web

A raiz web é o caminho base para ficheiros de recursos públicos e estáticos, como folhas de estilo, ficheiros JavaScript e imagens.

Por defeito, os ficheiros estáticos são servidos apenas a partir do diretório raiz da web e dos seus subdiretórios. O caminho da raiz da Web assume por defeito o caminho {CONTENT ROOT}/wwwroot, onde o marcador {CONTENT ROOT} representa a raiz do conteúdo. Especifique uma raiz web diferente ao definir o seu caminho ao construir o host . Também podes impedir a publicação de ficheiros em wwwroot com o elemento de projeto <Content> project item no ficheiro de projeto da aplicação.

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

Para mais informações, consulte Host Genérico .NET no ASP.NET Core e Disponibilizar ficheiros estáticos em aplicações ASP.NET Core.

Como fazer o download de um exemplo

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

Baixe o arquivo zip do repositório ASP.NET.
Descompacte o arquivo AspNetCore.Docs-main.zip.
Para acessar o aplicativo de exemplo de um artigo no repositório descompactado, use a 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 código de exemplo.

Para obter uma única aplicação de exemplo e apenas o seu último commit, utilize git sparse-checkout.

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

Substitui o {VERSION FOLDER} marcador de lugar pela pasta de versões.
Substitui o {SAMPLE FOLDER} marcador de lugar pela pasta de exemplos.

Num shell de comandos, navegue até à pasta onde gostaria de clonar a amostra. Execute os seguintes comandos na linha de comandos, passando o caminho da pasta version/sample ao 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 seguinte do PowerShell obtém o exemplo 10.0 Blazor Web App e coloca-o na pasta de documentos do utilizador usando o caminho do ~/documents PowerShell para o comando de alteração de 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 de pré-processador no código de exemplo

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

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

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Para alterar o exemplo para executar o cenário de ExpandDefault, defina o símbolo ExpandDefault e deixe os símbolos restantes comentados:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Para obter mais informações sobre como usar diretivas de pré-processador C# para compilar seletivamente 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 #region e #endregion diretivas C#. O sistema de compilação de documentação injeta essas regiões nos tópicos de documentação renderizados.

Os nomes das regiões geralmente contêm a palavra "trecho". O exemplo a seguir mostra uma região chamada snippet_WebHostDefaults:

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

O trecho de código C# anterior é referenciado no arquivo de marcação do tópico com a seguinte linha:

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

Você pode com segurança ignorar ou remover 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 Contribuir para a documentação do ASP.NET: trechos de código.

Modelo de objeto de documento (DOM)

As referências ao Modelo de Objetos do Documento ao longo deste conjunto de documentação utilizam a abreviatura DOM.

Para mais informações, consulte Introdução ao DOM (documentação MDN) e Especificação do Modelo de Objetos de Documento de Nível 1 (W3C).

Múltiplos de bytes

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

Nome (abreviatura)	Dimensão	Example
Kilobyte (KB)	1.024 bytes	1 KB = 1.024 bytes
Megabyte (MB)	1.024² bytes	1 MB = 1.048.576 bytes
Gigabyte (GB)	1.024³ bytes	1 GB = 1.073.741.824 bytes

Solicitações 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:

Para um eventual bug no framework ou feedback do produto, abra uma questão para a unidade de produto ASP.NET Core em dotnet/aspnetcore issues. Os relatórios de bugs normalmente 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 em GitHub para os engenheiros da unidade de produto descarregarem e executarem. Interligue o projeto ao comentário de abertura do tópico.

Para um potencial problema com um artigo, abra uma questão de documentação. Para abrir uma questão de documentação, use o link Abrir uma questão de documentação no final 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.

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

Para problemas ou comentários sobre o Visual Studio, use os gestos Relatar um problema ou Sugerir um recurso de dentro do Visual Studio, que abrem problemas internos para o Visual Studio. Para 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 produtosmicrosoft/vscode, abra um problema no repositório GitHub.

Recursos adicionais

Comentários

Esta página foi útil?

Last updated on 2026-09-05

ASP.NET Visão geral dos fundamentos principais

O Program ficheiro

A Startup classe

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

Environments

Middleware

Host

Cenários não Web

Servers

Windows

macOS e Linux

Configuration

Logging

Routing

Lidar com erros

Fazer solicitações HTTP

Raiz do conteúdo

Diretório raiz da Web

Como fazer o download de um exemplo

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

Regiões no código de exemplo

Modelo de objeto de documento (DOM)

Múltiplos de bytes

Solicitações de suporte

Recursos adicionais

Comentários

Recursos adicionais

O `Program` ficheiro

A `Startup` classe