Conceitos básicos do ASP.NET CoreASP.NET Core fundamentals

Este artigo é uma visão geral dos principais tópicos para entender como desenvolver aplicativos ASP.NET Core.This article is an overview of key topics for understanding how to develop ASP.NET Core apps.

A classe StartupThe Startup class

A classe Startup é o local em que:The Startup class is where:

  • Quaisquer serviços exigidos pelo aplicativo são configurados.Any services required by the app are configured.

  • O pipeline de tratamento de solicitação é definido.The request handling pipeline is defined.

  • Código para configurar (ou registrar) serviços é adicionado ao método Startup.ConfigureServices.Code to configure (or register) services is added to the Startup.ConfigureServices method. Serviços são componentes usados pelo aplicativo.Services are components that are used by the app. Por exemplo, um objeto de contexto do Entity Framework Core é um serviço.For example, an Entity Framework Core context object is a service.

  • O código para configurar a pipeline de tratamento de solicitação é adicionado ao método Startup.Configure.Code to configure the request handling pipeline is added to the Startup.Configure method. O pipeline é composto como uma série de componentes de middleware.The pipeline is composed as a series of middleware components. Por exemplo, um middleware pode manipular as solicitações para arquivos estáticos ou redirecionar solicitações HTTP para HTTPS.For example, a middleware might handle requests for static files or redirect HTTP requests to HTTPS. Cada middleware executa operações assíncronas em um HttpContext e invoca o próximo middleware no pipeline ou encerra a solicitação.Each middleware performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

Aqui está um exemplo de classe Startup:Here's a sample Startup class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

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

Para obter mais informações, consulte Inicialização de aplicativo no ASP.NET Core.For more information, see Inicialização de aplicativo no ASP.NET Core.

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

O ASP.NET Core tem uma estrutura de DI (injeção de dependência) interna que torna serviços configurados disponíveis para classes do aplicativo.ASP.NET Core has a built-in dependency injection (DI) framework that makes configured services available to an app's classes. Uma maneira de obter uma instância de um serviço em uma classe criar um construtor com um parâmetro do tipo necessário.One way to get an instance of a service in a class is to create a constructor with a parameter of the required type. O parâmetro pode ser o tipo de serviço ou uma interface.The parameter can be the service type or an interface. O sistema de DI fornece o serviço em tempo de execução.The DI system provides the service at runtime.

Aqui está uma classe que usa DI para obter um objeto de contexto do Entity Framework Core.Here's a class that uses DI to get an Entity Framework Core context object. A linha realçada é um exemplo de injeção de construtor:The highlighted line is an example of constructor injection:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }
    // ...
    public async Task OnGetAsync()
    {
        var movies = from m in _context.Movies
                        select m;
        Movies = await movies.ToListAsync();
    }
}

Embora a DI seja interna, ela foi projetada para permitir que você conecte um contêiner de IoC (inversão de controle) de terceiros, se preferir.While DI is built in, it's designed to let you plug in a third-party Inversion of Control (IoC) container if you prefer.

Para obter mais informações, consulte Injeção de dependência no ASP.NET Core.For more information, see Injeção de dependência no ASP.NET Core.

MiddlewareMiddleware

O pipeline de tratamento de solicitação é composto como uma série de componentes de middleware.The request handling pipeline is composed as a series of middleware components. Cada componente executa operações assíncronas em um HttpContext e então invoca o próximo middleware no pipeline ou encerra a solicitação.Each component performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

Por convenção, um componente de middleware é adicionado ao pipeline invocando seu método de extensão Use... no método Startup.Configure.By convention, a middleware component is added to the pipeline by invoking its Use... extension method in the Startup.Configure method. Por exemplo, para habilitar o processamento de arquivos estáticos, chame UseStaticFiles.For example, to enable rendering of static files, call UseStaticFiles.

O código realçado no exemplo a seguir configura o pipeline de tratamento de solicitação:The highlighted code in the following example configures the request handling pipeline:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

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

O ASP.NET Core inclui um conjunto de middleware interno, e você pode escrever um middleware personalizado.ASP.NET Core includes a rich set of built-in middleware, and you can write custom middleware.

