Host da Web do ASP.NET CoreASP.NET Core Web Host

Por Luke LathamBy Luke Latham

Aplicativos ASP.NET Core configuram e inicializam um host.ASP.NET Core apps configure and launch a host. O host é responsável pelo gerenciamento de tempo de vida e pela inicialização do aplicativo.The host is responsible for app startup and lifetime management. No mínimo, o host configura um servidor e um pipeline de processamento de solicitações.At a minimum, the host configures a server and a request processing pipeline. Este tópico aborda o Host da Web do ASP.NET Core (WebHostBuilder), que é útil para hospedagem de aplicativos Web.This topic covers the ASP.NET Core Web Host (WebHostBuilder), which is useful for hosting web apps. Para cobertura do Host Genérico .NET (HostBuilder), veja o tópico Host Genérico.For coverage of the .NET Generic Host (HostBuilder), see the Generic Host topic.

Configurar um hostSet up a host

Crie um host usando uma instância de WebHostBuilder.Create a host using an instance of WebHostBuilder. Normalmente, isso é feito no ponto de entrada do aplicativo, o método Main.This is typically performed in the app's entry point, the Main method. Em modelos de projeto, Main está localizado em Program.cs.In the project templates, Main is located in Program.cs. Um Program.cs típico chama CreateDefaultBuilder para começar a configurar um host:A typical Program.cs calls CreateDefaultBuilder to start setting up 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>();
}

CreateDefaultBuilder executa as seguintes tarefas:CreateDefaultBuilder performs the following tasks:

A raiz do conteúdo determina onde o host procura por arquivos de conteúdo, como arquivos de exibição do MVC.The content root determines where the host searches for content files, such as MVC view files. Quando o aplicativo é iniciado na pasta raiz do projeto, essa pasta é usada como a raiz do conteúdo.When the app is started from the project's root folder, the project's root folder is used as the content root. Esse é o padrão usado no Visual Studio e nos novos modelos dotnet.This is the default used in Visual Studio and the dotnet new templates.

Para obter mais informações sobre a configuração de aplicativos, consulte Configuração no ASP.NET Core.For more information on app configuration, see Configuration in 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.As an alternative to using the static CreateDefaultBuilder method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x. Para obter mais informações, consulte a guia do ASP.NET Core 1.x.For more information, see the ASP.NET Core 1.x tab.

Ao configurar um host, os métodos Configure e ConfigureServices podem ser fornecidos.When setting up a host, Configure and ConfigureServices methods can be provided. Se uma classe Startup for especificada, ela deverá definir um método Configure.If a Startup class is specified, it must define a Configure method. Para obter mais informações, consulte Inicialização do aplicativo no ASP.NET Core.For more information, see Application Startup in ASP.NET Core. Diversas chamadas para ConfigureServices são acrescentadas umas às outras.Multiple calls to ConfigureServices append to one another. Diversas chamadas para Configure ou UseStartup no WebHostBuilder substituem configurações anteriores.Multiple calls to Configure or UseStartup on the WebHostBuilder replace previous settings.

Valores de configuração do hostHost configuration values

WebHostBuilder conta com as seguintes abordagens para definir os valores de configuração do host:WebHostBuilder relies on the following approaches to set the host configuration values:

  • Configuração do construtor do host, que inclui variáveis de ambiente com o formato ASPNETCORE_{configurationKey}.Host builder configuration, which includes environment variables with the format ASPNETCORE_{configurationKey}. Por exemplo, ASPNETCORE_ENVIRONMENT.For example, ASPNETCORE_ENVIRONMENT.
  • Métodos explícitos, como HostingAbstractionsWebHostBuilderExtensions.UseContentRoot.Explicit methods, such as HostingAbstractionsWebHostBuilderExtensions.UseContentRoot.
  • UseSetting e a chave associada.UseSetting and the associated key. Ao definir um valor com UseSetting, o valor é definido como uma cadeia de caracteres, independentemente do tipo.When setting a value with UseSetting, the value is set as a string regardless of the type.

O host usa a opção que define um valor por último.The host uses whichever option sets a value last. Para obter mais informações, veja Substituir configuração na próxima seção.For more information, see Override configuration in the next section.

Capturar erros de inicializaçãoCapture Startup Errors

Esta configuração controla a captura de erros de inicialização.This setting controls the capture of startup errors.

