Condividi tramite


Host Web ASP.NET Core

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Le app ASP.NET Core configurano e avviano un host. L'host è responsabile della gestione dell'avvio e della durata delle app. L'host configura almeno un server e una pipeline di elaborazione delle richieste. L'host può anche configurare la registrazione, l'inserimento delle dipendenze e la configurazione.

Questo articolo descrive l'host Web, che rimane disponibile solo per compatibilità con le versioni precedenti. I modelli ASP.NET Core creano un WebApplicationBuilder e WebApplication, consigliato per le app Web. Per altre informazioni su WebApplicationBuilder e WebApplication, vedere Eseguire la migrazione da ASP.NET Core 5.0 a 6.0

Configurare un host

Creare un host usando un'istanza di IWebHostBuilder. Questa operazione viene in genere eseguita nel punto di ingresso dell'app, il Main metodo in Program.cs. Una tipica chiamata CreateDefaultBuilder dell'app per avviare la configurazione di un 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>();
}

Il codice che chiama CreateDefaultBuilder è incluso in un metodo denominato CreateWebHostBuilder, che lo separa dal codice in Main che chiama Run per l'oggetto generatore. Questa separazione è necessaria se si usano gli strumenti di Entity Framework Core. Gli strumenti si aspettano di trovare un metodo CreateWebHostBuilder che possono chiamare in fase di progettazione per configurare l'host senza eseguire l'app. Un'alternativa consiste nell'implementare IDesignTimeDbContextFactory. Per altre informazioni, vedere Creazione DbContext in fase di progettazione.

CreateDefaultBuilder esegue queste attività:

La configurazione definita da CreateDefaultBuilder può essere sottoposta a override e aumentata da ConfigureAppConfiguration, ConfigureLogginge altri metodi e metodi di estensione di IWebHostBuilder. Di seguito sono riportati alcuni esempi:

  • ConfigureAppConfiguration viene usato per specificare ulteriori IConfiguration informazioni per l'app. La chiamata seguente ConfigureAppConfiguration aggiunge un delegato per includere la appsettings.xml configurazione dell'app nel file. ConfigureAppConfiguration può essere chiamato più volte. Si noti che questa configurazione non è valida per l'host (ad esempio, gli URL del server o l'ambiente). Vedere la sezione Valori di configurazione dell'host.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • La chiamata seguente ConfigureLogging aggiunge un delegato per configurare il livello di registrazione minimo (SetMinimumLevel) a LogLevel.Warning. Questa impostazione sostituisce le impostazioni in appsettings.Development.json () e appsettings.Production.json (LogLevel.Error) configurate da CreateDefaultBuilderLogLevel.Debug. ConfigureLogging può essere chiamato più volte.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • La chiamata seguente per ConfigureKestrel eseguire l'override del valore predefinito Limits.MaxRequestBodySize di 30.000.000 byte stabilito quando Kestrel è stato configurato da CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

La radice del contenuto determina la posizione in cui l'host cerca i file dei contenuti, ad esempio i file di visualizzazione MVC. Quando l'app viene avviata dalla cartella radice del progetto, la cartella radice del progetto viene usata come radice del contenuto. Si tratta dell'impostazione predefinita usata in Visual Studio e nei nuovi modelli dotnet.

Per altre informazioni sulla configurazione delle app, vedere Configurazione in ASP.NET Core.

Nota

In alternativa all'uso del metodo statico CreateDefaultBuilder , la creazione di un host da WebHostBuilder è un approccio supportato con ASP.NET Core 2.x.

Quando si configura un host, Configure è possibile specificare i metodi e ConfigureServices . Se viene specificata una classe Startup, la classe deve definire un metodo Configure. Per altre informazioni, vedere Avvio delle app in ASP.NET Core. Se vengono effettuate più chiamate a ConfigureServices, le chiamate vengono aggiunte l'una all'altra. Più chiamate a Configure o UseStartup in WebHostBuilder sostituiscono le impostazioni precedenti.

Valori di configurazione dell'host