Para obter mais informações, consulte Middleware do ASP.NET Core.For more information, see Middleware do ASP.NET Core.

O hostThe host

Um aplicativo ASP.NET Core cria um host na inicialização.An ASP.NET Core app builds a host on startup. O host é um objeto que encapsula todos os recursos do aplicativo, como:The host is an object that encapsulates all of the app's resources, such as:

  • Uma implementação do servidor HTTPAn HTTP server implementation
  • Componentes de middlewareMiddleware components
  • Registrando em logLogging
  • DIDI
  • ConfiguraçãoConfiguration

O principal motivo para incluir todos os recursos interdependentes do aplicativo em um objeto é o gerenciamento de tempo de vida: controle sobre a inicialização do aplicativo e desligamento normal.The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

O código para criar um host está em Program.Main e segue o padrão de construtor.The code to create a host is in Program.Main and follows the builder pattern. Métodos são chamados para configurar cada recurso que faz parte do host.Methods are called to configure each resource that is part of the host. Um método construtor é chamado para reunir tudo e instanciar o objeto de host.A builder method is called to pull it all together and instantiate the host object.

No ASP.NET Core 3.0 ou posterior, o Host Genérico (classe Host) ou o Host da Web (classe WebHost) podem ser usados em um aplicativo Web.In ASP.NET Core 3.0 or later, Generic Host (Host class) or Web Host (WebHost class) can be used in a web app. O Host Genérico é o recomendado, e o Host da Web está disponível para compatibilidade com versões anteriores.Generic Host is recommended, and Web Host is available for backwards compatibility.

A estrutura fornece os métodos CreateDefaultBuilder e ConfigureWebHostDefaults para configurar um host com opções comumente usadas, como as seguintes:The framework provides the CreateDefaultBuilder and ConfigureWebHostDefaults methods to set up a host with commonly used options, such as the following:

  • Uso do Kestrel como o servidor Web e habilitação da integração do IIS.Use Kestrel as the web server and enable IIS integration.
  • Configuração de carregamento de appsettings.json, appsettings.{EnvironmentName}.json, de variáveis de ambiente, de argumentos de linha de comando e outras fontes de configuração.Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • Envio da saída de log para os provedores de console e de depuração.Send logging output to the console and debug providers.

Aqui está um exemplo de código que cria um host.Here's sample code that builds a host. Os métodos que configuram o host com as opções mais usadas são realçados:The methods that set up the host with commonly used options are highlighted:

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 Host Genérico .NET e Host da Web do ASP.NET Core.For more information, see Host Genérico .NET and Host da Web do ASP.NET Core.

O ASP.NET Core 2.x usa o Host da Web (classe WebHost) para aplicativos Web.ASP.NET Core 2.x uses Web Host (WebHost class) for web apps. A estrutura fornece CreateDefaultBuilder para configurar um host com opções comumente usadas, como as seguintes:The framework provides CreateDefaultBuilder to set up a host with commonly used options, such as the following:

  • Uso do Kestrel como o servidor Web e habilitação da integração do IIS.Use Kestrel as the web server and enable IIS integration.
  • Configuração de carregamento de appsettings.json, appsettings.{EnvironmentName}.json, de variáveis de ambiente, de argumentos de linha de comando e outras fontes de configuração.Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • Envio da saída de log para os provedores de console e de depuração.Send logging output to the console and debug providers.

Aqui está um exemplo de código que cria um host:Here's sample code that builds a host:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Para obter mais informações, consulte Host da Web do ASP.NET Core.For more information, see Host da Web do ASP.NET Core.

Cenários avançados de hostAdvanced host scenarios

O Host Genérico está disponível para uso por qualquer aplicativo .NET Core, não apenas para aplicativos ASP.NET Core.Generic Host is available for any .NET Core app to use—not just ASP.NET Core apps. O Host Genérico (classe Host) permite que outros tipos de aplicativo usem extensões de estruturas abrangentes como registro em log, DI, configuração e gerenciamento de tempo de vida de aplicativo.Generic Host (Host class) allows other types of apps to use cross-cutting framework extensions, such as logging, DI, configuration, and app lifetime management. Para obter mais informações, consulte Host Genérico .NET.For more information, see Host Genérico .NET.