Chave: captureStartupErrorsKey: captureStartupErrors
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: o padrão é false, a menos que o aplicativo seja executado com o Kestrel por trás do IIS, em que o padrão é true.Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
Definido usando: CaptureStartupErrorsSet using: CaptureStartupErrors
Variável de ambiente: ASPNETCORE_CAPTURESTARTUPERRORSEnvironment variable: ASPNETCORE_CAPTURESTARTUPERRORS

Quando false, erros durante a inicialização resultam no encerramento do host.When false, errors during startup result in the host exiting. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.When true, the host captures exceptions during startup and attempts to start the server.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raiz do conteúdoContent Root

Essa configuração determina onde o ASP.NET Core começa a procurar por arquivos de conteúdo, como exibições do MVC.This setting determines where ASP.NET Core begins searching for content files, such as MVC views.

Chave: contentRootKey: contentRoot
Tipo: stringType: string
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.Default: Defaults to the folder where the app assembly resides.
Definido usando: UseContentRootSet using: UseContentRoot
Variável de ambiente: ASPNETCORE_CONTENTROOTEnvironment variable: ASPNETCORE_CONTENTROOT

A raiz do conteúdo também é usada como o caminho base para a Configuração da raiz da Web.The content root is also used as the base path for the Web Root setting. Se o caminho não existir, o host não será iniciado.If the path doesn't exist, the host fails to start.

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

Erros detalhadosDetailed Errors

Determina se erros detalhados devem ser capturados.Determines if detailed errors should be captured.

Chave: detailedErrorsKey: detailedErrors
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: falsoDefault: false
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_DETAILEDERRORSEnvironment variable: ASPNETCORE_DETAILEDERRORS

Quando habilitado (ou quando o Ambiente é definido como Development), o aplicativo captura exceções detalhadas.When enabled (or when the Environment is set to Development), the app captures detailed exceptions.

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

AmbienteEnvironment

Define o ambiente do aplicativo.Sets the app's environment.

Chave: ambienteKey: environment
Tipo: stringType: string
Padrão: ProductionDefault: Production
Definido usando: UseEnvironmentSet using: UseEnvironment
Variável de ambiente: ASPNETCORE_ENVIRONMENTEnvironment variable: ASPNETCORE_ENVIRONMENT

O ambiente pode ser definido como qualquer valor.The environment can be set to any value. Os valores definidos pela estrutura incluem Development, Staging e Production.Framework-defined values include Development, Staging, and Production. Os valores não diferenciam maiúsculas de minúsculas.Values aren't case sensitive. Por padrão, o Ambiente é lido da variável de ambiente ASPNETCORE_ENVIRONMENT.By default, the Environment is read from the ASPNETCORE_ENVIRONMENT environment variable. Ao usar o Visual Studio, variáveis de ambiente podem ser definidas no arquivo launchSettings.json.When using Visual Studio, environment variables may be set in the launchSettings.json file. Para obter mais informações, veja Usar vários ambientes.For more information, see Use multiple environments.

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

Hospedando assemblies de inicializaçãoHosting Startup Assemblies

Define os assemblies de inicialização de hospedagem do aplicativo.Sets the app's hosting startup assemblies.

Chave: hostingStartupAssembliesKey: hostingStartupAssemblies
Tipo: stringType: string
Padrão: cadeia de caracteres vaziaDefault: Empty string
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização.A semicolon-delimited string of hosting startup assemblies to load on startup. Este recurso é novo no ASP.NET Core 2.0.This feature is new in ASP.NET Core 2.0.

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.Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. 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.When hosting startup assemblies are provided, they're added to the app's assembly for loading when the app builds its common services during startup.

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

Preferir URLs de hospedagemPrefer Hosting URLs

Indica se o host deve escutar as URLs configuradas com o WebHostBuilder em vez daquelas configuradas com a implementação IServer.Indicates whether the host should listen on the URLs configured with the WebHostBuilder instead of those configured with the IServer implementation.

Chave: preferHostingUrlsKey: preferHostingUrls
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: trueDefault: true
Definido usando: PreferHostingUrlsSet using: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLSEnvironment variable: ASPNETCORE_PREFERHOSTINGURLS

Este recurso é novo no ASP.NET Core 2.0.This feature is new in ASP.NET Core 2.0.

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Impedir inicialização de hospedagemPrevent Hosting Startup

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo.Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. Confira Aprimorar um aplicativo em um assembly externo com IHostingStartup para obter mais informações.See Enhance an app from an external assembly with IHostingStartup for more information.

Chave: preventHostingStartupKey: preventHostingStartup
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: falsoDefault: false
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUPEnvironment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP

