Host da Web do ASP.NET Core

ASP.NET Core aplicativos configuram e iniciam um host. O host é responsável pelo gerenciamento de tempo de vida e pela inicialização do aplicativo. No mínimo, o host configura um servidor e um pipeline de processamento de solicitações. O host também pode configurar registro em log, a injeção de dependência e a configuração.

Este artigo aborda o host da Web, que permanece disponível somente para compatibilidade com versões anteriores. os modelos de ASP.NET Core criam um Host genérico .net, que é recomendado para todos os tipos de aplicativo.

Este artigo aborda o host da Web, que serve para hospedar aplicativos Web. Para outros tipos de aplicativos, use o Host genérico.

Configurar um host

Crie um host usando uma instância do IWebHostBuilder. Normalmente, isso é feito no ponto de entrada do aplicativo, o método Main.

Nos modelos de projeto, Main está localizado em Program. cs. Um aplicativo típico chama CreateDefaultBuilder para começar a configurar um 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>();
}

O código que chama CreateDefaultBuilder está em um método chamado CreateWebHostBuilder, que o separa do código em Main, que chama Run no objeto de construtor. Essa separação será necessária se você usar ferramentas do Entity Framework Core. As ferramentas esperam encontrar um método CreateWebHostBuilder que elas possam chamar em tempo de design para configurar o host sem executar o aplicativo. Uma alternativa é implementar IDesignTimeDbContextFactory. Para obter mais informações, confira Criação de DbContext no tempo de design.

CreateDefaultBuilder realiza as seguintes tarefas:

A configuração definida por CreateDefaultBuilder pode ser substituída e aumentada por ConfigureAppConfiguration, ConfigureLogging e outros métodos, bem como os métodos de extensão de IWebHostBuilder. Veja a seguir alguns exemplos:

  • ConfigureAppConfiguration é usado para especificar IConfiguration adicionais para o aplicativo. A seguinte chamada de ConfigureAppConfiguration adiciona um delegado para incluir a configuração do aplicativo no arquivo appsettings.xml. ConfigureAppConfiguration pode ser chamado várias vezes. Observe que essa configuração não se aplica ao host (por exemplo, URLs de servidor ou de ambiente). Consulte a seção Valores de configuração de Host.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • A seguinte chamada de ConfigureLogging adiciona um delegado para configurar o nível de log mínimo (SetMinimumLevel) como LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.jsem ( LogLevel.Debug ) e appsettings.Production.jsno ( LogLevel.Error ) configurado por CreateDefaultBuilder . ConfigureLogging pode ser chamado várias vezes.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • A chamada a seguir para ConfigureKestrel substitui os limites padrão. MaxRequestBodySize de 30 milhões bytes estabelecidos quando Kestrel foi configurado por CreateDefaultBuilder :

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    
  • A seguinte chamada para usar Kestrel substitui os limites padrão. MaxRequestBodySize de 30 milhões bytes estabelecidos quando Kestrel foi configurado por CreateDefaultBuilder :

    WebHost.CreateDefaultBuilder(args)
        .UseKestrel(options =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

A raiz do conteúdo determina onde o host procura por arquivos de conteúdo, como arquivos de exibição do MVC. Quando o aplicativo é iniciado na pasta raiz do projeto, essa pasta é usada como a raiz do conteúdo. Esse é o padrão usado no Visual Studio e nos novos modelos dotnet.

Para obter mais informações sobre a configuração de aplicativo, veja Configuração no ASP.NET Core.

Observação

Como uma alternativa ao uso do método CreateDefaultBuilder estático, criar um host de WebHostBuilder é uma abordagem compatível com o ASP.NET Core 2. x.

Ao configurar um host, os métodos Configure e ConfigureServices podem ser fornecidos. Se uma classe Startup for especificada, ela deverá definir um método Configure. Para obter mais informações, consulte Inicialização de aplicativo no ASP.NET Core. Diversas chamadas para ConfigureServices são acrescentadas umas às outras. Diversas chamadas para Configure ou UseStartup no WebHostBuilder substituem configurações anteriores.

Valores de configuração do host

WebHostBuilder conta com as seguintes abordagens para definir os valores de configuração do host:

  • Configuração do construtor do host, que inclui variáveis de ambiente com o formato ASPNETCORE_{configurationKey}. Por exemplo, ASPNETCORE_ENVIRONMENT.
  • Extensões como UseContentRoot e UseConfiguration (consulte a seção Configuração de substituição).
  • UseSetting e a chave associada. Ao definir um valor com UseSetting, o valor é definido como uma cadeia de caracteres, independentemente do tipo.

O host usa a opção que define um valor por último. Para obter mais informações, veja Substituir configuração na próxima seção.

Chave do Aplicativo (Nome)

A IWebHostEnvironment.ApplicationName propriedade é definida automaticamente quando UseStartup ou Configure é chamado durante a construção do host. O valor é definido para o nome do assembly que contém o ponto de entrada do aplicativo. Para definir o valor explicitamente, use o WebHostDefaults.ApplicationKey:

A propriedade IHostingEnvironment.ApplicationName é definida automaticamente quando UseStartup ou Configure é chamado durante a construção do host. O valor é definido para o nome do assembly que contém o ponto de entrada do aplicativo. Para definir o valor explicitamente, use o WebHostDefaults.ApplicationKey:

Chave: applicationName
Tipo: cadeia de caracteres
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Definir usando: UseSetting
Variável de ambiente: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capturar erros de inicialização

Esta configuração controla a captura de erros de inicialização.

Chave: captureStartupErrors
Tipo: bool (true ou 1)
Padrão: false o padrão é a menos que o aplicativo seja executado com o Kestrel IIS por trás, onde o padrão é true .
Definir usando: CaptureStartupErrors
Variável de ambiente: ASPNETCORE_CAPTURESTARTUPERRORS

Quando false, erros durante a inicialização resultam no encerramento do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raiz do conteúdo

essa configuração determina onde ASP.NET Core começa a pesquisar arquivos de conteúdo.

Chave: contentRoot
Tipo: cadeia de caracteres
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.
Definir usando: UseContentRoot
Variável de ambiente: ASPNETCORE_CONTENTROOT

A raiz do conteúdo também é usada como o caminho base para a raiz da Web. Se o caminho raiz do conteúdo não existir, o host falhará ao iniciar.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Para obter mais informações, consulte:

Erros detalhados

Determina se erros detalhados devem ser capturados.

Chave: detailedErrors
Tipo: bool (true ou 1)
Padrão: false
De definido usando: UseSetting
Variável de ambiente: ASPNETCORE_DETAILEDERRORS

Quando habilitado (ou quando o Ambiente é definido como Development), o aplicativo captura exceções detalhadas.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Ambiente

Define o ambiente do aplicativo.

Chave: ambiente
Tipo: cadeia de caracteres
Padrão: Production
De definido usando: UseEnvironment
Variável de ambiente: ASPNETCORE_ENVIRONMENT

O ambiente pode ser definido como qualquer valor. Os valores definidos pela estrutura incluem Development, Staging e Production. Os valores não diferenciam maiúsculas de minúsculas. Por padrão, o Ambiente é lido da variável de ambiente ASPNETCORE_ENVIRONMENT. Ao usar o Visual Studio, variáveis de ambiente podem ser definidas no arquivo launchSettings.json. Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hospedando assemblies de inicialização

Define os assemblies de inicialização de hospedagem do aplicativo.

Chave: hostingStartupAssemblies
Tipo: cadeia de caracteres
Padrão: cadeia de caracteres vazia
De definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização.

Embora o valor padrão da configuração seja uma cadeia de caracteres vazia, os assemblies de inicialização de hospedagem sempre incluem o assembly do aplicativo. Quando assemblies de inicialização de hospedagem são fornecidos, eles são adicionados ao assembly do aplicativo para carregamento quando o aplicativo compilar seus serviços comuns durante a inicialização.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Porta HTTPS

Defina a porta de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: cadeia de caracteres
Padrão: um valor padrão não está definido.
De definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORT

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Hospedando assemblies de exclusão de inicialização

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.

Chave: hostingStartupExcludeAssemblies
Tipo: cadeia de caracteres
Padrão: cadeia de caracteres vazia
De definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Preferir URLs de hospedagem

Indica se o host deve escutar as URLs configuradas com o WebHostBuilder em vez daquelas configuradas com a implementação IServer.

Chave: preferHostingUrls
Tipo: bool (true ou 1)
Padrão: true
De definido usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Impedir inicialização de hospedagem

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo. Para obter mais informações, consulte Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Chave: preventHostingStartup
Tipo: bool (true ou 1)
Padrão: false
De definido usando: UseSetting
Variável de ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

URLs de servidor

Indica os endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações.

Chave: urls
Tipo: cadeia de caracteres
**Padrão:**http://localhost:5000
De definido usando: UseUrls
Variável de ambiente: ASPNETCORE_URLS

Defina como uma lista separada por ponto e vírgula (;) de prefixos de URL aos quais o servidor deve responder. Por exemplo, http://localhost:123. Use "*" para indicar que o servidor deve escutar solicitações em qualquer endereço IP ou nome do host usando a porta e o protocolo especificados (por exemplo, http://*:5000). O protocolo (http:// ou https://) deve ser incluído com cada URL. Os formatos compatíveis variam dependendo dos servidores.

WebHost.CreateDefaultBuilder(args)
    .UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte configurar pontos de extremidade para o Kestrel servidor web ASP.NET Core.

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte Kestrelimplementação do servidor Web no ASP.NET Core.

Tempo limite de desligamento

Especifica o tempo de espera para o desligamento do host da Web.

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5
De definido usando: UseShutdownTimeout
Variável de ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Embora a chave aceite um int com UseSetting (por exemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), o método de extensão UseShutdownTimeout usa um TimeSpan.

Durante o período de tempo limite, a hospedagem:

Se o período de tempo limite expirar antes que todos os serviços hospedados parem, os serviços ativos restantes serão parados quando o aplicativo for desligado. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Assembly de inicialização

Determina o assembly para pesquisar pela classe Startup.

Chave: startupAssembly
Tipo: cadeia de caracteres
Padrão: o assembly do aplicativo
Definir usando: UseStartup
Variável de ambiente: ASPNETCORE_STARTUPASSEMBLY

O assembly por nome (string) ou por tipo (TStartup) pode ser referenciado. Se vários métodos UseStartup forem chamados, o último terá precedência.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Raiz da Web

Define o caminho relativo para os ativos estáticos do aplicativo.

Chave: webroot
Tipo: cadeia de caracteres
Padrão: o padrão é wwwroot . O caminho para {Content root}/wwwroot deve existir. Se o caminho não existir, um provedor de arquivo não operacional será usado.
Definir usando: UseWebRoot
Variável de ambiente: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Para obter mais informações, consulte:

Substituir configuração

Use Configuração para configurar o host da Web. No exemplo a seguir, a configuração do host é especificada, opcionalmente, em um arquivo hostsettings.json. Qualquer configuração carregada do arquivo hostsettings.json pode ser substituída por argumentos de linha de comando. A configuração de build (no config) é usada para configurar o host com UseConfiguration. A configuração IWebHostBuilder é adicionada à configuração do aplicativo, mas o contrário não é verdade—ConfigureAppConfiguration não afeta a configuração IWebHostBuilder.

Substituição da configuração fornecida por UseUrls pela configuração de hostsettings.json primeiro, e pela configuração de argumento da linha de comando depois:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

Observação

UseConfiguration copia apenas as chaves do fornecido IConfiguration para a configuração do host Builder. Portanto, definir reloadOnChange: true para arquivos de configuração JSON, INI e XML não tem nenhum efeito.

Para especificar o host executado em uma URL específica, o valor desejado pode ser passado em um prompt de comando ao executar dotnet run. O argumento de linha de comando substitui o valor urls do arquivo hostsettings.json e o servidor escuta na porta 8080:

dotnet run --urls "http://*:8080"

Gerenciar o host

Executar

O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:

host.Run();

Iniciar

Execute o host sem bloqueio, chamando seu método Start:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Se uma lista de URLs for passada para o método Start, ele escutará nas URLs especificadas:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

O aplicativo pode inicializar e iniciar um novo host usando os padrões pré-configurados de CreateDefaultBuilder, usando um método estático conveniente. Esses métodos iniciam o servidor sem uma saída do console e com WaitForShutdown e aguardam uma quebra (Ctrl-C/SIGINT ou SIGTERM):

Start(RequestDelegate app)

Inicie com um RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Faça uma solicitação no navegador para http://localhost:5000 para receber a resposta "Olá, Mundo!" WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.

Start(string url, RequestDelegate app)

Inicie com uma URL e RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Produz o mesmo resultado que Start(RequestDelegate app), mas o aplicativo responde em http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Use uma instância de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar o middleware de roteamento:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Use as seguintes solicitações de navegador com o exemplo:

Solicitação Resposta
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Gera uma exceção com a cadeia de caracteres "ooops!"
http://localhost:5000/throw Gera uma exceção com a cadeia de caracteres "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Olá, Mundo!

WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.

Start(string url, Action<IRouteBuilder> routeBuilder)

Use uma URL e uma instância de IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produz o mesmo resultado que Start(Action<IRouteBuilder> routeBuilder), mas o aplicativo responde em http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Forneça um delegado para configurar um IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Faça uma solicitação no navegador para http://localhost:5000 para receber a resposta "Olá, Mundo!" WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.

StartWith(string url, Action<IApplicationBuilder> app)

Forneça um delegado e uma URL para configurar um IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produz o mesmo resultado que StartWith(Action<IApplicationBuilder> app), mas o aplicativo responde em http://localhost:8080.

Interface IWebHostEnvironment

A IWebHostEnvironment interface fornece informações sobre o ambiente de hospedagem na Web do aplicativo. Use a injeção de construtor para obter o IWebHostEnvironment para usar suas propriedades e métodos de extensão:

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Uma abordagem baseada em convenção pode ser usada para configurar o aplicativo na inicialização com base no ambiente. Como alternativa, injete o IWebHostEnvironment no construtor Startup para uso em ConfigureServices:

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Observação

Além do método de extensão IsDevelopment, IWebHostEnvironment oferece os métodos IsStaging, IsProduction e IsEnvironment(string environmentName). Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.

O serviço IWebHostEnvironment também pode ser injetado diretamente no método Configure para configurar o pipeline de processamento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironment pode ser injetado no método Invoke ao criar um middleware personalizado:

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interface IHostingEnvironment

A interface IHostingEnvironment fornece informações sobre o ambiente de hospedagem na Web do aplicativo. Use a injeção de construtor para obter o IHostingEnvironment para usar suas propriedades e métodos de extensão:

public class CustomFileReader
{
    private readonly IHostingEnvironment _env;

    public CustomFileReader(IHostingEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Uma abordagem baseada em convenção pode ser usada para configurar o aplicativo na inicialização com base no ambiente. Como alternativa, injete o IHostingEnvironment no construtor Startup para uso em ConfigureServices:

public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IHostingEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Observação

Além do método de extensão IsDevelopment, IHostingEnvironment oferece os métodos IsStaging, IsProduction e IsEnvironment(string environmentName). Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.

O serviço IHostingEnvironment também pode ser injetado diretamente no método Configure para configurar o pipeline de processamento:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IHostingEnvironment pode ser injetado no método Invoke ao criar um middleware personalizado:

public async Task Invoke(HttpContext context, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interface IHostApplicationLifetime

IHostApplicationLifetime permite atividades de pós-inicialização e desligamento. Três propriedades na interface são tokens de cancelamento usados para registrar métodos Action que definem eventos de inicialização e desligamento.

Token de cancelamento Acionado quando…
ApplicationStarted O host foi iniciado totalmente.
ApplicationStopped O host está concluindo um desligamento normal. Todas as solicitações devem ser processadas. O desligamento é bloqueado até que esse evento seja concluído.
ApplicationStopping O host está executando um desligamento normal. Solicitações ainda podem estar sendo processadas. O desligamento é bloqueado até que esse evento seja concluído.
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication solicita o término do aplicativo. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

    public MyClass(IHostApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Interface IApplicationLifetime

IApplicationLifetime permite atividades pós-inicialização e desligamento. Três propriedades na interface são tokens de cancelamento usados para registrar métodos Action que definem eventos de inicialização e desligamento.

Token de cancelamento Acionado quando…
ApplicationStarted O host foi iniciado totalmente.
ApplicationStopped O host está concluindo um desligamento normal. Todas as solicitações devem ser processadas. O desligamento é bloqueado até que esse evento seja concluído.
ApplicationStopping O host está executando um desligamento normal. Solicitações ainda podem estar sendo processadas. O desligamento é bloqueado até que esse evento seja concluído.
public class Startup
{
    public void Configure(IApplicationBuilder app, IApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication solicita o término do aplicativo. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

    public MyClass(IApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Validação de escopo

CreateDefaultBuilder define ServiceProviderOptions.ValidateScopes como true quando o ambiente do aplicativo é de desenvolvimento.

Quando ValidateScopes está definido como true, o provedor de serviço padrão executa verificações para saber se:

  • Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor de serviço raiz.
  • Os serviços com escopo não são injetados direta ou indiretamente em singletons.

O provedor de serviços raiz é criado quando BuildServiceProvider é chamado. O tempo de vida do provedor de serviço raiz corresponde ao tempo de vida do aplicativo/servidor quando o provedor começa com o aplicativo e é descartado quando o aplicativo é desligado.

Os serviços com escopo são descartados pelo contêiner que os criou. Se um serviço com escopo é criado no contêiner raiz, o tempo de vida do serviço é promovido efetivamente para singleton, porque ele só é descartado pelo contêiner raiz quando o aplicativo/servidor é desligado. A validação dos escopos de serviço detecta essas situações quando BuildServiceProvider é chamado.

Para que os escopos sempre sejam validados, incluindo no ambiente de produção, configure ServiceProviderOptions com UseDefaultServiceProvider no construtor do host:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Recursos adicionais