O Host da Web foi desenvolvido para incluir uma implementação de servidor HTTP, que não é exigida para outros tipos de aplicativo .NET.Web Host is designed to include an HTTP server implementation, which isn't required for other kinds of .NET apps. A partir do ASP.NET Core 2.1, o Host Genérico (classe Host) está disponível para uso por qualquer aplicativo .NET Core — não apenas para aplicativos ASP.NET Core.Starting in ASP.NET Core 2.1, the Generic Host (Host class) is available for any .NET Core app to use—not just ASP.NET Core apps. O Host Genérico permite que outros tipos de aplicativo usem extensões de estruturas abrangentes como registro em log, DI, configuração e gerenciamento de tempo de vida de aplicativo.Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, DI, configuration, and app lifetime management. Para obter mais informações, consulte Host Genérico .NET.For more information, see Host Genérico .NET.

Você também pode usar o host para executar tarefas em segundo plano.You can also use the host to run background tasks. Para obter mais informações, consulte Tarefas em segundo plano com serviços hospedados no ASP.NET Core.For more information, see Tarefas em segundo plano com serviços hospedados no ASP.NET Core.

ServidoresServers

Um aplicativo ASP.NET Core usa uma implementação do servidor HTTP para ouvir solicitações HTTP.An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. O servidor descobre solicitações ao aplicativo como um conjunto de recursos de solicitação compostos em um HttpContext.The server surfaces requests to the app as a set of request features composed into an HttpContext.

O ASP.NET Core vem com as seguintes implementações de servidor:ASP.NET Core provides the following server implementations:

  • Kestrel é um servidor Web multiplataforma.Kestrel is a cross-platform web server. O Kestrel normalmente é executado em uma configuração de proxy reverso que usa o IIS.Kestrel is often run in a reverse proxy configuration using 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.In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • O Servidor HTTP de IIS é um servidor do Windows que usa o IIS.IIS HTTP Server is a server for windows that uses IIS. Com esse servidor, o aplicativo ASP.NET Core e o IIS são executados no mesmo processo.With this server, the ASP.NET Core app and IIS run in the same process.
  • HTTP.sys é um servidor para Windows que não é usado com IIS.HTTP.sys is a server for Windows that isn't used with IIS.

O ASP.NET Core vem com as seguintes implementações de servidor:ASP.NET Core provides the following server implementations:

  • Kestrel é um servidor Web multiplataforma.Kestrel is a cross-platform web server. O Kestrel normalmente é executado em uma configuração de proxy reverso que usa o IIS.Kestrel is often run in a reverse proxy configuration using 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.In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • HTTP.sys é um servidor para Windows que não é usado com IIS.HTTP.sys is a server for Windows that isn't used with IIS.

Para obter mais informações, consulte Implementações de servidor Web em ASP.NET Core.For more information, see Implementações de servidor Web em ASP.NET Core.

ConfiguraçãoConfiguration

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.ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. Há provedores de configuração internos para uma variedade de fontes, como arquivos .json, arquivos .xml, variáveis de ambiente e argumentos de linha de comando.There are built-in configuration providers for a variety of sources, such as .json files, .xml files, environment variables, and command-line arguments. Você também pode escrever seus próprios provedores de configuração personalizados.You can also write custom configuration providers.

Por exemplo, você poderia especificar que a configuração é proveniente de appsettings.json e variáveis de ambiente.For example, you could specify that configuration comes from appsettings.json and environment variables. Então, quando o valor de ConnectionString for solicitado, a estrutura procura primeiro no arquivo appsettings.json.Then when the value of ConnectionString is requested, the framework looks first in the appsettings.json file. Se o valor for encontrado lá, mas também em uma variável de ambiente, o valor da variável de ambiente terá precedência.If the value is found there but also in an environment variable, the value from the environment variable would take precedence.