WebHostBuilder si basa sugli approcci seguenti per impostare i valori di configurazione host:

  • Configurazione del generatore di host, che include le variabili di ambiente nel formato ASPNETCORE_{configurationKey}. Ad esempio: ASPNETCORE_ENVIRONMENT.
  • Estensioni come UseContentRoot e UseConfiguration (vedere la sezione Eseguire l'override della configurazione ).
  • UseSetting e la chiave associata. Quando si imposta un valore con UseSetting, il valore viene impostato come stringa indipendentemente dal tipo.

L'host usa l'ultima opzione che imposta un valore. Per altre informazioni, vedere Override della configurazione nella prossima sezione.

Chiave applicazione (nome)

La IWebHostEnvironment.ApplicationName proprietà viene impostata automaticamente quando UseStartup o Configure viene chiamato durante la costruzione dell'host. Il valore viene impostato sul nome dell'assembly contenente il punto di ingresso dell'app. Per impostare il valore in modo esplicito, usare :WebHostDefaults.ApplicationKey

Chiave: applicationName
Tipo: string
Impostazione predefinita: il nome dell'assembly contenente il punto di ingresso dell'app.
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_APPLICATIONNAME

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

Acquisizione degli errori di avvio

Questa impostazione controlla l'acquisizione degli errori di avvio.

Chiave: captureStartupErrors
Tipo: bool (true o 1)
Impostazione predefinita: l'impostazione predefinita è false a meno che l'app non venga eseguita con Kestrel IIS, dove il valore predefinito è true.
Impostare usando: CaptureStartupErrors
Variabile di ambiente: ASPNETCORE_CAPTURESTARTUPERRORS

Quando è false, gli errori durante l'avvio causano la chiusura dell'host. Quando è true, l'host acquisisce le eccezioni durante l'avvio e tenta di avviare il server.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Radice del contenuto

Questa impostazione determina dove ASP.NET Core inizia la ricerca di file di contenuto.

Chiave: contentRoot
Tipo: string
Impostazione predefinita: il valore predefinito corrisponde alla cartella contenente l'assembly dell'app.
Impostare usando: UseContentRoot
Variabile di ambiente: ASPNETCORE_CONTENTROOT

La radice del contenuto viene usata anche come percorso di base per la radice Web. Se il percorso radice del contenuto non esiste, l'host non viene avviato.

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

Per altre informazioni, vedi:

Errori dettagliati

Determina l'acquisizione degli errori dettagliati.

Chiave: detailedErrors
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_DETAILEDERRORS

Quando è abilitata (o quando l'ambiente è impostato su Development), l'app acquisisce le eccezioni dettagliate.

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

Ambiente

Imposta l'ambiente per l'app.

Chiave: environment
Tipo: string
Impostazione predefinita: Production
Impostare usando: UseEnvironment
Variabile di ambiente: ASPNETCORE_ENVIRONMENT

L'ambiente può essere impostato su qualsiasi valore. I valori definiti dal framework includono Development, Staging e Production. Nei valori non viene fatta distinzione tra maiuscole e minuscole. Per impostazione predefinita, l'ambiente viene letto dalla variabile di ambiente ASPNETCORE_ENVIRONMENT. Quando si usa Visual Studio, le variabili di ambiente possono essere impostate nel launchSettings.json file. Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

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

Assembly di avvio dell'hosting

Imposta gli assembly di avvio dell'hosting dell'app.

Chiave: hostingStartupAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da caricare all'avvio.

Sebbene il valore di configurazione predefinito sia una stringa vuota, gli assembly di avvio dell'hosting includono sempre l'assembly dell'app. Quando vengono specificati, gli assembly di avvio dell'hosting vengono aggiunti all'assembly dell'app per essere caricati quando l'app compila i servizi comuni durante l'avvio.

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

Porta HTTPS

Impostare la porta HTTPS su cui eseguire il reindirizzamento se si ottiene una connessione non HTTPS. Usata per imporre HTTPS. Questa impostazione non causa l'ascolto del server sulla porta specificata. Ciò significa che è possibile reindirizzare accidentalmente le richieste a una porta inutilizzata.

Chiave: https_port
Tipo: string
Impostazione predefinita: un valore predefinito non è impostato.
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HTTPS_PORT

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

Porte HTTPS

Impostare le porte su cui rimanere in ascolto per le connessioni HTTPS.

Chiave: https_ports Tipo: stringa
Impostazione predefinita: un valore predefinito non è impostato.
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HTTPS_PORTS

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

Assembly di avvio dell'hosting da escludere

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da escludere all'avvio.

Chiave: hostingStartupExcludeAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Preferire gli URL di hosting

Indica se l'host deve eseguire l'ascolto sugli URL configurati con WebHostBuilder anziché su quelli configurati con l'implementazione IServer.

Chiave: preferHostingUrls
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: PreferHostingUrls
Variabile di ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Impedire l'avvio dell'hosting

Impedisce il caricamento automatico degli assembly di avvio dell'hosting, inclusi gli assembly di avvio dell'hosting configurati dall'assembly dell'app. Per altre informazioni, vedere Usare assembly di avvio dell'hosting in ASP.NET Core.

Chiave: preventHostingStartup
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

URL del server

Indica gli indirizzi IP o gli indirizzi host con le porte e protocolli su cui il server deve eseguire l'ascolto per le richieste.

Chiave: urls
Tipo: string
Predefinito: http://localhost:5000
Impostare usando: UseUrls
Variabile di ambiente: ASPNETCORE_URLS

Impostare su un elenco di prefissi URL separati da punto e virgola (;) ai quali il server deve rispondere. Ad esempio: http://localhost:123. Usare "*" per indicare che il server deve restare in ascolto delle richieste su qualsiasi indirizzo IP o nome host usando la porta e il protocollo specificati , ad esempio http://*:5000. Il protocollo (http:// o https://) deve essere incluso con ogni URL. I formati supportati variano a seconda del server.

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

Kestrel ha una propria API di configurazione dell'endpoint. Per altre informazioni, vedere Configurare gli endpoint per il server Web ASP.NET CoreKestrel.

Timeout di arresto

Specifica il tempo di attesa per l'arresto dell'host Web.

Chiave: shutdownTimeoutSeconds
Tipo: int
Impostazione predefinita: 5
Impostare usando: UseShutdownTimeout
Variabile di ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Sebbene la chiave accetti int con UseSetting (ad esempio, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), il metodo di estensione UseShutdownTimeout accetta TimeSpan.

Durante il periodo di timeout, l'hosting:

Se il periodo di timeout scade prima che siano stati arrestati tutti i servizi ospitati, gli eventuali servizi attivi rimanenti vengono interrotti quando l'app viene arrestata. I servizi si arrestano anche se non hanno completato l'elaborazione. Se l'arresto dei servizi richiede più tempo, aumentare il valore di timeout.

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

Assembly di avvio

Determina l'assembly per la ricerca della classe Startup.

Chiave: startupAssembly
Tipo: string
Impostazione predefinita: assembly dell'app
Impostare usando: UseStartup
Variabile di ambiente: ASPNETCORE_STARTUPASSEMBLY

È possibile fare riferimento all'assembly per nome (string) o per tipo (TStartup). Se vengono chiamati più metodi UseStartup, l'ultimo metodo ha la precedenza.

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

Radice Web

Imposta il percorso relativo degli asset statici dell'app.

Chiave: webroot
Tipo: string
Impostazione predefinita: il valore predefinito è wwwroot. Il percorso di {content root}/wwwroot deve esistere. Se il percorso non esiste, viene usato un provider di file no-op.
Impostare usando: UseWebRoot
Variabile di ambiente: ASPNETCORE_WEBROOT

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

Per altre informazioni, vedi:

Override della configurazione

Usare la Configurazione per configurare l'host Web. Nell'esempio seguente, la configurazione host viene specificata facoltativamente in un hostsettings.json file. Qualsiasi configurazione caricata dal hostsettings.json file può essere sottoposta a override dagli argomenti della riga di comando. La configurazione compilata (in config) viene usata per configurare l'host con UseConfiguration. IWebHostBuilder la configurazione viene aggiunta alla configurazione dell'app, ma il contrario non è true,ConfigureAppConfiguration non influisce sulla IWebHostBuilder configurazione.

Override della configurazione fornita da UseUrls con hostsettings.json config first, command-line argument config second:

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

Nota

UseConfiguration copia solo le chiavi dall'elemento IConfiguration specificato nella configurazione del generatore di host. Pertanto, l'impostazione di reloadOnChange: true per i file JSON, INI e XML non ha alcun effetto.

Per specificare l'host eseguito in un URL specifico, il valore desiderato può essere passato da un prompt dei comandi durante l'esecuzione di dotnet run. L'argomento della riga di comando esegue l'override del urls valore del hostsettings.json file e il server è in ascolto sulla porta 8080:

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

Gestire l'host

Run

Il metodo Run avvia l'app Web e blocca il thread di chiamata fino all'arresto dell'host:

host.Run();

Avviare

Eseguire l'host in modo non bloccante chiamandone il metodo Start:

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

Se viene passato un elenco di URL al metodo Start, viene eseguito l'ascolto sugli URL specificati:

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

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

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

L'app può inizializzare e avviare un nuovo host usando i valori predefiniti preconfigurati di CreateDefaultBuilder con un metodo pratico statico. Questi metodi avviano il server senza output della console e attendono WaitForShutdown un'interruzione (CTRL-C/SIGINT o SIGTERM):

Start(RequestDelegate app)

Start con RequestDelegate:

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

Effettuare una richiesta nel browser per http://localhost:5000 ricevere la risposta "Hello World!" WaitForShutdown blocca fino a quando non viene eseguita un'interruzione (CTRL-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

Start(string url, RequestDelegate app)

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

Produce lo stesso risultato di Start(app RequestDelegate), ad eccezione del fatto che l'app risponde su http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Usare un'istanza di IRouteBuilder (Microsoft.AspNetCore.Routing) per usare il middleware di routing:

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

Usare le richieste del browser seguenti con l'esempio:

Richiedi Risposta
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Genera un'eccezione con la stringa "ooops!"
http://localhost:5000/throw Genera un'eccezione con la stringa "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown rimane bloccato fino a quando non viene eseguita un'interruzione (Ctrl-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

Start(string url, Action<IRouteBuilder> routeBuilder)

Usare un URL e un'istanza di 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();
}

Produce lo stesso risultato di Start(Action<IRouteBuilder> routeBuilder), ad eccezione del fatto che l'app risponde in http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Specificare un delegato per configurare 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();
}