Este recurso é novo no ASP.NET Core 2.0.This feature is new in ASP.NET Core 2.0.

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

URLs de servidorServer URLs

Indica os endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações.Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.

Chave: urlsKey: urls
Tipo: stringType: string
Padrão: http://localhost:5000Default: http://localhost:5000
Definido usando: UseUrlsSet using: UseUrls
Variável de ambiente: ASPNETCORE_URLSEnvironment variable: ASPNETCORE_URLS

Defina como uma lista separada por ponto e vírgula (;) de prefixos de URL aos quais o servidor deve responder.Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. Por exemplo, http://localhost:123.For example, 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).Use "*" to indicate that the server should listen for requests on any IP address or hostname using the specified port and protocol (for example, http://*:5000). O protocolo (http:// ou https://) deve ser incluído com cada URL.The protocol (http:// or https://) must be included with each URL. Os formatos compatíveis variam dependendo dos servidores.Supported formats vary between servers.

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

O Kestrel tem sua própria API de configuração de ponto de extremidade.Kestrel has its own endpoint configuration API. Para obter mais informações, consulte Implementação do servidor Web Kestrel no ASP.NET Core.For more information, see Kestrel web server implementation in ASP.NET Core.

Tempo limite de desligamentoShutdown Timeout

Especifica o tempo de espera para o desligamento do host da Web.Specifies the amount of time to wait for the web host to shut down.

Chave: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Tipo: intType: int
Padrão: 5Default: 5
Definido usando: UseShutdownTimeoutSet using: UseShutdownTimeout
Variável de ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDSEnvironment variable: 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.Although the key accepts an int with UseSetting (for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), the UseShutdownTimeout extension method takes a TimeSpan. Este recurso é novo no ASP.NET Core 2.0.This feature is new in ASP.NET Core 2.0.

Durante o período de tempo limite, a hospedagem:During the timeout period, hosting:

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.If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento.The services stop even if they haven't finished processing. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.If services require additional time to stop, increase the timeout.

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

Assembly de inicializaçãoStartup Assembly

Determina o assembly para pesquisar pela classe Startup.Determines the assembly to search for the Startup class.

Chave: startupAssemblyKey: startupAssembly
Tipo: stringType: string
Padrão: o assembly do aplicativoDefault: The app's assembly
Definido usando: UseStartupSet using: UseStartup
Variável de ambiente: ASPNETCORE_STARTUPASSEMBLYEnvironment variable: ASPNETCORE_STARTUPASSEMBLY

O assembly por nome (string) ou por tipo (TStartup) pode ser referenciado.The assembly by name (string) or type (TStartup) can be referenced. Se vários métodos UseStartup forem chamados, o último terá precedência.If multiple UseStartup methods are called, the last one takes precedence.

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

Raiz da WebWeb Root

Define o caminho relativo para os ativos estáticos do aplicativo.Sets the relative path to the app's static assets.

Chave: webrootKey: webroot
Tipo: stringType: string
Padrão: se não for especificado, o padrão será "(Raiz do conteúdo)/wwwroot", se o caminho existir.Default: If not specified, the default is "(Content Root)/wwwroot", if the path exists. Se o caminho não existir, um provedor de arquivo não operacional será usado.If the path doesn't exist, then a no-op file provider is used.
Definido usando: UseWebRootSet using: UseWebRoot
Variável de ambiente: ASPNETCORE_WEBROOTEnvironment variable: ASPNETCORE_WEBROOT

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

Substituir configuraçãoOverride configuration

Use Configuração para configurar o host.Use Configuration to configure the host. No exemplo a seguir, a configuração do host é especificada, opcionalmente, em um arquivo hosting.json.In the following example, host configuration is optionally specified in a hosting.json file. Qualquer configuração carregada do arquivo hosting.json pode ser substituída por argumentos de linha de comando.Any configuration loaded from the hosting.json file may be overridden by command-line arguments. A configuração interna (no config) é usada para configurar o host com UseConfiguration.The built configuration (in config) is used to configure the host with UseConfiguration.

hosting.json:hosting.json:

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

Substituição da configuração fornecida por UseUrls pela configuração de hosting.json primeiro e pela configuração de argumento da linha de comando depois:Overriding the configuration provided by UseUrls with hosting.json config first, command-line argument config second:

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

    public static IWebHost BuildWebHost(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hosting.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!"));
            })
            .Build();
    }
}

Observação