Para gerenciar dados de configuração confidenciais como senhas, o ASP.NET Core fornece uma ferramenta Secret Manager.For managing confidential configuration data such as passwords, ASP.NET Core provides a Secret Manager tool. Para segredos de produção, recomendamos o Azure Key Vault.For production secrets, we recommend Azure Key Vault.

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

OpçõesOptions

Sempre que possível, o ASP.NET Core segue o padrão de opções para armazenar e recuperar valores de configuração.Where possible, ASP.NET Core follows the options pattern for storing and retrieving configuration values. O padrão de opções usa classes para representar grupos de configurações relacionadas.The options pattern uses classes to represent groups of related settings.

Por exemplo, o código a seguir define as opções de WebSockets:For example, the following code sets WebSockets options:

var options = new WebSocketOptions  
{  
   KeepAliveInterval = TimeSpan.FromSeconds(120),  
   ReceiveBufferSize = 4096
};  
app.UseWebSockets(options);

Para obter mais informações, consulte Padrão de opções no ASP.NET Core.For more information, see Padrão de opções no ASP.NET Core.

AmbientesEnvironments

Ambientes de execução, como Desenvolvimento, Preparo e Produção, são uma noção de primeira classe no ASP.NET Core.Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core. Você pode especificar o ambiente em que um aplicativo está em execução definindo a variável de ambiente ASPNETCORE_ENVIRONMENT.You can specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable. O ASP.NET Core lê a variável de ambiente na inicialização do aplicativo e armazena o valor em uma implementação IHostingEnvironment.ASP.NET Core reads that environment variable at app startup and stores the value in an IHostingEnvironment implementation. O objeto de ambiente está disponível em qualquer lugar no aplicativo por meio de DI.The environment object is available anywhere in the app via DI.

O seguinte código de exemplo da classe Startup configura o aplicativo para fornecer informações de erro detalhadas somente quando ele é executado no desenvolvimento:The following sample code from the Startup class configures the app to provide detailed error information only when it runs in development:

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

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseMvc();
}

Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.For more information, see Usar vários ambientes no ASP.NET Core.

Registrando em logLogging

O ASP.NET Core oferece suporte a uma API de registro em log que funciona com uma variedade de provedores de logs internos e terceirizados.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Provedores disponíveis incluem os seguintes:Available providers include the following:

  • ConsoleConsole
  • DepurarDebug
  • Rastreamento de Eventos no WindowsEvent Tracing on Windows
  • Log de Eventos do WindowsWindows Event Log
  • TraceSourceTraceSource
  • Serviço de Aplicativo do AzureAzure App Service
  • Azure Application InsightsAzure Application Insights

Escreva logs de qualquer lugar no código do aplicativo obtendo um objeto ILogger da DI e chamando os métodos de log.Write logs from anywhere in an app's code by getting an ILogger object from DI and calling log methods.

Aqui está o código de exemplo que usa um objeto ILogger, com injeção de construtor e chamadas de método de registro em log realçadas.Here's sample code that uses an ILogger object, with constructor injection and the logging method calls highlighted.

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

A interface ILogger permite que você passe qualquer número de campos para o provedor de registro em log.The ILogger interface lets you pass any number of fields to the logging provider. Os campos são comumente usados para construir uma cadeia de caracteres de mensagem, mas o provedor também pode enviá-los como campos separados para um armazenamento de dados.The fields are commonly used to construct a message string, but the provider can also send them as separate fields to a data store. Esse recurso torna possível para provedores de log implementar registro em log semântico, também conhecido como registro em log estruturado.This feature makes it possible for logging providers to implement semantic logging, also known as structured logging.

Para obter mais informações, consulte Registro em log no ASP.NET Core.For more information, see Registro em log no ASP.NET Core.

RoteamentoRouting

Um rota é um padrão de URL mapeado para um manipulador.A route is a URL pattern that is mapped to a handler. O manipulador normalmente é um Razor Page, um método de ação em um controlador MVC ou um middleware.The handler is typically a Razor page, an action method in an MVC controller, or a middleware. O roteamento do ASP.NET Core lhe dá controle sobre as URLs usadas pelo seu aplicativo.ASP.NET Core routing gives you control over the URLs used by your app.