Effettuare una richiesta nel browser per http://localhost:5000 ricevere la risposta "Hello World!" WaitForShutdown blocca fino a quando non viene eseguita un'interruzione (CTRL-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

StartWith(string url, Action<IApplicationBuilder> app)

Specificare un URL e un delegato per configurare 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();
}

Produce lo stesso risultato di StartWith(Action<IApplicationBuilder> app), ad eccezione del fatto che l'app risponde su http://localhost:8080.

Interfaccia IWebHostEnvironment

L'interfaccia IWebHostEnvironment fornisce informazioni sull'ambiente di hosting Web dell'app. Usare l'inserimento di un costruttore per ottenere IWebHostEnvironment per poterne usare le proprietà e i metodi di estensione:

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

È possibile usare un approccio basato su convenzione per configurare l'app all'avvio in base all'ambiente. In alternativa, inserire IWebHostEnvironment nel costruttore Startup per l'utilizzo in 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;
    }
}

Nota

Oltre al metodo di estensione IsDevelopment, IWebHostEnvironment offre i metodi IsStaging, IsProduction e IsEnvironment(string environmentName). Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

Il servizio IWebHostEnvironment può anche essere inserito direttamente nel metodo Configure per configurare la pipeline di elaborazione:

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 può essere inserito nel metodo Invoke durante la creazione di middleware personalizzato:

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

Interfaccia IHostApplicationLifetime

IHostApplicationLifetime consente attività successive all'avvio e all'arresto. Tre proprietà nell'interfaccia sono token di annullamento usati per registrare i metodi Action che definiscono gli eventi di avvio e arresto.

Token di annullamento Attivato quando...
ApplicationStarted L'host è stato completamente avviato.
ApplicationStopped L'host sta completando un arresto normale. Tutte le richieste devono essere elaborate. L'arresto è bloccato fino al completamento di questo evento.
ApplicationStopping L'host sta eseguendo un arresto normale. È possibile che le richieste siano ancora in esecuzione. L'arresto è bloccato fino al completamento di questo evento.
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 richiede la chiusura dell'applicazione corrente. La classe seguente usa StopApplication per arrestare normalmente un'app quando viene chiamato il metodo Shutdown della classe:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Convalida dell'ambito

CreateDefaultBuilder imposta su ServiceProviderOptions.ValidateScopes true se l'ambiente dell'app è Sviluppo.

Quando ValidateScopes è impostato su true, il provider di servizi predefinito esegue dei controlli per verificare che:

  • I servizi con ambito non vengano risolti direttamente o indirettamente dal provider di servizi radice.
  • I servizi con ambito non vengano inseriti direttamente o indirettamente in singleton.

Il provider di servizi radice venga creato con la chiamata di BuildServiceProvider. La durata del provider di servizi radice corrisponde alla durata dell'app/server quando il provider viene avviato con l'app e viene eliminato alla chiusura dell'app.

I servizi con ambito vengono eliminati dal contenitore che li ha creati. Se un servizio con ambito viene creato nel contenitore radice, la durata del servizio viene di fatto convertita in singleton, perché il servizio viene eliminato solo dal contenitore radice alla chiusura dell'app/server. La convalida degli ambiti servizio rileva queste situazioni nel contesto della chiamata di BuildServiceProvider.

Per convalidare sempre gli ambiti, incluso nell'ambiente di produzione, configurare ServiceProviderOptions con UseDefaultServiceProvider nel generatore host:

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

Risorse aggiuntive

Le app ASP.NET Core configurano e avviano un host. L'host è responsabile della gestione dell'avvio e della durata delle app. L'host configura almeno un server e una pipeline di elaborazione delle richieste. L'host può anche configurare la registrazione, l'inserimento delle dipendenze e la configurazione.

Questo articolo descrive l'host Web, che rimane disponibile solo per compatibilità con le versioni precedenti. I modelli di ASP.NET Core creano un host generico .NET, consigliato per tutti i tipi di app.

Configurare un host

Creare un host usando un'istanza di IWebHostBuilder. Questa operazione viene in genere eseguita nel punto di ingresso dell'app, il metodo Main.

Nei modelli Main di progetto si trova in Program.cs. Una tipica chiamata CreateDefaultBuilder dell'app per avviare la configurazione di un 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>();
}

Il codice che chiama CreateDefaultBuilder è incluso in un metodo denominato CreateWebHostBuilder, che lo separa dal codice in Main che chiama Run per l'oggetto generatore. Questa separazione è necessaria se si usano gli strumenti di Entity Framework Core. Gli strumenti si aspettano di trovare un metodo CreateWebHostBuilder che possono chiamare in fase di progettazione per configurare l'host senza eseguire l'app. Un'alternativa consiste nell'implementare IDesignTimeDbContextFactory. Per altre informazioni, vedere Creazione DbContext in fase di progettazione.

CreateDefaultBuilder esegue queste attività:

