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:

  • Os serviços exigidos pelo aplicativo são configurados.Services required by the app are configured.
  • O pipeline de tratamento de solicitação é definido.The request handling pipeline is defined.

Serviços são componentes usados pelo aplicativo.Services are components that are used by the app. Por exemplo, um componente de registro em log é um serviço.For example, a logging component is a service. 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.

O pipeline de tratamento de solicitações é composto como uma série de componentes de middleware.The request handling 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. 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.

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.

HostHost

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.

Dois hosts estão disponíveis: o Host Genérico e o Host Web.Two hosts are available: the Generic Host and the Web Host. O Host Genérico é o recomendado, e o Host Web está disponível apenas para compatibilidade com versões anteriores.The Generic Host is recommended, and the Web Host is available only for backwards compatibility.

O código para criar um host está em Program.Main:The code to create a host is in Program.Main:

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 as opções usadas com frequência, como as seguintes:The CreateDefaultBuilder and ConfigureWebHostDefaults methods configure 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.

Para obter mais informações, consulte Host Genérico .NET.For more information, see Host Genérico .NET.

Dois hosts estão disponíveis: o Host Web e o Host Genérico.Two hosts are available: the Web Host and the Generic Host. No ASP.NET Core 2.x, o Host Genérico é somente para cenários não Web.In ASP.NET Core 2.x, the Generic Host is only for non-web scenarios.

O código para criar um host está em Program.Main:The code to create a host is in Program.Main:

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

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

O método CreateDefaultBuilder configura um host com as opções usadas com frequência, como as seguintes:The CreateDefaultBuilder method configures 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.

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 não WebNon-web scenarios

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.The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. Para obter mais informações, consulte Host Genérico .NET e Tarefas em segundo plano com serviços hospedados no ASP.NET Core.For more information, see Host Genérico .NET and 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 Como fazer registro em log no .NET Core e no ASP.NET Core.For more information, see Como fazer registro em log no .NET Core e 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:The content root is the base path to the:

  • Executável que hospeda o aplicativo ( . exe).Executable hosting the app (.exe).
  • Assemblies compilados que compõem o aplicativo ( . dll).Compiled assemblies that make up the app (.dll).
  • Arquivos de conteúdo que não são de código usados pelo aplicativo, como:Non-code content files used by the app, such as:
    • Arquivos Razor ( . cshtml, . Razor)Razor files (.cshtml, .razor)
    • Arquivos de configuração ( . JSON, . xml)Configuration files (.json, .xml)
    • Arquivos de dados ( . db)Data files (.db)
  • Raiz da Web, normalmente a pasta wwwroot publicada.Web root, typically the published wwwroot folder.

Durante o desenvolvimento:During development:

  • A raiz do conteúdo assume como padrão o diretório raiz do projeto.The content root defaults to the project's root directory.
  • O diretório raiz do projeto é usado para criar:The project's root directory is used to create the:
    • Caminho para os arquivos de conteúdo sem código do aplicativo no diretório raiz do projeto.Path to the app's non-code content files in the project's root directory.
    • Raiz da Web, normalmente a pasta wwwroot no diretório raiz do projeto.Web root, typically the wwwroot folder in the project's root directory.

Um caminho de raiz de conteúdo alternativo pode ser especificado ao criar o host.An alternative content root path can be specified when building the host. Para obter mais informações, consulte Host Genérico .NET.For more information, see Host Genérico .NET.

Um caminho de raiz de conteúdo alternativo pode ser especificado ao criar o host.An alternative content root path can be specified when building the host. Para obter mais informações, consulte Host da Web do ASP.NET Core.For more information, see Host da Web do ASP.NET Core.

Raiz da WebWeb root

A raiz da Web é o caminho base para arquivos de recurso estáticos, não de código e públicos, como:The web root is the base path to public, non-code, static resource files, such as:

  • Folhas de estilo ( . css)Stylesheets (.css)
  • JavaScript ( . js)JavaScript (.js)
  • Imagens ( . png, . jpg)Images (.png, .jpg)

Os arquivos estáticos são servidos apenas por padrão no diretório raiz da Web (e subdiretórios).Static files are only served by default from the web root directory (and sub-directories).

O caminho raiz da Web tem como padrão {Content root}/wwwroot, mas uma raiz da Web diferente pode ser especificada ao criar o host.The web root path defaults to {content root}/wwwroot, but a different web root can be specified when building the host. Para obter mais informações, consulte Host Genérico .NET.For more information, see Host Genérico .NET.

O caminho raiz da Web tem como padrão {Content root}/wwwroot, mas uma raiz da Web diferente pode ser especificada ao criar o host.The web root path defaults to {content root}/wwwroot, but a different web root can be specified when building the host. Para obter mais informações, confira Diretório base.For more information, see Web root.

Em arquivos Razor ( . cshtml), a barra de til (~/) aponta para a raiz da Web.In Razor (.cshtml) files, the tilde-slash (~/) points to the web root. Um caminho que começa com ~/ é conhecido como um caminho virtual.A path beginning with ~/ is referred to as a virtual path.

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