Compartilhar via


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

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

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:

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:

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.

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.

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

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

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:

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:

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.

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.

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

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

A classe Startup

A classe Startup é o local em que:

  • 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.

Aqui está um exemplo de classe Startup:

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();
        });
    }
}

Saiba mais em Inicialização de aplicativos no ASP.NET Core.

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

O ASP.NET Core inclui uma estrutura de DI (injeção de dependência) interna que disponibiliza os serviços configurados em um aplicativo. Por exemplo, um componente de registro em log é um serviço.

Código para configurar (ou registrar) serviços é adicionado ao método Startup.ConfigureServices. Por exemplo:

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

    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. A estrutura de DI fornece uma instância desse serviço em runtime.

O seguinte exemplo usa injeção de construtor para resolver um RazorPagesMovieContext do DI:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }

    // ...

    public async Task OnGetAsync()
    {
        Movies = await _context.Movies.ToListAsync();
    }
}

Se o contêiner de IoC (Inversão de Controle) interno não atender a todas as necessidades de um aplicativo, 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.

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... no método Startup.Configure. Por exemplo, para habilitar o processamento de arquivos estáticos, chame UseStaticFiles.

O seguinte exemplo configura o pipeline de tratamento de solicitação:

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

    app.UseRouting();

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

O ASP.NET Core inclui um conjunto avançado de middleware interno. Componentes de middleware personalizados também podem ser escritos.

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á dois hosts diferentes:

  • Host Genérico .NET
  • Host da Web do ASP.NET Core

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

O seguinte exemplo cria um Host Genérico do .NET:

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>();
            });
}

Os métodos CreateDefaultBuilder e ConfigureWebHostDefaults configuram 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, appsettings.{Environment}.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.

Para saber mais, confira Host Genérico .NET no ASP.NET Core.

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.

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.

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.

A maneira preferencial de ler os valores de configuração relacionados é usando o padrão de opções. Para obter mais informações, confira Vincular dados de configuração hierárquica usando o padrão de opções.

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, são uma noção de primeira classe 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 aplicativo para fornecer informações de erro detalhadas ao executar no ambiente Development:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

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

    app.UseRouting();

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

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 TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        
        // Item lookup code removed.
        
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
        
        return item;
    }
}

Métodos de registro em log, como LogInformation, são suporte a qualquer número de campos. Esses campos costumam ser usados para construir uma mensagem string, mas alguns provedores de log os enviam para um armazenamento de dados como campos separados. Esse recurso torna possível para provedores de log implementar registro em log semântico, também conhecido como registro em log estruturado.

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.

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>

Em arquivos Razor.cshtml, o til-barra (~/) aponta para a raiz Web. Um caminho que começa com ~/ é conhecido como um caminho virtual.

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