La configurazione definita da CreateDefaultBuilder può essere sottoposta a override e aumentata da ConfigureAppConfiguration, ConfigureLogginge altri metodi e metodi di estensione di IWebHostBuilder. Di seguito sono riportati alcuni esempi:

  • ConfigureAppConfiguration viene usato per specificare ulteriori IConfiguration informazioni per l'app. La chiamata seguente ConfigureAppConfiguration aggiunge un delegato per includere la appsettings.xml configurazione dell'app nel file. ConfigureAppConfiguration può essere chiamato più volte. Si noti che questa configurazione non è valida per l'host (ad esempio, gli URL del server o l'ambiente). Vedere la sezione Valori di configurazione dell'host.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • La chiamata seguente ConfigureLogging aggiunge un delegato per configurare il livello di registrazione minimo (SetMinimumLevel) a LogLevel.Warning. Questa impostazione sostituisce le impostazioni in appsettings.Development.json () e appsettings.Production.json (LogLevel.Error) configurate da CreateDefaultBuilderLogLevel.Debug. ConfigureLogging può essere chiamato più volte.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • La chiamata seguente per ConfigureKestrel eseguire l'override del valore predefinito Limits.MaxRequestBodySize di 30.000.000 byte stabilito quando Kestrel è stato configurato da CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

La radice del contenuto determina la posizione in cui l'host cerca i file dei contenuti, ad esempio i file di visualizzazione MVC. Quando l'app viene avviata dalla cartella radice del progetto, la cartella radice del progetto viene usata come radice del contenuto. Si tratta dell'impostazione predefinita usata in Visual Studio e nei nuovi modelli dotnet.

Per altre informazioni sulla configurazione delle app, vedere Configurazione in ASP.NET Core.

Nota

In alternativa all'uso del metodo statico CreateDefaultBuilder , la creazione di un host da WebHostBuilder è un approccio supportato con ASP.NET Core 2.x.

Quando si configura un host, Configure è possibile specificare i metodi e ConfigureServices . Se viene specificata una classe Startup, la classe deve definire un metodo Configure. Per altre informazioni, vedere Avvio delle app in ASP.NET Core. Se vengono effettuate più chiamate a ConfigureServices, le chiamate vengono aggiunte l'una all'altra. Più chiamate a Configure o UseStartup in WebHostBuilder sostituiscono le impostazioni precedenti.

Valori di configurazione dell'host