Atualmente, o método de extensão UseConfiguration não é capaz de analisar uma seção de configuração retornada por GetSection (por exemplo, .UseConfiguration(Configuration.GetSection("section"))).The UseConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection (for example, .UseConfiguration(Configuration.GetSection("section")). O método GetSection filtra as chaves de configuração da seção solicitada, mas deixa o nome da seção nas chaves (por exemplo, section:urls, section:environment).The GetSection method filters the configuration keys to the section requested but leaves the section name on the keys (for example, section:urls, section:environment). O método UseConfiguration espera que as chaves correspondam às chaves WebHostBuilder (por exemplo, urls, environment).The UseConfiguration method expects the keys to match the WebHostBuilder keys (for example, urls, environment). A presença do nome da seção nas chaves impede que os valores da seção configurem o host.The presence of the section name on the keys prevents the section's values from configuring the host. Esse problema será corrigido em uma próxima versão.This issue will be addressed in an upcoming release. Para obter mais informações e soluções alternativas, consulte Passar a seção de configuração para WebHostBuilder.UseConfiguration usa chaves completas.For more information and workarounds, see Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.

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.To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing dotnet run. O argumento de linha de comando substitui o valor urls do arquivo hosting.json e o servidor escuta na porta 8080:The command-line argument overrides the urls value from the hosting.json file, and the server listens on port 8080:

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

Gerenciar o hostManage the host

ExecutarRun

O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:The Run method starts the web app and blocks the calling thread until the host is shut down:

host.Run();

IniciarStart

Execute o host sem bloqueio, chamando seu método Start:Run the host in a non-blocking manner by calling its Start method:

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

Se uma lista de URLs for passada para o método Start, ele escutará nas URLs especificadas:If a list of URLs is passed to the Start method, it listens on the URLs specified:

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.The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder using a static convenience method. Esses métodos iniciam o servidor sem uma saída do console e com WaitForShutdown e aguardam uma quebra (Ctrl-C/SIGINT ou SIGTERM):These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):

Start(RequestDelegate app)Start(RequestDelegate app)

Inicie com um RequestDelegate:Start with a 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!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida.WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, RequestDelegate app)Start(string url, RequestDelegate app)

Inicie com uma URL e RequestDelegate:Start with a URL and 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.Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)Start(Action<IRouteBuilder> routeBuilder)

Use uma instância de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar o middleware de roteamento:Use an instance of IRouteBuilder (Microsoft.AspNetCore.Routing) to use routing middleware:

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:Use the following browser requests with the example:

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

WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida.WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, Action<IRouteBuilder> routeBuilder)Start(string url, Action<IRouteBuilder> routeBuilder)

Use uma URL e uma instância de IRouteBuilder:Use a URL and an instance of 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.Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)StartWith(Action<IApplicationBuilder> app)

Forneça um delegado para configurar um IApplicationBuilder:Provide a delegate to configure an 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!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida.WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.The app displays the Console.WriteLine message and waits for a keypress to exit.

StartWith(string url, Action<IApplicationBuilder> app)StartWith(string url, Action<IApplicationBuilder> app)

Forneça um delegado e uma URL para configurar um IApplicationBuilder:Provide a URL and a delegate to configure an 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.Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080.

Interface IHostingEnvironmentIHostingEnvironment interface

A interface IHostingEnvironment fornece informações sobre o ambiente de hospedagem na Web do aplicativo.The IHostingEnvironment interface provides information about the app's web hosting environment. Use a injeção de construtor para obter o IHostingEnvironment para usar suas propriedades e métodos de extensão:Use constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:

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.A convention-based approach can be used to configure the app at startup based on the environment. Como alternativa, injete o IHostingEnvironment no construtor Startup para uso em ConfigureServices:Alternatively, inject the IHostingEnvironment into the Startup constructor for use in 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).In addition to the IsDevelopment extension method, IHostingEnvironment offers IsStaging, IsProduction, and IsEnvironment(string environmentName) methods. Confira Usar vários ambientes para obter detalhes.See Use multiple environments for details.

