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

Conheça os conceitos fundamentais para criar aplicativos ASP.NET Core, incluindo DI (injeção de dependência), configuração, middleware e muito mais.

Consulte as diretrizes básicas do Blazor, que adicionam ou se sobrepõem às diretrizes neste nó, em Princípios básicos do ASP.NET Core Blazor.

Module.vb

Aplicativos ASP.NET Core criados com modelos Web contêm o código de inicialização do aplicativo no arquivo Program.cs. O arquivo Program.cs é 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 seguinte código de inicialização do aplicativo dá suporte a:

• Razor Pages
• Controladores MVC com exibições
• API Web com controladores
• APIs Web mínimas

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

O ASP.NET Core inclui injeção de dependência (DI) que disponibiliza os serviços configurados em todo o aplicativo. Os serviços são adicionados ao contêiner de DI com WebApplicationBuilder.Services, builder.Services, no código anterior. Quando a instância de WebApplicationBuilder é criada, muitos serviços fornecidos pela estrutura são adicionados. builder é um WebApplicationBuilder no seguinte código:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

No código realçado anterior, builder tem a configuração, o registro em log e muitos outros serviços adicionados ao contêiner de DI.

O seguinte código adiciona Razor Pages, controladores MVC com exibições e um DbContext personalizado ao contêiner de DI:

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

Normalmente, os serviços são resolvidos da DI usando injeção de construtor. A estrutura de DI fornece uma instância desse serviço em runtime.

O seguinte código usa a injeção de construtor para resolver o contexto do banco de dados e o agente de DI:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

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, um componente de middleware é adicionado ao pipeline invocando um método de extensão Use{Feature}. O middleware adicionado ao aplicativo está realçado no seguinte código:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Para obter mais informações, confira Middleware do 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 do servidor HTTP
• Componentes de middleware
• Registrando em log
• Serviço de DI (injeção de dependência)
• Configuração

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 de .NET combinado com o do ConfigureWebHostDefaults do ASP.NET Core
• ASP.NET Core WebHost

Os tipos WebApplication e WebApplicationBuilder de ASP.NET Core são recomendados e usados em todos os modelos de ASP.NET Core. WebApplication comporta-se 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 WebHost do ASP.NET Core está disponível apenas para compatibilidade com versões anteriores.

O exemplo a seguir instancia um WebApplication:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

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

• Usar o Kestrel como o servidor Web e habilitar a integração do IIS.
• Carregar a configuração de appsettings.json, variáveis de ambiente, argumentos de linha de comando e de outras fontes de configuração.
• Envio da saída de log para os provedores de console e de depuração.

Cenários não Web

O Host Genérico permite que outros tipos de aplicativos usem extensões de estruturas abrangentes como registro em log, DI (Injeção de Dependência), configuração e gerenciamento do tempo de vida dos aplicativos. 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.

Servidores

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.

Windows

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

• O Kestrel é um servidor Web multiplataforma. O Kestrel normalmente é executado em uma configuração de proxy reverso que usa 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 IIS.

macOS

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. O Kestrel normalmente é executado em uma configuração de proxy reverso com Nginx ou Apache.

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. O Kestrel normalmente é executado em uma configuração de proxy reverso com Nginx ou Apache.

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

Configuração

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

Por padrão, aplicativos ASP.NET Core são configurados para leitura de appsettings.json, variáveis de ambiente, linha de comando e muito mais. Quando a configuração do aplicativo é carregada, os valores das variáveis de ambiente substituem valores de appsettings.json.

Para gerenciar dados de configuração confidenciais como senhas, o .NET Core fornece um Gerenciador de Segredos. Para segredos de produção, recomendamos o Azure Key Vault.

Para obter mais informações, consulte Configuração no ASP.NET Core.

Ambientes

Ambientes de execução, como Development, Staging e Production, estão disponíveis no ASP.NET Core. Especifique o ambiente em que um aplicativo está em execução definindo a variável de ambiente ASPNETCORE_ENVIRONMENT. O ASP.NET Core lê a variável de ambiente na inicialização do aplicativo e armazena o valor em uma implementação IWebHostEnvironment. Essa implementação está disponível em qualquer lugar de um aplicativo por meio da DI (injeção de dependência).

O seguinte exemplo configura o manipulador de exceções e o middleware HSTS (Protocolo de Segurança de Transporte Estrito HTTP) quando não é executado no ambiente Development:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Para obter mais informações, confira Usar vários ambientes no ASP.NET Core.

Registrando em log

O ASP.NET Core dá suporte a uma API de registro em log que funciona com uma série de provedores de registro em log internos e de terceiros. Os provedores disponíveis incluem:

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

Para criar logs, resolva um serviço ILogger<TCategoryName> com base na DI (injeção de dependência) e chame métodos de registro em log, como LogInformation. Por exemplo:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Para obter mais informações, confira Log no .NET Core e no ASP.NET Core.

Roteiro

Um rota é um padrão de URL mapeado para um manipulador. O manipulador normalmente é um Razor Page, um método de ação em um controlador MVC ou um middleware. O roteamento do ASP.NET Core lhe dá controle sobre as URLs usadas pelo seu aplicativo.

O seguinte código, gerado pelo modelo de aplicativo Web ASP.NET Core, chama UseRouting:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Saiba mais em Roteamento no ASP.NET Core.

Tratamento de 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, confira Manipular erros no ASP.NET Core.

Fazer solicitações HTTP

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

• Fornece um local central para nomear e configurar instâncias lógicas de HttpClient. Por exemplo, registre e configure um cliente do github para acessar o GitHub. Registre e configure um cliente padrão para outras finalidades.
• 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 com a Polly, uma biblioteca de terceiros popular para tratamento de falhas transitórias.
• 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 saber mais, confira Fazer solicitações HTTP usando IHttpClientFactory no ASP.NET Core.

Raiz do conteúdo

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

• O executável que hospeda o aplicativo (.exe).
• Assemblies compilados que compõem o aplicativo (.dll).
• Arquivos de conteúdo usados pelo aplicativo, como:
  • Arquivos Razor (.cshtml, .razor)
  • Arquivos de configuração (.json, .xml)
  • Arquivos de dados (.db)
• A raiz da Web, 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 criar o host. Para obter mais informações, veja Raiz de conteúdo.

Raiz da Web

A raiz da Web é o caminho base para arquivos de recursos públicos e estáticos, como:

• Folhas de estilos (.css)
• JavaScript (.js)
• Imagens (.png, .jpg)

Por padrão, arquivos estáticos são fornecidos apenas do diretório raiz da Web e seus subdiretórios. O caminho raiz da Web é padrão para {raiz de conteúdo}/wwwroot. Especifique uma raiz da Web diferente definindo seu caminho ao criar o host. Para obter mais informações, confira Diretório base.

Impeça a publicação de arquivos em wwwroot com o Item de projeto de <conteúdo> no arquivo de projeto. O seguinte exemplo impede a publicação de conteúdo em wwwroot/local e seus subdiretórios:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

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

Saiba mais em Arquivos estáticos no ASP.NET Core.

Recursos adicionais

• Código-fonte do WebApplicationBuilder