WebHostBuilder si basa sugli approcci seguenti per impostare i valori di configurazione host:

  • Configurazione del generatore di host, che include le variabili di ambiente nel formato ASPNETCORE_{configurationKey}. Ad esempio: ASPNETCORE_ENVIRONMENT.
  • Estensioni come UseContentRoot e UseConfiguration (vedere la sezione Eseguire l'override della configurazione ).
  • UseSetting e la chiave associata. Quando si imposta un valore con UseSetting, il valore viene impostato come stringa indipendentemente dal tipo.

L'host usa l'ultima opzione che imposta un valore. Per altre informazioni, vedere Override della configurazione nella prossima sezione.

Chiave applicazione (nome)

La IWebHostEnvironment.ApplicationName proprietà viene impostata automaticamente quando UseStartup o Configure viene chiamato durante la costruzione dell'host. Il valore viene impostato sul nome dell'assembly contenente il punto di ingresso dell'app. Per impostare il valore in modo esplicito, usare :WebHostDefaults.ApplicationKey

Chiave: applicationName
Tipo: string
Impostazione predefinita: il nome dell'assembly contenente il punto di ingresso dell'app.
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_APPLICATIONNAME

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

Acquisizione degli errori di avvio

Questa impostazione controlla l'acquisizione degli errori di avvio.

Chiave: captureStartupErrors
Tipo: bool (true o 1)
Impostazione predefinita: l'impostazione predefinita è false a meno che l'app non venga eseguita con Kestrel IIS, dove il valore predefinito è true.
Impostare usando: CaptureStartupErrors
Variabile di ambiente: ASPNETCORE_CAPTURESTARTUPERRORS

Quando è false, gli errori durante l'avvio causano la chiusura dell'host. Quando è true, l'host acquisisce le eccezioni durante l'avvio e tenta di avviare il server.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Radice del contenuto

Questa impostazione determina dove ASP.NET Core inizia la ricerca di file di contenuto.

Chiave: contentRoot
Tipo: string
Impostazione predefinita: il valore predefinito corrisponde alla cartella contenente l'assembly dell'app.
Impostare usando: UseContentRoot
Variabile di ambiente: ASPNETCORE_CONTENTROOT

La radice del contenuto viene usata anche come percorso di base per la radice Web. Se il percorso radice del contenuto non esiste, l'host non viene avviato.

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

Per altre informazioni, vedi:

Errori dettagliati

Determina l'acquisizione degli errori dettagliati.

Chiave: detailedErrors
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_DETAILEDERRORS

Quando è abilitata (o quando l'ambiente è impostato su Development), l'app acquisisce le eccezioni dettagliate.

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

Ambiente

Imposta l'ambiente per l'app.

Chiave: environment
Tipo: string
Impostazione predefinita: Production
Impostare usando: UseEnvironment
Variabile di ambiente: ASPNETCORE_ENVIRONMENT

L'ambiente può essere impostato su qualsiasi valore. I valori definiti dal framework includono Development, Staging e Production. Nei valori non viene fatta distinzione tra maiuscole e minuscole. Per impostazione predefinita, l'ambiente viene letto dalla variabile di ambiente ASPNETCORE_ENVIRONMENT. Quando si usa Visual Studio, le variabili di ambiente possono essere impostate nel launchSettings.json file. Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

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

Assembly di avvio dell'hosting

Imposta gli assembly di avvio dell'hosting dell'app.

Chiave: hostingStartupAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da caricare all'avvio.

Sebbene il valore di configurazione predefinito sia una stringa vuota, gli assembly di avvio dell'hosting includono sempre l'assembly dell'app. Quando vengono specificati, gli assembly di avvio dell'hosting vengono aggiunti all'assembly dell'app per essere caricati quando l'app compila i servizi comuni durante l'avvio.

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

Porta HTTPS

Impostare la porta di reindirizzamento HTTPS. Usata per imporre HTTPS.

Chiave: https_port
Tipo: string
Impostazione predefinita: un valore predefinito non è impostato.
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HTTPS_PORTS

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

Assembly di avvio dell'hosting da escludere

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da escludere all'avvio.

Chiave: hostingStartupExcludeAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Preferire gli URL di hosting

Indica se l'host deve eseguire l'ascolto sugli URL configurati con WebHostBuilder anziché su quelli configurati con l'implementazione IServer.

Chiave: preferHostingUrls
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: PreferHostingUrls
Variabile di ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Impedire l'avvio dell'hosting

Impedisce il caricamento automatico degli assembly di avvio dell'hosting, inclusi gli assembly di avvio dell'hosting configurati dall'assembly dell'app. Per altre informazioni, vedere Usare assembly di avvio dell'hosting in ASP.NET Core.

Chiave: preventHostingStartup
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

URL del server

Indica gli indirizzi IP o gli indirizzi host con le porte e protocolli su cui il server deve eseguire l'ascolto per le richieste.

Chiave: urls
Tipo: string
Predefinito: http://localhost:5000
Impostare usando: UseUrls
Variabile di ambiente: ASPNETCORE_URLS

Impostare su un elenco di prefissi URL separati da punto e virgola (;) ai quali il server deve rispondere. Ad esempio: http://localhost:123. Usare "*" per indicare che il server deve restare in ascolto delle richieste su qualsiasi indirizzo IP o nome host usando la porta e il protocollo specificati , ad esempio http://*:5000. Il protocollo (http:// o https://) deve essere incluso con ogni URL. I formati supportati variano a seconda del server.

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

Kestrel ha una propria API di configurazione dell'endpoint. Per altre informazioni, vedere Configurare gli endpoint per il server Web ASP.NET CoreKestrel.

Timeout di arresto

Specifica il tempo di attesa per l'arresto dell'host Web.

Chiave: shutdownTimeoutSeconds
Tipo: int
Impostazione predefinita: 5
Impostare usando: UseShutdownTimeout
Variabile di ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Sebbene la chiave accetti int con UseSetting (ad esempio, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), il metodo di estensione UseShutdownTimeout accetta TimeSpan.

Durante il periodo di timeout, l'hosting:

Se il periodo di timeout scade prima che siano stati arrestati tutti i servizi ospitati, gli eventuali servizi attivi rimanenti vengono interrotti quando l'app viene arrestata. I servizi si arrestano anche se non hanno completato l'elaborazione. Se l'arresto dei servizi richiede più tempo, aumentare il valore di timeout.

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

Assembly di avvio

Determina l'assembly per la ricerca della classe Startup.

Chiave: startupAssembly
Tipo: string
Impostazione predefinita: assembly dell'app
Impostare usando: UseStartup
Variabile di ambiente: ASPNETCORE_STARTUPASSEMBLY

È possibile fare riferimento all'assembly per nome (string) o per tipo (TStartup). Se vengono chiamati più metodi UseStartup, l'ultimo metodo ha la precedenza.

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

Radice Web

Imposta il percorso relativo degli asset statici dell'app.

Chiave: webroot
Tipo: string
Impostazione predefinita: il valore predefinito è wwwroot. Il percorso di {content root}/wwwroot deve esistere. Se il percorso non esiste, viene usato un provider di file no-op.
Impostare usando: UseWebRoot
Variabile di ambiente: ASPNETCORE_WEBROOT

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

Per altre informazioni, vedi:

Override della configurazione

Usare la Configurazione per configurare l'host Web. Nell'esempio seguente, la configurazione host viene specificata facoltativamente in un hostsettings.json file. Qualsiasi configurazione caricata dal hostsettings.json file può essere sottoposta a override dagli argomenti della riga di comando. La configurazione compilata (in config) viene usata per configurare l'host con UseConfiguration. IWebHostBuilder la configurazione viene aggiunta alla configurazione dell'app, ma il contrario non è true,ConfigureAppConfiguration non influisce sulla IWebHostBuilder configurazione.

Override della configurazione fornita da UseUrls con hostsettings.json config first, command-line argument config second:

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

Nota

UseConfiguration copia solo le chiavi dall'elemento IConfiguration specificato nella configurazione del generatore di host. Pertanto, l'impostazione di reloadOnChange: true per i file JSON, INI e XML non ha alcun effetto.

Per specificare l'host eseguito in un URL specifico, il valore desiderato può essere passato da un prompt dei comandi durante l'esecuzione di dotnet run. L'argomento della riga di comando esegue l'override del urls valore del hostsettings.json file e il server è in ascolto sulla porta 8080:

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

Gestire l'host

Run

Il metodo Run avvia l'app Web e blocca il thread di chiamata fino all'arresto dell'host:

host.Run();

Avviare

Eseguire l'host in modo non bloccante chiamandone il metodo Start:

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

Se viene passato un elenco di URL al metodo Start, viene eseguito l'ascolto sugli URL specificati:

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

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

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

L'app può inizializzare e avviare un nuovo host usando i valori predefiniti preconfigurati di CreateDefaultBuilder con un metodo pratico statico. Questi metodi avviano il server senza output della console e attendono WaitForShutdown un'interruzione (CTRL-C/SIGINT o SIGTERM):

Start(RequestDelegate app)

Start con RequestDelegate:

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

Effettuare una richiesta nel browser per http://localhost:5000 ricevere la risposta "Hello World!" WaitForShutdown blocca fino a quando non viene eseguita un'interruzione (CTRL-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

Start(string url, RequestDelegate app)

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

Produce lo stesso risultato di Start(app RequestDelegate), ad eccezione del fatto che l'app risponde su http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Usare un'istanza di IRouteBuilder (Microsoft.AspNetCore.Routing) per usare il middleware di routing:

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

Usare le richieste del browser seguenti con l'esempio:

Richiedi Risposta
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Genera un'eccezione con la stringa "ooops!"
http://localhost:5000/throw Genera un'eccezione con la stringa "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown rimane bloccato fino a quando non viene eseguita un'interruzione (Ctrl-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

Start(string url, Action<IRouteBuilder> routeBuilder)

Usare un URL e un'istanza di 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();
}

Produce lo stesso risultato di Start(Action<IRouteBuilder> routeBuilder), ad eccezione del fatto che l'app risponde in http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Specificare un delegato per configurare 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();
}

Effettuare una richiesta nel browser per http://localhost:5000 ricevere la risposta "Hello World!" WaitForShutdown blocca fino a quando non viene eseguita un'interruzione (CTRL-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

StartWith(string url, Action<IApplicationBuilder> app)

Specificare un URL e un delegato per configurare 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();
}

Produce lo stesso risultato di StartWith(Action<IApplicationBuilder> app), ad eccezione del fatto che l'app risponde su http://localhost:8080.

Interfaccia IWebHostEnvironment

L'interfaccia IWebHostEnvironment fornisce informazioni sull'ambiente di hosting Web dell'app. Usare l'inserimento di un costruttore per ottenere IWebHostEnvironment per poterne usare le proprietà e i metodi di estensione:

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

È possibile usare un approccio basato su convenzione per configurare l'app all'avvio in base all'ambiente. In alternativa, inserire IWebHostEnvironment nel costruttore Startup per l'utilizzo in 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;
    }
}

Nota

Oltre al metodo di estensione IsDevelopment, IWebHostEnvironment offre i metodi IsStaging, IsProduction e IsEnvironment(string environmentName). Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