O serviço IHostingEnvironment também pode ser injetado diretamente no método Configure para configurar o pipeline de processamento:The IHostingEnvironment service can also be injected directly into the Configure method for setting up the processing pipeline:

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:IHostingEnvironment can be injected into the Invoke method when creating custom middleware:

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 IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime permite atividades pós-inicialização e desligamento.IApplicationLifetime allows for post-startup and shutdown activities. Três propriedades na interface são tokens de cancelamento usados para registrar métodos Action que definem eventos de inicialização e desligamento.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Token de cancelamentoCancellation Token Acionado quando…Triggered when…
ApplicationStartedApplicationStarted O host foi iniciado totalmente.The host has fully started.
ApplicationStoppedApplicationStopped O host está concluindo um desligamento normal.The host is completing a graceful shutdown. Todas as solicitações devem ser processadas.All requests should be processed. O desligamento é bloqueado até que esse evento seja concluído.Shutdown blocks until this event completes.
ApplicationStoppingApplicationStopping O host está executando um desligamento normal.The host is performing a graceful shutdown. Solicitações ainda podem estar sendo processadas.Requests may still be processing. O desligamento é bloqueado até que esse evento seja concluído.Shutdown blocks until this event completes.
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.StopApplication requests termination of the app. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

Validação de escopoScope validation

No ASP.NET Core 2.0 ou posterior, CreateDefaultBuilder define ServiceProviderOptions.ValidateScopes como true quando o ambiente do aplicativo é de desenvolvimento.In ASP.NET Core 2.0 or later, CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true if the app's environment is Development.

Quando ValidateScopes está definido como true, o provedor de serviço padrão executa verificações para saber se:When ValidateScopes is set to true, the default service provider performs checks to verify that:

  • Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor de serviço raiz.Scoped services aren't directly or indirectly resolved from the root service provider.
  • Os serviços com escopo não são injetados direta ou indiretamente em singletons.Scoped services aren't directly or indirectly injected into singletons.

O provedor de serviços raiz é criado quando BuildServiceProvider é chamado.The root service provider is created when BuildServiceProvider is called. 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.The root service provider's lifetime corresponds to the app/server's lifetime when the provider starts with the app and is disposed when the app shuts down.

Os serviços com escopo são descartados pelo contêiner que os criou.Scoped services are disposed by the container that created them. 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.If a scoped service is created in the root container, the service's lifetime is effectively promoted to singleton because it's only disposed by the root container when app/server is shut down. A validação dos escopos de serviço detecta essas situações quando BuildServiceProvider é chamado.Validating service scopes catches these situations when BuildServiceProvider is called.

Para que os escopos sempre sejam validados, incluindo no ambiente de produção, configure ServiceProviderOptions com UseDefaultServiceProvider no construtor do host:To always validate scopes, including in the Production environment, configure the ServiceProviderOptions with UseDefaultServiceProvider on the host builder:

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

Solução de problemas de System.ArgumentExceptionTroubleshooting System.ArgumentException

Aplica-se somente ao ASP.NET Core 2.0Applies to ASP.NET Core 2.0 Only

Um host pode ser compilado injetando IStartup diretamente no contêiner de injeção de dependência em vez de chamar UseStartup ou Configure:A host may be built by injecting IStartup directly into the dependency injection container rather than calling UseStartup or Configure:

services.AddSingleton<IStartup, Startup>();

Se o host for compilado dessa maneira, o seguinte erro poderá ocorrer:If the host is built this way, the following error may occur:

Unhandled Exception: System.ArgumentException: A valid non-empty application name must be provided.

Isso ocorre porque o applicationName(ApplicationKey) (do assembly atual) é necessário para verificar se há HostingStartupAttributes.This occurs because the applicationName(ApplicationKey) (the current assembly) is required to scan for HostingStartupAttributes. Se o aplicativo injetar manualmente IStartup no contêiner de injeção de dependência, adicione a seguinte chamada para WebHostBuilder com o nome do assembly especificado:If the app manually injects IStartup into the dependency injection container, add the following call to WebHostBuilder with the assembly name specified:

WebHost.CreateDefaultBuilder(args)
    .UseSetting("applicationName", "<Assembly Name>")
    ...

Como alternativa, adicione um Configure fictício ao WebHostBuilder, que define o applicationName(ApplicationKey) automaticamente:Alternatively, add a dummy Configure to the WebHostBuilder, which sets the applicationName(ApplicationKey) automatically:

WebHost.CreateDefaultBuilder(args)
    .Configure(_ => { })
    ...

Observação: isso só é necessário com a versão do ASP.NET Core 2.0 e somente quando o aplicativo não chama UseStartup ou Configure.NOTE: This is only required with the ASP.NET Core 2.0 release and only when the app doesn't call UseStartup or Configure.

Para obter mais informações, consulte Comunicado: Microsoft.Extensions.PlatformAbstractions foi removido (comentário) e o Exemplo de StartupInjection.For more information, see Announcements: Microsoft.Extensions.PlatformAbstractions has been removed (comment) and the StartupInjection sample.

Recursos adicionaisAdditional resources