Para obter mais informações, consulte Roteamento no ASP.NET Core.For more information, see Roteamento no ASP.NET Core.

Tratamento de errosError handling

O ASP.NET Core tem recursos internos para tratamento de erros, como:ASP.NET Core has built-in features for handling errors, such as:

  • Uma página de exceção do desenvolvedorA developer exception page
  • Páginas de erro personalizadasCustom error pages
  • Páginas de código de status estáticoStatic status code pages
  • Tratamento de exceção na inicializaçãoStartup exception handling

Para obter mais informações, consulte Tratar erros no ASP.NET Core.For more information, see Tratar erros no ASP.NET Core.

Fazer solicitações HTTPMake HTTP requests

Uma implementação de IHttpClientFactory está disponível para a criação de instâncias do HttpClient.An implementation of IHttpClientFactory is available for creating HttpClient instances. O alocador:The factory:

  • Fornece um local central para nomear e configurar instâncias lógicas de HttpClient.Provides a central location for naming and configuring logical HttpClient instances. Por exemplo, um cliente github pode ser registrado e configurado para acessar o GitHub.For example, a github client can be registered and configured to access GitHub. Um cliente padrão pode ser registrado para outras finalidades.A default client can be registered for other purposes.
  • 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.Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. Esse padrão é semelhante ao pipeline do middleware de entrada no ASP.NET Core.This pattern is similar to the inbound middleware pipeline in 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.The pattern provides a mechanism to manage cross-cutting concerns around HTTP requests, including caching, error handling, serialization, and logging.
  • Integra-se com a Polly, uma biblioteca de terceiros popular para tratamento de falhas transitórias.Integrates with Polly, a popular third-party library for transient fault handling.
  • Gerencia o pooling e o tempo de vida das instâncias de HttpClientMessageHandler subjacentes para evitar problemas de DNS comuns que ocorrem no gerenciamento manual de tempos de vida de HttpClient.Manages the pooling and lifetime of underlying HttpClientMessageHandler instances to avoid common DNS problems that occur when manually managing HttpClient lifetimes.
  • 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.Adds a configurable logging experience (via ILogger) for all requests sent through clients created by the factory.

Para obter mais informações, consulte Fazer solicitações HTTP usando IHttpClientFactory no ASP.NET Core.For more information, see Fazer solicitações HTTP usando IHttpClientFactory no ASP.NET Core.

Raiz do conteúdoContent root

A raiz do conteúdo é o caminho base para qualquer conteúdo privado usado pelo aplicativo, como seus arquivos do Razor.The content root is the base path to any private content used by the app, such as its Razor files. Por padrão, a raiz do conteúdo é o caminho base do executável que hospeda o aplicativo.By default, the content root is the base path for the executable hosting the app. Um local alternativo pode ser especificado ao criar o host.An alternative location can be specified when building the host.

Para obter mais informações, veja Raiz de conteúdo.For more information, see Content root.

Para obter mais informações, veja Raiz de conteúdo.For more information, see Content root.

Raiz da WebWeb root

A raiz Web (também conhecida como webroot) é o caminho base para recursos públicos e estáticos como CSS, JavaScript e arquivos de imagem.The web root (also known as webroot) is the base path to public, static resources, such as CSS, JavaScript, and image files. O middleware de arquivos estáticos apenas veiculará arquivos do diretório raiz Web (e seus subdiretórios) por padrão.The static files middleware will only serve files from the web root directory (and sub-directories) by default. O caminho da raiz Web assume como padrão {Content Root}/wwwroot, mas é possível especificar um local diferente ao criar o host.The web root path defaults to {Content Root}/wwwroot, but a different location can be specified when building the host.

Em arquivos (.cshtml) do Razor, o til-barra ~/ aponta para a raiz Web.In Razor (.cshtml) files, the tilde-slash ~/ points to the web root. Caminhos que começam com ~/ são denominados caminhos virtuais.Paths beginning with ~/ are referred to as virtual paths.

Para obter mais informações, consulte Arquivos estáticos no ASP.NET Core.For more information, see Arquivos estáticos no ASP.NET Core.