Il servizio IWebHostEnvironment può anche essere inserito direttamente nel metodo Configure per configurare la pipeline di elaborazione:

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 può essere inserito nel metodo Invoke durante la creazione di middleware personalizzato:

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

Interfaccia IHostApplicationLifetime

IHostApplicationLifetime consente attività successive all'avvio e all'arresto. Tre proprietà nell'interfaccia sono token di annullamento usati per registrare i metodi Action che definiscono gli eventi di avvio e arresto.

Token di annullamento Attivato quando...
ApplicationStarted L'host è stato completamente avviato.
ApplicationStopped L'host sta completando un arresto normale. Tutte le richieste devono essere elaborate. L'arresto è bloccato fino al completamento di questo evento.
ApplicationStopping L'host sta eseguendo un arresto normale. È possibile che le richieste siano ancora in esecuzione. L'arresto è bloccato fino al completamento di questo evento.
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 richiede la chiusura dell'applicazione corrente. La classe seguente usa StopApplication per arrestare normalmente un'app quando viene chiamato il metodo Shutdown della classe:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Convalida dell'ambito

CreateDefaultBuilder imposta su ServiceProviderOptions.ValidateScopes true se l'ambiente dell'app è Sviluppo.

Quando ValidateScopes è impostato su true, il provider di servizi predefinito esegue dei controlli per verificare che:

  • I servizi con ambito non vengano risolti direttamente o indirettamente dal provider di servizi radice.
  • I servizi con ambito non vengano inseriti direttamente o indirettamente in singleton.

Il provider di servizi radice venga creato con la chiamata di BuildServiceProvider. La durata del provider di servizi radice corrisponde alla durata dell'app/server quando il provider viene avviato con l'app e viene eliminato alla chiusura dell'app.

I servizi con ambito vengono eliminati dal contenitore che li ha creati. Se un servizio con ambito viene creato nel contenitore radice, la durata del servizio viene di fatto convertita in singleton, perché il servizio viene eliminato solo dal contenitore radice alla chiusura dell'app/server. La convalida degli ambiti servizio rileva queste situazioni nel contesto della chiamata di BuildServiceProvider.

Per convalidare sempre gli ambiti, incluso nell'ambiente di produzione, configurare ServiceProviderOptions con UseDefaultServiceProvider nel generatore host:

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

Risorse aggiuntive

Le app ASP.NET Core configurano e avviano un host. L'host è responsabile della gestione dell'avvio e della durata delle app. L'host configura almeno un server e una pipeline di elaborazione delle richieste. L'host può anche configurare la registrazione, l'inserimento delle dipendenze e la configurazione.

Questo articolo descrive l'host Web, che rimane disponibile solo per compatibilità con le versioni precedenti. I modelli di ASP.NET Core creano un host generico .NET, consigliato per tutti i tipi di app.

Configurare un host

Creare un host usando un'istanza di IWebHostBuilder. Questa operazione viene in genere eseguita nel punto di ingresso dell'app, il metodo Main.

Nei modelli Main di progetto si trova in Program.cs. Una tipica chiamata CreateDefaultBuilder dell'app per avviare la configurazione di un 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>();
}

Il codice che chiama CreateDefaultBuilder è incluso in un metodo denominato CreateWebHostBuilder, che lo separa dal codice in Main che chiama Run per l'oggetto generatore. Questa separazione è necessaria se si usano gli strumenti di Entity Framework Core. Gli strumenti si aspettano di trovare un metodo CreateWebHostBuilder che possono chiamare in fase di progettazione per configurare l'host senza eseguire l'app. Un'alternativa consiste nell'implementare IDesignTimeDbContextFactory. Per altre informazioni, vedere Creazione DbContext in fase di progettazione.

CreateDefaultBuilder esegue queste attività:

La configurazione definita da CreateDefaultBuilder può essere sottoposta a override e aumentata da ConfigureAppConfiguration, ConfigureLogginge altri metodi e metodi di estensione di IWebHostBuilder. Di seguito sono riportati alcuni esempi:

  • ConfigureAppConfiguration viene usato per specificare ulteriori IConfiguration informazioni per l'app. La chiamata seguente ConfigureAppConfiguration aggiunge un delegato per includere la appsettings.xml configurazione dell'app nel file. ConfigureAppConfiguration può essere chiamato più volte. Si noti che questa configurazione non è valida per l'host (ad esempio, gli URL del server o l'ambiente). Vedere la sezione Valori di configurazione dell'host.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • La chiamata seguente ConfigureLogging aggiunge un delegato per configurare il livello di registrazione minimo (SetMinimumLevel) a LogLevel.Warning. Questa impostazione sostituisce le impostazioni in appsettings.Development.json () e appsettings.Production.json (LogLevel.Error) configurate da CreateDefaultBuilderLogLevel.Debug. ConfigureLogging può essere chiamato più volte.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • La chiamata seguente per ConfigureKestrel eseguire l'override del valore predefinito Limits.MaxRequestBodySize di 30.000.000 byte stabilito quando Kestrel è stato configurato da CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

La radice del contenuto determina la posizione in cui l'host cerca i file dei contenuti, ad esempio i file di visualizzazione MVC. Quando l'app viene avviata dalla cartella radice del progetto, la cartella radice del progetto viene usata come radice del contenuto. Si tratta dell'impostazione predefinita usata in Visual Studio e nei nuovi modelli dotnet.

Per altre informazioni sulla configurazione delle app, vedere Configurazione in ASP.NET Core.

Nota

In alternativa all'uso del metodo statico CreateDefaultBuilder , la creazione di un host da WebHostBuilder è un approccio supportato con ASP.NET Core 2.x.

Quando si configura un host, Configure è possibile specificare i metodi e ConfigureServices . Se viene specificata una classe Startup, la classe deve definire un metodo Configure. Per altre informazioni, vedere Avvio delle app in ASP.NET Core. Se vengono effettuate più chiamate a ConfigureServices, le chiamate vengono aggiunte l'una all'altra. Più chiamate a Configure o UseStartup in WebHostBuilder sostituiscono le impostazioni precedenti.

Valori di configurazione dell'host

WebHostBuilder si basa sugli approcci seguenti per impostare i valori di configurazione host:

  • Configurazione del generatore di host, che include le variabili di ambiente nel formato ASPNETCORE_{configurationKey}. Ad esempio: ASPNETCORE_ENVIRONMENT.
  • Estensioni come UseContentRoot e UseConfiguration (vedere la sezione Eseguire l'override della configurazione ).
  • UseSetting e la chiave associata. Quando si imposta un valore con UseSetting, il valore viene impostato come stringa indipendentemente dal tipo.

L'host usa l'ultima opzione che imposta un valore. Per altre informazioni, vedere Override della configurazione nella prossima sezione.

Chiave applicazione (nome)

La IWebHostEnvironment.ApplicationName proprietà viene impostata automaticamente quando UseStartup o Configure viene chiamato durante la costruzione dell'host. Il valore viene impostato sul nome dell'assembly contenente il punto di ingresso dell'app. Per impostare il valore in modo esplicito, usare :WebHostDefaults.ApplicationKey

Chiave: applicationName
Tipo: string
Impostazione predefinita: il nome dell'assembly contenente il punto di ingresso dell'app.
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_APPLICATIONNAME

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

Acquisizione degli errori di avvio

Questa impostazione controlla l'acquisizione degli errori di avvio.

Chiave: captureStartupErrors
Tipo: bool (true o 1)
Impostazione predefinita: l'impostazione predefinita è false a meno che l'app non venga eseguita con Kestrel IIS, dove il valore predefinito è true.
Impostare usando: CaptureStartupErrors
Variabile di ambiente: ASPNETCORE_CAPTURESTARTUPERRORS

Quando è false, gli errori durante l'avvio causano la chiusura dell'host. Quando è true, l'host acquisisce le eccezioni durante l'avvio e tenta di avviare il server.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Radice del contenuto

Questa impostazione determina dove ASP.NET Core inizia la ricerca di file di contenuto.

Chiave: contentRoot
Tipo: string
Impostazione predefinita: il valore predefinito corrisponde alla cartella contenente l'assembly dell'app.
Impostare usando: UseContentRoot
Variabile di ambiente: ASPNETCORE_CONTENTROOT

La radice del contenuto viene usata anche come percorso di base per la radice Web. Se il percorso radice del contenuto non esiste, l'host non viene avviato.

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

Per altre informazioni, vedi:

Errori dettagliati

Determina l'acquisizione degli errori dettagliati.

Chiave: detailedErrors
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_DETAILEDERRORS

Quando è abilitata (o quando l'ambiente è impostato su Development), l'app acquisisce le eccezioni dettagliate.

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

Ambiente

Imposta l'ambiente per l'app.

Chiave: environment
Tipo: string
Impostazione predefinita: Production
Impostare usando: UseEnvironment
Variabile di ambiente: ASPNETCORE_ENVIRONMENT

L'ambiente può essere impostato su qualsiasi valore. I valori definiti dal framework includono Development, Staging e Production. Nei valori non viene fatta distinzione tra maiuscole e minuscole. Per impostazione predefinita, l'ambiente viene letto dalla variabile di ambiente ASPNETCORE_ENVIRONMENT. Quando si usa Visual Studio, le variabili di ambiente possono essere impostate nel launchSettings.json file. Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

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

Assembly di avvio dell'hosting

Imposta gli assembly di avvio dell'hosting dell'app.

Chiave: hostingStartupAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da caricare all'avvio.

Sebbene il valore di configurazione predefinito sia una stringa vuota, gli assembly di avvio dell'hosting includono sempre l'assembly dell'app. Quando vengono specificati, gli assembly di avvio dell'hosting vengono aggiunti all'assembly dell'app per essere caricati quando l'app compila i servizi comuni durante l'avvio.

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

Porta HTTPS

Impostare la porta di reindirizzamento HTTPS. Usata per imporre HTTPS.

Chiave: https_port
Tipo: string
Impostazione predefinita: un valore predefinito non è impostato.
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HTTPS_PORTS

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

Assembly di avvio dell'hosting da escludere

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da escludere all'avvio.

Chiave: hostingStartupExcludeAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Preferire gli URL di hosting

Indica se l'host deve eseguire l'ascolto sugli URL configurati con WebHostBuilder anziché su quelli configurati con l'implementazione IServer.

Chiave: preferHostingUrls
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: PreferHostingUrls
Variabile di ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Impedire l'avvio dell'hosting

Impedisce il caricamento automatico degli assembly di avvio dell'hosting, inclusi gli assembly di avvio dell'hosting configurati dall'assembly dell'app. Per altre informazioni, vedere Usare assembly di avvio dell'hosting in ASP.NET Core.

Chiave: preventHostingStartup
Tipo: bool (true o 1)
Impostazione predefinita: false
Impostare usando: UseSetting
Variabile di ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

URL del server

Indica gli indirizzi IP o gli indirizzi host con le porte e protocolli su cui il server deve eseguire l'ascolto per le richieste.

Chiave: urls
Tipo: string
Predefinito: http://localhost:5000
Impostare usando: UseUrls
Variabile di ambiente: ASPNETCORE_URLS

Impostare su un elenco di prefissi URL separati da punto e virgola (;) ai quali il server deve rispondere. Ad esempio: http://localhost:123. Usare "*" per indicare che il server deve restare in ascolto delle richieste su qualsiasi indirizzo IP o nome host usando la porta e il protocollo specificati , ad esempio http://*:5000. Il protocollo (http:// o https://) deve essere incluso con ogni URL. I formati supportati variano a seconda del server.

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

Kestrel ha una propria API di configurazione dell'endpoint. Per altre informazioni, vedere Kestrel Server Web in ASP.NET Core.

Timeout di arresto

Specifica il tempo di attesa per l'arresto dell'host Web.

Chiave: shutdownTimeoutSeconds
Tipo: int
Impostazione predefinita: 5
Impostare usando: UseShutdownTimeout
Variabile di ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Sebbene la chiave accetti int con UseSetting (ad esempio, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), il metodo di estensione UseShutdownTimeout accetta TimeSpan.

Durante il periodo di timeout, l'hosting:

Se il periodo di timeout scade prima che siano stati arrestati tutti i servizi ospitati, gli eventuali servizi attivi rimanenti vengono interrotti quando l'app viene arrestata. I servizi si arrestano anche se non hanno completato l'elaborazione. Se l'arresto dei servizi richiede più tempo, aumentare il valore di timeout.

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

Assembly di avvio

Determina l'assembly per la ricerca della classe Startup.

Chiave: startupAssembly
Tipo: string
Impostazione predefinita: assembly dell'app
Impostare usando: UseStartup
Variabile di ambiente: ASPNETCORE_STARTUPASSEMBLY

È possibile fare riferimento all'assembly per nome (string) o per tipo (TStartup). Se vengono chiamati più metodi UseStartup, l'ultimo metodo ha la precedenza.

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

Radice Web

Imposta il percorso relativo degli asset statici dell'app.

Chiave: webroot
Tipo: string
Impostazione predefinita: il valore predefinito è wwwroot. Il percorso di {content root}/wwwroot deve esistere. Se il percorso non esiste, viene usato un provider di file no-op.
Impostare usando: UseWebRoot
Variabile di ambiente: ASPNETCORE_WEBROOT

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

Per altre informazioni, vedi:

Override della configurazione

Usare la Configurazione per configurare l'host Web. Nell'esempio seguente, la configurazione host viene specificata facoltativamente in un hostsettings.json file. Qualsiasi configurazione caricata dal hostsettings.json file può essere sottoposta a override dagli argomenti della riga di comando. La configurazione compilata (in config) viene usata per configurare l'host con UseConfiguration. IWebHostBuilder la configurazione viene aggiunta alla configurazione dell'app, ma il contrario non è true,ConfigureAppConfiguration non influisce sulla IWebHostBuilder configurazione.

Override della configurazione fornita da UseUrls con hostsettings.json config first, command-line argument config second:

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

Nota

UseConfiguration copia solo le chiavi dall'elemento IConfiguration specificato nella configurazione del generatore di host. Pertanto, l'impostazione di reloadOnChange: true per i file JSON, INI e XML non ha alcun effetto.

Per specificare l'host eseguito in un URL specifico, il valore desiderato può essere passato da un prompt dei comandi durante l'esecuzione di dotnet run. L'argomento della riga di comando esegue l'override del urls valore del hostsettings.json file e il server è in ascolto sulla porta 8080:

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

Gestire l'host

Run

Il metodo Run avvia l'app Web e blocca il thread di chiamata fino all'arresto dell'host:

host.Run();

Avviare

Eseguire l'host in modo non bloccante chiamandone il metodo Start:

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

Se viene passato un elenco di URL al metodo Start, viene eseguito l'ascolto sugli URL specificati:

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

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

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

L'app può inizializzare e avviare un nuovo host usando i valori predefiniti preconfigurati di CreateDefaultBuilder con un metodo pratico statico. Questi metodi avviano il server senza output della console e attendono WaitForShutdown un'interruzione (CTRL-C/SIGINT o SIGTERM):

Start(RequestDelegate app)

Start con RequestDelegate:

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

Effettuare una richiesta nel browser per http://localhost:5000 ricevere la risposta "Hello World!" WaitForShutdown blocca fino a quando non viene eseguita un'interruzione (CTRL-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

Start(string url, RequestDelegate app)

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

Produce lo stesso risultato di Start(app RequestDelegate), ad eccezione del fatto che l'app risponde su http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Usare un'istanza di IRouteBuilder (Microsoft.AspNetCore.Routing) per usare il middleware di routing:

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

Usare le richieste del browser seguenti con l'esempio:

Richiedi Risposta
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Genera un'eccezione con la stringa "ooops!"
http://localhost:5000/throw Genera un'eccezione con la stringa "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown rimane bloccato fino a quando non viene eseguita un'interruzione (Ctrl-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

Start(string url, Action<IRouteBuilder> routeBuilder)

Usare un URL e un'istanza di 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();
}

Produce lo stesso risultato di Start(Action<IRouteBuilder> routeBuilder), ad eccezione del fatto che l'app risponde in http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Specificare un delegato per configurare 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();
}

Effettuare una richiesta nel browser per http://localhost:5000 ricevere la risposta "Hello World!" WaitForShutdown blocca fino a quando non viene eseguita un'interruzione (CTRL-C/SIGINT o SIGTERM). L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.

StartWith(string url, Action<IApplicationBuilder> app)

Specificare un URL e un delegato per configurare 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();
}

Produce lo stesso risultato di StartWith(Action<IApplicationBuilder> app), ad eccezione del fatto che l'app risponde su http://localhost:8080.

Interfaccia IWebHostEnvironment

L'interfaccia IWebHostEnvironment fornisce informazioni sull'ambiente di hosting Web dell'app. Usare l'inserimento di un costruttore per ottenere IWebHostEnvironment per poterne usare le proprietà e i metodi di estensione:

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

È possibile usare un approccio basato su convenzione per configurare l'app all'avvio in base all'ambiente. In alternativa, inserire IWebHostEnvironment nel costruttore Startup per l'utilizzo in 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;
    }
}

Nota

Oltre al metodo di estensione IsDevelopment, IWebHostEnvironment offre i metodi IsStaging, IsProduction e IsEnvironment(string environmentName). Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

Il servizio IWebHostEnvironment può anche essere inserito direttamente nel metodo Configure per configurare la pipeline di elaborazione:

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 può essere inserito nel metodo Invoke durante la creazione di middleware personalizzato:

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

Interfaccia IHostApplicationLifetime

IHostApplicationLifetime consente attività successive all'avvio e all'arresto. Tre proprietà nell'interfaccia sono token di annullamento usati per registrare i metodi Action che definiscono gli eventi di avvio e arresto.

Token di annullamento Attivato quando...
ApplicationStarted L'host è stato completamente avviato.
ApplicationStopped L'host sta completando un arresto normale. Tutte le richieste devono essere elaborate. L'arresto è bloccato fino al completamento di questo evento.
ApplicationStopping L'host sta eseguendo un arresto normale. È possibile che le richieste siano ancora in esecuzione. L'arresto è bloccato fino al completamento di questo evento.
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 richiede la chiusura dell'applicazione corrente. La classe seguente usa StopApplication per arrestare normalmente un'app quando viene chiamato il metodo Shutdown della classe:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Convalida dell'ambito

CreateDefaultBuilder imposta su ServiceProviderOptions.ValidateScopes true se l'ambiente dell'app è Sviluppo.

Quando ValidateScopes è impostato su true, il provider di servizi predefinito esegue dei controlli per verificare che:

  • I servizi con ambito non vengano risolti direttamente o indirettamente dal provider di servizi radice.
  • I servizi con ambito non vengano inseriti direttamente o indirettamente in singleton.

Il provider di servizi radice venga creato con la chiamata di BuildServiceProvider. La durata del provider di servizi radice corrisponde alla durata dell'app/server quando il provider viene avviato con l'app e viene eliminato alla chiusura dell'app.

I servizi con ambito vengono eliminati dal contenitore che li ha creati. Se un servizio con ambito viene creato nel contenitore radice, la durata del servizio viene di fatto convertita in singleton, perché il servizio viene eliminato solo dal contenitore radice alla chiusura dell'app/server. La convalida degli ambiti servizio rileva queste situazioni nel contesto della chiamata di BuildServiceProvider.

Per convalidare sempre gli ambiti, incluso nell'ambiente di produzione, configurare ServiceProviderOptions con UseDefaultServiceProvider nel generatore host:

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

Risorse aggiuntive