ASP.NET Core-webhost

ASP.NET Core-apps een host configureren en starten. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. De host configureert minimaal een server en een aanvraagverwerkingspijplijn. De host kan ook logboekregistratie, afhankelijkheidsinjectie en configuratie instellen.

Dit artikel bevat informatie over de webhost, die alleen beschikbaar blijft voor compatibiliteit met eerdere versies. De ASP.NET Core-sjablonen maken een WebApplicationBuilder en WebApplication, die wordt aanbevolen voor web-apps. Zie WebApplicationBuilder voor meer informatie over WebApplication en

Een host instellen

Maak een host met behulp van een exemplaar van IWebHostBuilder. Dit wordt meestal uitgevoerd in het toegangspunt van de app, de Main methode in Program.cs. Een typische app roept CreateDefaultBuilder aan om een host op te zetten.

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

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

De code die CreateDefaultBuilder aanroept, bevindt zich in een methode met de naam CreateWebHostBuilder, die deze scheidt van de code in Main die Run aanroept op het opbouwobject. Deze scheiding is vereist als u Entity Framework Core-hulpprogramma's gebruikt. De hulpprogramma's verwachten een CreateWebHostBuilder methode te vinden die ze tijdens het ontwerp kunnen aanroepen om de host te configureren zonder de app uit te voeren. Een alternatief is om te implementeren IDesignTimeDbContextFactory. Zie Ontwerptijd dbContext Makenvoor meer informatie.

CreateDefaultBuilder voert de volgende taken uit:

• Configureert Kestrel als de webserver met behulp van de hostingconfiguratieproviders van de app. Zie voor de standaardopties van de Kestrel-server Opties configureren voor de ASP.NET Core Kestrel webserver.
• Stelt de root van de inhoud in op het pad dat door Directory.GetCurrentDirectorywordt geretourneerd.
• Hostconfiguratie wordt geladen van:
  • Omgevingsvariabelen voorafgegaan door ASPNETCORE_ (bijvoorbeeld ASPNETCORE_ENVIRONMENT).
  • Opdrachtregelargumenten.
• Laadt de app-configuratie in de volgende volgorde van:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Gebruikersgeheimen wanneer de app wordt uitgevoerd in de Development omgeving met behulp van de invoerassembly.
  • Omgevingsvariabelen.
  • Opdrachtregelargumenten.
• Hiermee configureer je logging voor console- en foutopsporingsuitvoer. Logboekregistratie bevat regels voor logboekfilters die zijn opgegeven in een sectie logboekconfiguratie van een appsettings.json of appsettings.{Environment}.json bestand.
• Wanneer u achter IIS met de ASP.NET Core Module werkt, CreateDefaultBuilder schakelt u IIS-integratie in, waarmee het basisadres en de poort van de app worden geconfigureerd. IIS-integratie configureert ook de app om opstartfouten vast te leggen. Zie Host ASP.NET Core in Windows met IIS-voor de standaardopties van IIS.
• Stel ServiceProviderOptions.ValidateScopes in op true als de omgeving van de app Ontwikkeling is. Zie Bereikvalidatie voor meer informatie.

De configuratie die is gedefinieerd door CreateDefaultBuilder kan worden overschreven en uitgebreid door ConfigureAppConfiguration, ConfigureLoggingen andere methoden en uitbreidingsmethoden van IWebHostBuilder. Hier volgen enkele voorbeelden:

• ConfigureAppConfiguration wordt gebruikt om aanvullende IConfiguration voor de app op te geven. Met de volgende ConfigureAppConfiguration aanroep wordt een gemachtigde toegevoegd om app-configuratie in het appsettings.xml bestand op te nemen. ConfigureAppConfiguration kan meerdere keren worden aangeroepen. Houd er rekening mee dat deze configuratie niet van toepassing is op de host (bijvoorbeeld server-URL's of omgeving). Zie de sectie Hostconfiguratiewaarden .

  WebHost.CreateDefaultBuilder(args)
      .ConfigureAppConfiguration((hostingContext, config) =>
      {
          config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
      })
      ...
  

• Met de volgende ConfigureLogging aanroep wordt een gemachtigde toegevoegd om het minimale logboekregistratieniveau (SetMinimumLevel) aan te LogLevel.Warningconfigureren. Deze instelling overschrijft de instellingen in appsettings.Development.json (LogLevel.Debug) en appsettings.Production.json (LogLevel.Error) die zijn geconfigureerd door CreateDefaultBuilder. ConfigureLogging kan meerdere keren worden aangeroepen.

  WebHost.CreateDefaultBuilder(args)
      .ConfigureLogging(logging => 
      {
          logging.SetMinimumLevel(LogLevel.Warning);
      })
      ...
  

• De volgende aanroep van ConfigureKestrel overschrijft de standaard Limits.MaxRequestBodySize van 30.000.000 bytes, die is ingesteld toen Kestrel door CreateDefaultBuilder werd geconfigureerd:

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

De hoofdmap van de inhoud bepaalt waar de host zoekt naar inhoudsbestanden, zoals MVC-weergavebestanden. Wanneer de app wordt gestart vanuit de hoofdmap van het project, wordt deze gebruikt als de rootmap van de content. Dit is de standaardinstelling die wordt gebruikt in Visual Studio en de nieuwe dotnet-sjablonen.

Zie Configuratie in ASP.NET Core voor meer informatie over app-configuratie.

Bij het instellen van een host kunnen de methoden Configure en ConfigureServices worden opgegeven. Als een Startup klasse is opgegeven, moet deze een Configure methode definiëren. Zie App opstarten in ASP.NET Core voor meer informatie. Meerdere oproepen naar ConfigureServices worden aan elkaar gekoppeld. Meerdere aanroepen van Configure of UseStartup op de WebHostBuilder overschrijven de vorige instellingen.

Hostconfiguratiewaarden

WebHostBuilder is afhankelijk van de volgende methoden om de hostconfiguratiewaarden in te stellen:

• Host builder-configuratie, die omgevingsvariabelen met de indeling ASPNETCORE_{configurationKey}bevat. Bijvoorbeeld: ASPNETCORE_ENVIRONMENT.
• Extensies zoals UseContentRoot en UseConfiguration (zie de sectie Configuratie overschrijven ).
• UseSetting en de bijbehorende sleutel. Wanneer u een waarde instelt, UseSettingwordt de waarde ingesteld als een tekenreeks, ongeacht het type.

De host gebruikt de optie waarmee een waarde voor het laatst wordt ingesteld. Zie Overschrijfconfiguratie in de volgende sectie voor meer informatie.

Toepassingssleutel (naam)

De IWebHostEnvironment.ApplicationName eigenschap wordt automatisch ingesteld wanneer UseStartup of Configure wordt aangeroepen tijdens de bouw van de host. De waarde wordt toegewezen aan de naam van de assembly die het toegangspunt van de app bevat. Als u de waarde expliciet wilt instellen, gebruikt u het WebHostDefaults.ApplicationKeyvolgende:

Sleutel: applicatienaam
Type: tekenreeks
Standaard: de naam van de assembly die het toegangspunt van de app bevat.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_APPLICATIONNAME

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

Opstartfouten vastleggen

Deze instelling bepaalt de opname van opstartfouten.

Sleutel: captureStartupErrors
Type: bool (true of 1)
standaard: wordt standaard ingesteld op false, tenzij de app wordt uitgevoerd met Kestrel achter IIS, waarbij de standaardwaarde is true.
Instellen met behulp van: CaptureStartupErrors
omgevingsvariabele: ASPNETCORE_CAPTURESTARTUPERRORS

Wanneer false, leiden fouten tijdens het opstarten ertoe dat de host stopt. Wanneer true, legt de host uitzonderingen vast tijdens het opstarten en probeert de server te starten.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Inhoudsroot

Deze instelling bepaalt waar ASP.NET Core begint met het zoeken naar inhoudsbestanden.

Sleutel: contentRoot
Type: tekenreeks
Standaard: wordt standaard ingesteld op de map waarin de app-assembly zich bevindt.
Instellen met behulp van: UseContentRoot
omgevingsvariabele: ASPNETCORE_CONTENTROOT

De hoofdmap van de inhoud wordt ook gebruikt als het basispad voor de webroot. Als het hoofdpad van de inhoud niet bestaat, kan de host niet worden gestart.

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

Voor meer informatie, zie:

• Basisbeginselen: inhoudsmap
• Webroot

Gedetailleerde fouten

Bepaalt of gedetailleerde fouten moeten worden vastgelegd.

Sleutel: gedetailleerdeFouten
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_DETAILEDERRORS

Wanneer deze optie is ingeschakeld (of als de omgeving is ingesteld op Development), legt de app gedetailleerde uitzonderingen vast.

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

Milieu

Hiermee stelt u de omgeving van de app in.

Sleutelwoord: omgeving
Type: tekenreeks
Standaard: Productie
Instellen met behulp van: UseEnvironment
omgevingsvariabele: ASPNETCORE_ENVIRONMENT

De omgeving kan worden ingesteld op elke waarde. Framework-gedefinieerde waarden omvatten Development, Stagingen Production. Waarden zijn niet hoofdlettergevoelig. De omgeving wordt standaard gelezen uit de ASPNETCORE_ENVIRONMENT omgevingsvariabele. Wanneer u Visual Studio gebruikt, kunnen omgevingsvariabelen worden ingesteld in het launchSettings.json bestand. Zie ASP.NET Core runtime-omgevingen voor meer informatie.

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

Het organiseren van start-up bijeenkomsten

Hiermee stelt u de hosting opstartassemblages van de app in.

Sleutel: hostingStartupAssemblies
Type: tekenreeks
standaard: lege tekenreeks
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's om te laden bij het opstarten.

Hoewel de configuratiewaarde standaard is ingesteld op een lege tekenreeks, bevatten de hosting-opstartassembly's altijd de assembly van de app. Wanneer opstartassembly's worden gehost, worden ze toegevoegd aan de assembly van de app voor het laden wanneer de app zijn algemene services opbouwt tijdens het opstarten.

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

HTTPS-poort

Stel de HTTPS-poort in waarnaar moet worden omgeleid als u een niet-HTTPS-verbinding krijgt. Gebruikt in om HTTPSaf te dwingen. Deze instelling zorgt er niet voor dat de server luistert op de opgegeven poort. Dat wil gezegd, het is mogelijk om aanvragen per ongeluk om te leiden naar een ongebruikte poort.

Sleutel: https_port
Type: tekenreeks
Standaard: er is geen standaardwaarde ingesteld.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HTTPS_PORT

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

HTTPS-poorten

Stel de poorten in om te luisteren naar HTTPS-verbindingen.

Sleutel: https_ports type: tekenreeks
Standaard: er is geen standaardwaarde ingesteld.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HTTPS_PORTS

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

HTTP-poorten

Stel de poorten in waarop moet worden geluisterd naar HTTP-verbindingen.

Sleutel: http_ports type: tekenreeks
Standaard: er is geen standaardwaarde ingesteld.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HTTP_PORTS

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

Assemblies uitsluiten tijdens het opstarten van de hosting

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's die moeten worden uitgesloten bij het opstarten.

Sleutel: hostingStartupExcludeAssemblies
Type: tekenreeks
standaard: lege tekenreeks
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Geef de voorkeur aan hosting-URLs

Geeft aan of de host moet luisteren naar de URL's die zijn geconfigureerd met de WebHostBuilder in plaats van de URL's die zijn geconfigureerd met de IServer implementatie.

Sleutel: preferHostingUrls
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: PreferHostingUrls
omgevingsvariabele: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Opstarten van hosting voorkomen

Voorkomt het automatisch laden van opstartassembly's, waaronder het hosten van opstartassembly's die zijn geconfigureerd door de assembly van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Sleutel: preventHostingStartup
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Server-URL's

Geeft de IP-adressen of hostadressen aan met poorten en protocollen waarop de server moet luisteren naar aanvragen.

Sleutel: URL's
Type: tekenreeks
Standaard: http://localhost:5000
Instellen met behulp van: UseUrls
omgevingsvariabele: ASPNETCORE_URLS

Ingesteld op een door puntkomma's gescheiden (;) lijst met URL-voorvoegsels waarop de server moet reageren. Bijvoorbeeld: http://localhost:123. Gebruik *om aan te geven dat de server moet luisteren naar aanvragen op een IP-adres of hostnaam met behulp van de opgegeven poort en het opgegeven protocol (bijvoorbeeld http://*:5000). Het protocol (http:// of https://) moet worden opgenomen in elke URL. Ondersteunde indelingen verschillen per server.

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

Kestrel heeft een eigen eindpuntconfiguratie-API. Zie Eindpunten configureren voor de ASP.NET Core Kestrel webservervoor meer informatie.

Time-out afsluiten

Hiermee geeft u de hoeveelheid tijd die moet worden gewacht totdat de webhost wordt afgesloten.

Sleutel: afsluitTimeoutSeconden
Type: int
Standaard: 5
Instellen met behulp van: UseShutdownTimeout
omgevingsvariabele: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Hoewel de sleutel een int accepteert met UseSetting (bijvoorbeeld .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), neemt de UseShutdownTimeout extensiemethode een TimeSpan.

Tijdens de time-outperiode hosten:

• Triggers IApplicationLifetime.ApplicationStopping.
• Pogingen om gehoste services te stoppen, waarbij eventuele fouten worden geregistreerd voor services die niet kunnen worden gestopt.

Als de time-outperiode verloopt voordat alle gehoste services stoppen, worden alle resterende actieve services gestopt wanneer de app wordt afgesloten. De services stoppen zelfs als ze de verwerking nog niet hebben voltooid. Als voor services extra tijd nodig is om te stoppen, verhoogt u de time-out.

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

Startupbijeenkomst

Bepaalt in welke assembly gezocht moet worden naar de Startup klasse.

Sleutel: startupAssembly
Type: tekenreeks
Standaard: de samenstelling van de app
Instellen met behulp van: UseStartup
omgevingsvariabele: ASPNETCORE_STARTUPASSEMBLY

Er kan naar de assembly worden verwezen op naam (string) of type (TStartup). Als er meerdere UseStartup methoden worden aangeroepen, heeft de laatste prioriteit.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

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

webroot

Hiermee stelt u het relatieve pad in voor de statische elementen van de app.

Sleutel: webroot
Type: tekenreeks
standaard: de standaardwaarde is wwwroot. Het pad naar {content root}/wwwroot- moet bestaan. Als het pad niet bestaat, wordt er een no-op bestandsprovider gebruikt.
Instellen met behulp van: UseWebRoot
omgevingsvariabele: ASPNETCORE_WEBROOT

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

Voor meer informatie, zie:

• Basisprincipes: webrootmap
• Inhoudroot

Configuratie overschrijven

Gebruik Configuratie om de webhost te configureren. In het volgende voorbeeld wordt de hostconfiguratie optioneel opgegeven in een hostsettings.json bestand. Elke configuratie die vanuit het hostsettings.json bestand wordt geladen, kan worden overschreven door opdrachtregelargumenten. De ingebouwde configuratie (in config) wordt gebruikt voor het configureren van de host met UseConfiguration. IWebHostBuilder configuratie wordt toegevoegd aan de configuratie van de app, maar het omgekeerde geldt niet—ConfigureAppConfiguration heeft geen invloed op de IWebHostBuilder configuratie.

Het overschrijven van de configuratie geleverd door UseUrls met eerst hostsettings.json configuratie, en ten tweede de opdrachtregelargument configuratie.

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

Om de host uit te voeren op een specifieke URL, kan de gewenste waarde worden doorgegeven vanuit een opdrachtprompt bij het uitvoeren van dotnet run. Het opdrachtregelargument overschrijft de urls waarde van het hostsettings.json bestand en de server luistert op poort 8080:

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

De host beheren

Rennen

De Run methode start de web-app en blokkeert de aanroepende thread totdat de host wordt afgesloten:

host.Run();

Begin

Voer de host op een niet-blokkerende manier uit door zijn methode Start aan te roepen.

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

Als een lijst met URL's wordt doorgegeven aan de Start methode, luistert deze naar de opgegeven URL's:

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

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

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

De app kan een nieuwe host initialiseren en starten met de vooraf geconfigureerde standaardwaarden van CreateDefaultBuilder met behulp van een statische gemaksfunctie. Met deze methoden start de server zonder console-uitvoer en met het wachten op een onderbreking (Ctrl-C/SIGINT of SIGTERM):

Start(RequestDelegate-app)

Begin met een RequestDelegate:

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

Doe een verzoek in de browser naar http://localhost:5000 om het antwoord 'Hallo wereld!' te ontvangen. WaitForShutdown blijft actief totdat er een onderbreking (met Ctrl-C/SIGINT of SIGTERM) wordt gegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

Start(tekenreeks-URL, RequestDelegate-app)

Begin met een URL en 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();
}

Produceert hetzelfde resultaat als Start(RequestDelegate app), behalve dat de app reageert op http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Gebruik een exemplaar van IRouteBuilder (Microsoft.AspNetCore.Routing) om middleware voor routering te gebruiken:

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

Gebruik de volgende browseraanvragen met het voorbeeld:

Aanvraag	Reactie
http://localhost:5000/hello/Martin	Hallo, Martin!
http://localhost:5000/buenosdias/Catrina	Buenos dias, Catrina!
http://localhost:5000/throw/ooops!	Genereert een uitzondering met tekenreeks 'ooops!'
http://localhost:5000/throw	Genereert een uitzondering met tekenreeks 'Uh oh!'
http://localhost:5000/Sante/Kevin	Sante, Kevin!
http://localhost:5000	Hallo mensen!

WaitForShutdown wordt geblokkeerd totdat een onderbreking (Ctrl-C/SIGINT of SIGTERM) wordt uitgegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

Start(String url, Action<IRouteBuilder> routeBuilder)

Gebruik een URL en een exemplaar van 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();
}

Produceert hetzelfde resultaat als Start(Action<IRouteBuilder routeBuilder> ), behalve dat de app reageert op http://localhost:8080.

StartWith(Action<IApplicationBuilder-app> )

Stel een gemachtigde in om een IApplicationBuilder te configureren.

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

Doe een verzoek in de browser naar http://localhost:5000 om het antwoord 'Hallo wereld!' te ontvangen. WaitForShutdown blijft actief totdat er een onderbreking (met Ctrl-C/SIGINT of SIGTERM) wordt gegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

StartWith(tekenreeks-URL, Action<IApplicationBuilder-app> )

Geef een URL en een afgevaardigde op om een IApplicationBuilder te configureren.

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

Produceert hetzelfde resultaat als StartWith(Action<IApplicationBuilder-app> ), behalve dat de app reageert op http://localhost:8080.

Interface IWebHostEnvironment

De IWebHostEnvironment interface biedt informatie over de webhostingomgeving van de app. Gebruik constructorinjectie om IWebHostEnvironment te verkrijgen en zijn eigenschappen en uitbreidingsmethoden te gebruiken:

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

Een op conventie gebaseerde benadering kan worden gebruikt om de app bij het opstarten te configureren op basis van de omgeving. U kunt ook de IWebHostEnvironment in de Startup constructor injecteren voor gebruik 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;
    }
}

De IWebHostEnvironment service kan ook rechtstreeks worden geïnjecteerd in de methode voor het Configure instellen van de verwerkingspijplijn:

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 kan worden geïnjecteerd in de Invoke methode bij het maken van aangepaste middleware:

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

    var contentRootPath = env.ContentRootPath;
}

Interface voor IHostApplicationLifetime

IHostApplicationLifetime maakt na het voltooien van opstarten en afsluiten activiteiten mogelijk. Drie eigenschappen op de interface zijn annuleringstokens die worden gebruikt om methoden te registreren Action waarmee opstart- en afsluitevenementen worden gedefinieerd.

Annuleringstoken	Geactiveerd wanneer...
ApplicationStarted	De host is volledig gestart.
ApplicationStopped	De host voltooit een zorgvuldige afsluiting. Alle aanvragen moeten worden verwerkt. Afsluiten blokkeert totdat deze gebeurtenis is voltooid.
ApplicationStopping	De host is bezig met een vlekkeloze afsluiting. Aanvragen kunnen nog steeds worden verwerkt. Afsluiten blokkeert totdat deze gebeurtenis is voltooid.

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 vraagt om beëindiging van de app. De volgende klasse gebruikt StopApplication om een app correct af te sluiten wanneer de methode van Shutdown de klasse wordt aangeroepen:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Bereikvalidatie

CreateDefaultBuilder stelt ServiceProviderOptions.ValidateScopes in op true als de omgeving van de app Ontwikkeling is.

Wanneer ValidateScopes is ingesteld op true, voert de standaardserviceprovider controles uit om te verifiëren dat:

• Scoped services worden niet direct of indirect opgelost vanuit de hoofdserviceprovider.
• Scoped services worden niet direct of indirect in singletons geïnjecteerd.

De hoofdserviceprovider wordt gemaakt wanneer BuildServiceProvider wordt aangeroepen. De levensduur van de hoofdserviceprovider komt overeen met de levensduur van de app/server wanneer de provider begint met de app en wordt verwijderd wanneer de app wordt afgesloten.

Scoped services worden verwijderd door de container die ze heeft gemaakt. Als een scoped service wordt gemaakt in de hoofdcontainer, wordt de levensduur van de service effectief gepromoveerd tot singleton omdat deze alleen wordt verwijderd door de hoofdcontainer wanneer de app/server wordt afgesloten. Bij het valideren van servicebereiken worden deze situaties onderschept wanneer BuildServiceProvider wordt aangeroepen.

Als u scopes, inclusief in de productieomgeving, altijd wilt valideren, configureert u de ServiceProviderOptions met UseDefaultServiceProvider op de host builder.

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

Aanvullende bronnen

• Host ASP.NET Core op Windows met IIS
• Host ASP.NET Core op Linux met Nginx
• Host ASP.NET Core in een Windows-service

ASP.NET Core-apps een host configureren en starten. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. De host configureert minimaal een server en een aanvraagverwerkingspijplijn. De host kan ook logboekregistratie, afhankelijkheidsinjectie en configuratie instellen.

Dit artikel bevat informatie over de webhost, die alleen beschikbaar blijft voor compatibiliteit met eerdere versies. De ASP.NET Core-sjablonen maken een .NET Generic Host. Dit wordt aanbevolen voor alle app-typen.

Een host instellen

Maak een host met behulp van een exemplaar van IWebHostBuilder. Dit wordt meestal uitgevoerd in het toegangspunt van de app, de Main methode.

In de projectsjablonen Main bevindt zich in Program.cs. Een typische app roept CreateDefaultBuilder aan om een host op te zetten.

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

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

De code die CreateDefaultBuilder aanroept, bevindt zich in een methode met de naam CreateWebHostBuilder, die deze scheidt van de code in Main die Run aanroept op het opbouwobject. Deze scheiding is vereist als u Entity Framework Core-hulpprogramma's gebruikt. De hulpprogramma's verwachten een CreateWebHostBuilder methode te vinden die ze tijdens het ontwerp kunnen aanroepen om de host te configureren zonder de app uit te voeren. Een alternatief is om te implementeren IDesignTimeDbContextFactory. Zie Ontwerptijd dbContext Makenvoor meer informatie.

CreateDefaultBuilder voert de volgende taken uit:

• Configureert Kestrel als de webserver met behulp van de hostingconfiguratieproviders van de app. Zie voor de standaardopties van de Kestrel-server Opties configureren voor de ASP.NET Core Kestrel webserver.
• Stelt de root van de inhoud in op het pad dat door Directory.GetCurrentDirectorywordt geretourneerd.
• Hostconfiguratie wordt geladen van:
  • Omgevingsvariabelen voorafgegaan door ASPNETCORE_ (bijvoorbeeld ASPNETCORE_ENVIRONMENT).
  • Opdrachtregelargumenten.
• Laadt de app-configuratie in de volgende volgorde van:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Gebruikersgeheimen wanneer de app wordt uitgevoerd in de Development omgeving met behulp van de invoerassembly.
  • Omgevingsvariabelen.
  • Opdrachtregelargumenten.
• Hiermee configureer je logging voor console- en foutopsporingsuitvoer. Logboekregistratie bevat regels voor logboekfilters die zijn opgegeven in een sectie logboekconfiguratie van een appsettings.json of appsettings.{Environment}.json bestand.
• Wanneer u achter IIS met de ASP.NET Core Module werkt, CreateDefaultBuilder schakelt u IIS-integratie in, waarmee het basisadres en de poort van de app worden geconfigureerd. IIS-integratie configureert ook de app om opstartfouten vast te leggen. Zie Host ASP.NET Core in Windows met IIS-voor de standaardopties van IIS.
• Stel ServiceProviderOptions.ValidateScopes in op true als de omgeving van de app Ontwikkeling is. Zie Bereikvalidatie voor meer informatie.

De configuratie die is gedefinieerd door CreateDefaultBuilder kan worden overschreven en uitgebreid door ConfigureAppConfiguration, ConfigureLoggingen andere methoden en uitbreidingsmethoden van IWebHostBuilder. Hier volgen enkele voorbeelden:

• ConfigureAppConfiguration wordt gebruikt om aanvullende IConfiguration voor de app op te geven. Met de volgende ConfigureAppConfiguration aanroep wordt een gemachtigde toegevoegd om app-configuratie in het appsettings.xml bestand op te nemen. ConfigureAppConfiguration kan meerdere keren worden aangeroepen. Houd er rekening mee dat deze configuratie niet van toepassing is op de host (bijvoorbeeld server-URL's of omgeving). Zie de sectie Hostconfiguratiewaarden .

  WebHost.CreateDefaultBuilder(args)
      .ConfigureAppConfiguration((hostingContext, config) =>
      {
          config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
      })
      ...
  

• Met de volgende ConfigureLogging aanroep wordt een gemachtigde toegevoegd om het minimale logboekregistratieniveau (SetMinimumLevel) aan te LogLevel.Warningconfigureren. Deze instelling overschrijft de instellingen in appsettings.Development.json (LogLevel.Debug) en appsettings.Production.json (LogLevel.Error) die zijn geconfigureerd door CreateDefaultBuilder. ConfigureLogging kan meerdere keren worden aangeroepen.

  WebHost.CreateDefaultBuilder(args)
      .ConfigureLogging(logging => 
      {
          logging.SetMinimumLevel(LogLevel.Warning);
      })
      ...
  

• De volgende aanroep van ConfigureKestrel overschrijft de standaard Limits.MaxRequestBodySize van 30.000.000 bytes, die is ingesteld toen Kestrel door CreateDefaultBuilder werd geconfigureerd:

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

De hoofdmap van de inhoud bepaalt waar de host zoekt naar inhoudsbestanden, zoals MVC-weergavebestanden. Wanneer de app wordt gestart vanuit de hoofdmap van het project, wordt deze gebruikt als de rootmap van de content. Dit is de standaardinstelling die wordt gebruikt in Visual Studio en de nieuwe dotnet-sjablonen.

Zie Configuratie in ASP.NET Core voor meer informatie over app-configuratie.

Bij het instellen van een host kunnen de methoden Configure en ConfigureServices worden opgegeven. Als een Startup klasse is opgegeven, moet deze een Configure methode definiëren. Zie App opstarten in ASP.NET Core voor meer informatie. Meerdere oproepen naar ConfigureServices worden aan elkaar gekoppeld. Meerdere aanroepen van Configure of UseStartup op de WebHostBuilder overschrijven de vorige instellingen.

Hostconfiguratiewaarden

WebHostBuilder is afhankelijk van de volgende methoden om de hostconfiguratiewaarden in te stellen:

• Host builder-configuratie, die omgevingsvariabelen met de indeling ASPNETCORE_{configurationKey}bevat. Bijvoorbeeld: ASPNETCORE_ENVIRONMENT.
• Extensies zoals UseContentRoot en UseConfiguration (zie de sectie Configuratie overschrijven ).
• UseSetting en de bijbehorende sleutel. Wanneer u een waarde instelt, UseSettingwordt de waarde ingesteld als een tekenreeks, ongeacht het type.

De host gebruikt de optie waarmee een waarde voor het laatst wordt ingesteld. Zie Overschrijfconfiguratie in de volgende sectie voor meer informatie.

Toepassingssleutel (naam)

De IWebHostEnvironment.ApplicationName eigenschap wordt automatisch ingesteld wanneer UseStartup of Configure wordt aangeroepen tijdens de bouw van de host. De waarde wordt toegewezen aan de naam van de assembly die het toegangspunt van de app bevat. Als u de waarde expliciet wilt instellen, gebruikt u het WebHostDefaults.ApplicationKeyvolgende:

Sleutel: applicatienaam
Type: tekenreeks
Standaard: de naam van de assembly die het toegangspunt van de app bevat.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_APPLICATIONNAME

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

Opstartfouten vastleggen

Deze instelling bepaalt de opname van opstartfouten.

Sleutel: captureStartupErrors
Type: bool (true of 1)
standaard: wordt standaard ingesteld op false, tenzij de app wordt uitgevoerd met Kestrel achter IIS, waarbij de standaardwaarde is true.
Instellen met behulp van: CaptureStartupErrors
omgevingsvariabele: ASPNETCORE_CAPTURESTARTUPERRORS

Wanneer false, leiden fouten tijdens het opstarten ertoe dat de host stopt. Wanneer true, legt de host uitzonderingen vast tijdens het opstarten en probeert de server te starten.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Inhoudsroot

Deze instelling bepaalt waar ASP.NET Core begint met het zoeken naar inhoudsbestanden.

Sleutel: contentRoot
Type: tekenreeks
Standaard: wordt standaard ingesteld op de map waarin de app-assembly zich bevindt.
Instellen met behulp van: UseContentRoot
omgevingsvariabele: ASPNETCORE_CONTENTROOT

De hoofdmap van de inhoud wordt ook gebruikt als het basispad voor de webroot. Als het hoofdpad van de inhoud niet bestaat, kan de host niet worden gestart.

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

Voor meer informatie, zie:

• Basisbeginselen: inhoudsmap
• Webroot

Gedetailleerde fouten

Bepaalt of gedetailleerde fouten moeten worden vastgelegd.

Sleutel: gedetailleerdeFouten
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_DETAILEDERRORS

Wanneer deze optie is ingeschakeld (of als de omgeving is ingesteld op Development), legt de app gedetailleerde uitzonderingen vast.

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

Milieu

Hiermee stelt u de omgeving van de app in.

Sleutelwoord: omgeving
Type: tekenreeks
Standaard: Productie
Instellen met behulp van: UseEnvironment
omgevingsvariabele: ASPNETCORE_ENVIRONMENT

De omgeving kan worden ingesteld op elke waarde. Framework-gedefinieerde waarden omvatten Development, Stagingen Production. Waarden zijn niet hoofdlettergevoelig. De omgeving wordt standaard gelezen uit de ASPNETCORE_ENVIRONMENT omgevingsvariabele. Wanneer u Visual Studio gebruikt, kunnen omgevingsvariabelen worden ingesteld in het launchSettings.json bestand. Zie ASP.NET Core runtime-omgevingen voor meer informatie.

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

Het organiseren van start-up bijeenkomsten

Hiermee stelt u de hosting opstartassemblages van de app in.

Sleutel: hostingStartupAssemblies
Type: tekenreeks
standaard: lege tekenreeks
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's om te laden bij het opstarten.

Hoewel de configuratiewaarde standaard is ingesteld op een lege tekenreeks, bevatten de hosting-opstartassembly's altijd de assembly van de app. Wanneer opstartassembly's worden gehost, worden ze toegevoegd aan de assembly van de app voor het laden wanneer de app zijn algemene services opbouwt tijdens het opstarten.

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

HTTPS-poort

Stel de HTTPS-omleidingspoort in. Gebruikt in om HTTPSaf te dwingen.

Sleutel: https_port
Type: tekenreeks
Standaard: er is geen standaardwaarde ingesteld.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HTTPS_PORTS

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

Assemblies uitsluiten tijdens het opstarten van de hosting

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's die moeten worden uitgesloten bij het opstarten.

Sleutel: hostingStartupExcludeAssemblies
Type: tekenreeks
standaard: lege tekenreeks
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Geef de voorkeur aan hosting-URLs

Geeft aan of de host moet luisteren naar de URL's die zijn geconfigureerd met de WebHostBuilder in plaats van de URL's die zijn geconfigureerd met de IServer implementatie.

Sleutel: preferHostingUrls
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: PreferHostingUrls
omgevingsvariabele: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Opstarten van hosting voorkomen

Voorkomt het automatisch laden van opstartassembly's, waaronder het hosten van opstartassembly's die zijn geconfigureerd door de assembly van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Sleutel: preventHostingStartup
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Server-URL's

Geeft de IP-adressen of hostadressen aan met poorten en protocollen waarop de server moet luisteren naar aanvragen.

Sleutel: URL's
Type: tekenreeks
Standaard: http://localhost:5000
Instellen met behulp van: UseUrls
omgevingsvariabele: ASPNETCORE_URLS

Ingesteld op een door puntkomma's gescheiden (;) lijst met URL-voorvoegsels waarop de server moet reageren. Bijvoorbeeld: http://localhost:123. Gebruik *om aan te geven dat de server moet luisteren naar aanvragen op een IP-adres of hostnaam met behulp van de opgegeven poort en het opgegeven protocol (bijvoorbeeld http://*:5000). Het protocol (http:// of https://) moet worden opgenomen in elke URL. Ondersteunde indelingen verschillen per server.

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

Kestrel heeft een eigen eindpuntconfiguratie-API. Zie Eindpunten configureren voor de ASP.NET Core Kestrel webservervoor meer informatie.

Time-out afsluiten

Hiermee geeft u de hoeveelheid tijd die moet worden gewacht totdat de webhost wordt afgesloten.

Sleutel: afsluitTimeoutSeconden
Type: int
Standaard: 5
Instellen met behulp van: UseShutdownTimeout
omgevingsvariabele: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Hoewel de sleutel een int accepteert met UseSetting (bijvoorbeeld .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), neemt de UseShutdownTimeout extensiemethode een TimeSpan.

Tijdens de time-outperiode hosten:

• Triggers IApplicationLifetime.ApplicationStopping.
• Pogingen om gehoste services te stoppen, waarbij eventuele fouten worden geregistreerd voor services die niet kunnen worden gestopt.

Als de time-outperiode verloopt voordat alle gehoste services stoppen, worden alle resterende actieve services gestopt wanneer de app wordt afgesloten. De services stoppen zelfs als ze de verwerking nog niet hebben voltooid. Als voor services extra tijd nodig is om te stoppen, verhoogt u de time-out.

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

Startupbijeenkomst

Bepaalt in welke assembly gezocht moet worden naar de Startup klasse.

Sleutel: startupAssembly
Type: tekenreeks
Standaard: de samenstelling van de app
Instellen met behulp van: UseStartup
omgevingsvariabele: ASPNETCORE_STARTUPASSEMBLY

Er kan naar de assembly worden verwezen op naam (string) of type (TStartup). Als er meerdere UseStartup methoden worden aangeroepen, heeft de laatste prioriteit.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

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

webroot

Hiermee stelt u het relatieve pad in voor de statische elementen van de app.

Sleutel: webroot
Type: tekenreeks
standaard: de standaardwaarde is wwwroot. Het pad naar {content root}/wwwroot- moet bestaan. Als het pad niet bestaat, wordt er een no-op bestandsprovider gebruikt.
Instellen met behulp van: UseWebRoot
omgevingsvariabele: ASPNETCORE_WEBROOT

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

Voor meer informatie, zie:

• Basisprincipes: webrootmap
• Inhoudroot

Configuratie overschrijven

Gebruik Configuratie om de webhost te configureren. In het volgende voorbeeld wordt de hostconfiguratie optioneel opgegeven in een hostsettings.json bestand. Elke configuratie die vanuit het hostsettings.json bestand wordt geladen, kan worden overschreven door opdrachtregelargumenten. De ingebouwde configuratie (in config) wordt gebruikt voor het configureren van de host met UseConfiguration. IWebHostBuilder configuratie wordt toegevoegd aan de configuratie van de app, maar het omgekeerde geldt niet—ConfigureAppConfiguration heeft geen invloed op de IWebHostBuilder configuratie.

Het overschrijven van de configuratie geleverd door UseUrls met eerst hostsettings.json configuratie, en ten tweede de opdrachtregelargument configuratie.

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

Om de host uit te voeren op een specifieke URL, kan de gewenste waarde worden doorgegeven vanuit een opdrachtprompt bij het uitvoeren van dotnet run. Het opdrachtregelargument overschrijft de urls waarde van het hostsettings.json bestand en de server luistert op poort 8080:

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

De host beheren

Rennen

De Run methode start de web-app en blokkeert de aanroepende thread totdat de host wordt afgesloten:

host.Run();

Begin

Voer de host op een niet-blokkerende manier uit door zijn methode Start aan te roepen.

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

Als een lijst met URL's wordt doorgegeven aan de Start methode, luistert deze naar de opgegeven URL's:

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

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

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

De app kan een nieuwe host initialiseren en starten met de vooraf geconfigureerde standaardwaarden van CreateDefaultBuilder met behulp van een statische gemaksfunctie. Met deze methoden start de server zonder console-uitvoer en met het wachten op een onderbreking (Ctrl-C/SIGINT of SIGTERM):

Start(RequestDelegate-app)

Begin met een RequestDelegate:

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

Doe een verzoek in de browser naar http://localhost:5000 om het antwoord 'Hallo wereld!' te ontvangen. WaitForShutdown blijft actief totdat er een onderbreking (met Ctrl-C/SIGINT of SIGTERM) wordt gegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

Start(tekenreeks-URL, RequestDelegate-app)

Begin met een URL en 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();
}

Produceert hetzelfde resultaat als Start(RequestDelegate app), behalve dat de app reageert op http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Gebruik een exemplaar van IRouteBuilder (Microsoft.AspNetCore.Routing) om middleware voor routering te gebruiken:

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

Gebruik de volgende browseraanvragen met het voorbeeld:

Aanvraag	Reactie
http://localhost:5000/hello/Martin	Hallo, Martin!
http://localhost:5000/buenosdias/Catrina	Buenos dias, Catrina!
http://localhost:5000/throw/ooops!	Genereert een uitzondering met tekenreeks 'ooops!'
http://localhost:5000/throw	Genereert een uitzondering met tekenreeks 'Uh oh!'
http://localhost:5000/Sante/Kevin	Sante, Kevin!
http://localhost:5000	Hallo mensen!

WaitForShutdown wordt geblokkeerd totdat een onderbreking (Ctrl-C/SIGINT of SIGTERM) wordt uitgegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

Start(String url, Action<IRouteBuilder> routeBuilder)

Gebruik een URL en een exemplaar van 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();
}

Produceert hetzelfde resultaat als Start(Action<IRouteBuilder routeBuilder> ), behalve dat de app reageert op http://localhost:8080.

StartWith(Action<IApplicationBuilder-app> )

Stel een gemachtigde in om een IApplicationBuilder te configureren.

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

Doe een verzoek in de browser naar http://localhost:5000 om het antwoord 'Hallo wereld!' te ontvangen. WaitForShutdown blijft actief totdat er een onderbreking (met Ctrl-C/SIGINT of SIGTERM) wordt gegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

StartWith(tekenreeks-URL, Action<IApplicationBuilder-app> )

Geef een URL en een afgevaardigde op om een IApplicationBuilder te configureren.

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

Produceert hetzelfde resultaat als StartWith(Action<IApplicationBuilder-app> ), behalve dat de app reageert op http://localhost:8080.

Interface IWebHostEnvironment

De IWebHostEnvironment interface biedt informatie over de webhostingomgeving van de app. Gebruik constructorinjectie om IWebHostEnvironment te verkrijgen en zijn eigenschappen en uitbreidingsmethoden te gebruiken:

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

Een op conventie gebaseerde benadering kan worden gebruikt om de app bij het opstarten te configureren op basis van de omgeving. U kunt ook de IWebHostEnvironment in de Startup constructor injecteren voor gebruik 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;
    }
}

De IWebHostEnvironment service kan ook rechtstreeks worden geïnjecteerd in de methode voor het Configure instellen van de verwerkingspijplijn:

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 kan worden geïnjecteerd in de Invoke methode bij het maken van aangepaste middleware:

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

    var contentRootPath = env.ContentRootPath;
}

Interface voor IHostApplicationLifetime

IHostApplicationLifetime maakt na het voltooien van opstarten en afsluiten activiteiten mogelijk. Drie eigenschappen op de interface zijn annuleringstokens die worden gebruikt om methoden te registreren Action waarmee opstart- en afsluitevenementen worden gedefinieerd.

Annuleringstoken	Geactiveerd wanneer...
ApplicationStarted	De host is volledig gestart.
ApplicationStopped	De host voltooit een zorgvuldige afsluiting. Alle aanvragen moeten worden verwerkt. Afsluiten blokkeert totdat deze gebeurtenis is voltooid.
ApplicationStopping	De host is bezig met een vlekkeloze afsluiting. Aanvragen kunnen nog steeds worden verwerkt. Afsluiten blokkeert totdat deze gebeurtenis is voltooid.

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 vraagt om beëindiging van de app. De volgende klasse gebruikt StopApplication om een app correct af te sluiten wanneer de methode van Shutdown de klasse wordt aangeroepen:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Bereikvalidatie

CreateDefaultBuilder stelt ServiceProviderOptions.ValidateScopes in op true als de omgeving van de app Ontwikkeling is.

Wanneer ValidateScopes is ingesteld op true, voert de standaardserviceprovider controles uit om te verifiëren dat:

• Scoped services worden niet direct of indirect opgelost vanuit de hoofdserviceprovider.
• Scoped services worden niet direct of indirect in singletons geïnjecteerd.

De hoofdserviceprovider wordt gemaakt wanneer BuildServiceProvider wordt aangeroepen. De levensduur van de hoofdserviceprovider komt overeen met de levensduur van de app/server wanneer de provider begint met de app en wordt verwijderd wanneer de app wordt afgesloten.

Scoped services worden verwijderd door de container die ze heeft gemaakt. Als een scoped service wordt gemaakt in de hoofdcontainer, wordt de levensduur van de service effectief gepromoveerd tot singleton omdat deze alleen wordt verwijderd door de hoofdcontainer wanneer de app/server wordt afgesloten. Bij het valideren van servicebereiken worden deze situaties onderschept wanneer BuildServiceProvider wordt aangeroepen.

Als u scopes, inclusief in de productieomgeving, altijd wilt valideren, configureert u de ServiceProviderOptions met UseDefaultServiceProvider op de host builder.

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

Aanvullende bronnen

• Host ASP.NET Core op Windows met IIS
• Host ASP.NET Core op Linux met Nginx
• Host ASP.NET Core in een Windows-service

ASP.NET Core-apps een host configureren en starten. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. De host configureert minimaal een server en een aanvraagverwerkingspijplijn. De host kan ook logboekregistratie, afhankelijkheidsinjectie en configuratie instellen.

Dit artikel bevat informatie over de webhost, die alleen beschikbaar blijft voor compatibiliteit met eerdere versies. De ASP.NET Core-sjablonen maken een .NET Generic Host. Dit wordt aanbevolen voor alle app-typen.

Een host instellen

Maak een host met behulp van een exemplaar van IWebHostBuilder. Dit wordt meestal uitgevoerd in het toegangspunt van de app, de Main methode.

In de projectsjablonen Main bevindt zich in Program.cs. Een typische app roept CreateDefaultBuilder aan om een host op te zetten.

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

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

De code die CreateDefaultBuilder aanroept, bevindt zich in een methode met de naam CreateWebHostBuilder, die deze scheidt van de code in Main die Run aanroept op het opbouwobject. Deze scheiding is vereist als u Entity Framework Core-hulpprogramma's gebruikt. De hulpprogramma's verwachten een CreateWebHostBuilder methode te vinden die ze tijdens het ontwerp kunnen aanroepen om de host te configureren zonder de app uit te voeren. Een alternatief is om te implementeren IDesignTimeDbContextFactory. Zie Ontwerptijd dbContext Makenvoor meer informatie.

CreateDefaultBuilder voert de volgende taken uit:

• Configureert Kestrel als de webserver met behulp van de hostingconfiguratieproviders van de app. Zie Kestrelvoor de standaardopties van de Kestrel-server.
• Stelt de root van de inhoud in op het pad dat door Directory.GetCurrentDirectorywordt geretourneerd.
• Hostconfiguratie wordt geladen van:
  • Omgevingsvariabelen voorafgegaan door ASPNETCORE_ (bijvoorbeeld ASPNETCORE_ENVIRONMENT).
  • Opdrachtregelargumenten.
• Laadt de app-configuratie in de volgende volgorde van:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Gebruikersgeheimen wanneer de app wordt uitgevoerd in de Development omgeving met behulp van de invoerassembly.
  • Omgevingsvariabelen.
  • Opdrachtregelargumenten.
• Hiermee configureer je logging voor console- en foutopsporingsuitvoer. Logboekregistratie bevat regels voor logboekfilters die zijn opgegeven in een sectie logboekconfiguratie van een appsettings.json of appsettings.{Environment}.json bestand.
• Wanneer u achter IIS met de ASP.NET Core Module werkt, CreateDefaultBuilder schakelt u IIS-integratie in, waarmee het basisadres en de poort van de app worden geconfigureerd. IIS-integratie configureert ook de app om opstartfouten vast te leggen. Zie Host ASP.NET Core in Windows met IIS-voor de standaardopties van IIS.
• Stel ServiceProviderOptions.ValidateScopes in op true als de omgeving van de app Ontwikkeling is. Zie Bereikvalidatie voor meer informatie.

De configuratie die is gedefinieerd door CreateDefaultBuilder kan worden overschreven en uitgebreid door ConfigureAppConfiguration, ConfigureLoggingen andere methoden en uitbreidingsmethoden van IWebHostBuilder. Hier volgen enkele voorbeelden:

• ConfigureAppConfiguration wordt gebruikt om aanvullende IConfiguration voor de app op te geven. Met de volgende ConfigureAppConfiguration aanroep wordt een gemachtigde toegevoegd om app-configuratie in het appsettings.xml bestand op te nemen. ConfigureAppConfiguration kan meerdere keren worden aangeroepen. Houd er rekening mee dat deze configuratie niet van toepassing is op de host (bijvoorbeeld server-URL's of omgeving). Zie de sectie Hostconfiguratiewaarden .

  WebHost.CreateDefaultBuilder(args)
      .ConfigureAppConfiguration((hostingContext, config) =>
      {
          config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
      })
      ...
  

• Met de volgende ConfigureLogging aanroep wordt een gemachtigde toegevoegd om het minimale logboekregistratieniveau (SetMinimumLevel) aan te LogLevel.Warningconfigureren. Deze instelling overschrijft de instellingen in appsettings.Development.json (LogLevel.Debug) en appsettings.Production.json (LogLevel.Error) die zijn geconfigureerd door CreateDefaultBuilder. ConfigureLogging kan meerdere keren worden aangeroepen.

  WebHost.CreateDefaultBuilder(args)
      .ConfigureLogging(logging => 
      {
          logging.SetMinimumLevel(LogLevel.Warning);
      })
      ...
  

• De volgende aanroep van ConfigureKestrel overschrijft de standaard Limits.MaxRequestBodySize van 30.000.000 bytes, die is ingesteld toen Kestrel door CreateDefaultBuilder werd geconfigureerd:

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

De hoofdmap van de inhoud bepaalt waar de host zoekt naar inhoudsbestanden, zoals MVC-weergavebestanden. Wanneer de app wordt gestart vanuit de hoofdmap van het project, wordt deze gebruikt als de rootmap van de content. Dit is de standaardinstelling die wordt gebruikt in Visual Studio en de nieuwe dotnet-sjablonen.

Zie Configuratie in ASP.NET Core voor meer informatie over app-configuratie.

Bij het instellen van een host kunnen de methoden Configure en ConfigureServices worden opgegeven. Als een Startup klasse is opgegeven, moet deze een Configure methode definiëren. Zie App opstarten in ASP.NET Core voor meer informatie. Meerdere oproepen naar ConfigureServices worden aan elkaar gekoppeld. Meerdere aanroepen van Configure of UseStartup op de WebHostBuilder overschrijven de vorige instellingen.

Hostconfiguratiewaarden

WebHostBuilder is afhankelijk van de volgende methoden om de hostconfiguratiewaarden in te stellen:

• Host builder-configuratie, die omgevingsvariabelen met de indeling ASPNETCORE_{configurationKey}bevat. Bijvoorbeeld: ASPNETCORE_ENVIRONMENT.
• Extensies zoals UseContentRoot en UseConfiguration (zie de sectie Configuratie overschrijven ).
• UseSetting en de bijbehorende sleutel. Wanneer u een waarde instelt, UseSettingwordt de waarde ingesteld als een tekenreeks, ongeacht het type.

De host gebruikt de optie waarmee een waarde voor het laatst wordt ingesteld. Zie Overschrijfconfiguratie in de volgende sectie voor meer informatie.

Toepassingssleutel (naam)

De IWebHostEnvironment.ApplicationName eigenschap wordt automatisch ingesteld wanneer UseStartup of Configure wordt aangeroepen tijdens de bouw van de host. De waarde wordt toegewezen aan de naam van de assembly die het toegangspunt van de app bevat. Als u de waarde expliciet wilt instellen, gebruikt u het WebHostDefaults.ApplicationKeyvolgende:

Sleutel: applicatienaam
Type: tekenreeks
Standaard: de naam van de assembly die het toegangspunt van de app bevat.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_APPLICATIONNAME

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

Opstartfouten vastleggen

Deze instelling bepaalt de opname van opstartfouten.

Sleutel: captureStartupErrors
Type: bool (true of 1)
standaard: wordt standaard ingesteld op false, tenzij de app wordt uitgevoerd met Kestrel achter IIS, waarbij de standaardwaarde is true.
Instellen met behulp van: CaptureStartupErrors
omgevingsvariabele: ASPNETCORE_CAPTURESTARTUPERRORS

Wanneer false, leiden fouten tijdens het opstarten ertoe dat de host stopt. Wanneer true, legt de host uitzonderingen vast tijdens het opstarten en probeert de server te starten.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Inhoudsroot

Deze instelling bepaalt waar ASP.NET Core begint met het zoeken naar inhoudsbestanden.

Sleutel: contentRoot
Type: tekenreeks
Standaard: wordt standaard ingesteld op de map waarin de app-assembly zich bevindt.
Instellen met behulp van: UseContentRoot
omgevingsvariabele: ASPNETCORE_CONTENTROOT

De hoofdmap van de inhoud wordt ook gebruikt als het basispad voor de webroot. Als het hoofdpad van de inhoud niet bestaat, kan de host niet worden gestart.

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

Voor meer informatie, zie:

• Basisbeginselen: inhoudsmap
• Webroot

Gedetailleerde fouten

Bepaalt of gedetailleerde fouten moeten worden vastgelegd.

Sleutel: gedetailleerdeFouten
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_DETAILEDERRORS

Wanneer deze optie is ingeschakeld (of als de omgeving is ingesteld op Development), legt de app gedetailleerde uitzonderingen vast.

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

Milieu

Hiermee stelt u de omgeving van de app in.

Sleutelwoord: omgeving
Type: tekenreeks
Standaard: Productie
Instellen met behulp van: UseEnvironment
omgevingsvariabele: ASPNETCORE_ENVIRONMENT

De omgeving kan worden ingesteld op elke waarde. Framework-gedefinieerde waarden omvatten Development, Stagingen Production. Waarden zijn niet hoofdlettergevoelig. De omgeving wordt standaard gelezen uit de ASPNETCORE_ENVIRONMENT omgevingsvariabele. Wanneer u Visual Studio gebruikt, kunnen omgevingsvariabelen worden ingesteld in het launchSettings.json bestand. Zie ASP.NET Core runtime-omgevingen voor meer informatie.

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

Het organiseren van start-up bijeenkomsten

Hiermee stelt u de hosting opstartassemblages van de app in.

Sleutel: hostingStartupAssemblies
Type: tekenreeks
standaard: lege tekenreeks
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's om te laden bij het opstarten.

Hoewel de configuratiewaarde standaard is ingesteld op een lege tekenreeks, bevatten de hosting-opstartassembly's altijd de assembly van de app. Wanneer opstartassembly's worden gehost, worden ze toegevoegd aan de assembly van de app voor het laden wanneer de app zijn algemene services opbouwt tijdens het opstarten.

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

HTTPS-poort

Stel de HTTPS-omleidingspoort in. Gebruikt in om HTTPSaf te dwingen.

Sleutel: https_port
Type: tekenreeks
Standaard: er is geen standaardwaarde ingesteld.
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HTTPS_PORTS

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

Assemblies uitsluiten tijdens het opstarten van de hosting

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's die moeten worden uitgesloten bij het opstarten.

Sleutel: hostingStartupExcludeAssemblies
Type: tekenreeks
standaard: lege tekenreeks
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Geef de voorkeur aan hosting-URLs

Geeft aan of de host moet luisteren naar de URL's die zijn geconfigureerd met de WebHostBuilder in plaats van de URL's die zijn geconfigureerd met de IServer implementatie.

Sleutel: preferHostingUrls
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: PreferHostingUrls
omgevingsvariabele: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Opstarten van hosting voorkomen

Voorkomt het automatisch laden van opstartassembly's, waaronder het hosten van opstartassembly's die zijn geconfigureerd door de assembly van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Sleutel: preventHostingStartup
Type: bool (true of 1)
Standaard: onwaar
Instellen met behulp van: UseSetting
omgevingsvariabele: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Server-URL's

Geeft de IP-adressen of hostadressen aan met poorten en protocollen waarop de server moet luisteren naar aanvragen.

Sleutel: URL's
Type: tekenreeks
Standaard: http://localhost:5000
Instellen met behulp van: UseUrls
omgevingsvariabele: ASPNETCORE_URLS

Ingesteld op een door puntkomma's gescheiden (;) lijst met URL-voorvoegsels waarop de server moet reageren. Bijvoorbeeld: http://localhost:123. Gebruik *om aan te geven dat de server moet luisteren naar aanvragen op een IP-adres of hostnaam met behulp van de opgegeven poort en het opgegeven protocol (bijvoorbeeld http://*:5000). Het protocol (http:// of https://) moet worden opgenomen in elke URL. Ondersteunde indelingen verschillen per server.

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

Kestrel heeft een eigen eindpuntconfiguratie-API. Zie Kestrel webserver in ASP.NET Corevoor meer informatie.

Time-out afsluiten

Hiermee geeft u de hoeveelheid tijd die moet worden gewacht totdat de webhost wordt afgesloten.

Sleutel: afsluitTimeoutSeconden
Type: int
Standaard: 5
Instellen met behulp van: UseShutdownTimeout
omgevingsvariabele: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Hoewel de sleutel een int accepteert met UseSetting (bijvoorbeeld .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), neemt de UseShutdownTimeout extensiemethode een TimeSpan.

Tijdens de time-outperiode hosten:

• Triggers IApplicationLifetime.ApplicationStopping.
• Pogingen om gehoste services te stoppen, waarbij eventuele fouten worden geregistreerd voor services die niet kunnen worden gestopt.

Als de time-outperiode verloopt voordat alle gehoste services stoppen, worden alle resterende actieve services gestopt wanneer de app wordt afgesloten. De services stoppen zelfs als ze de verwerking nog niet hebben voltooid. Als voor services extra tijd nodig is om te stoppen, verhoogt u de time-out.

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

Startupbijeenkomst

Bepaalt in welke assembly gezocht moet worden naar de Startup klasse.

Sleutel: startupAssembly
Type: tekenreeks
Standaard: de samenstelling van de app
Instellen met behulp van: UseStartup
omgevingsvariabele: ASPNETCORE_STARTUPASSEMBLY

Er kan naar de assembly worden verwezen op naam (string) of type (TStartup). Als er meerdere UseStartup methoden worden aangeroepen, heeft de laatste prioriteit.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

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

webroot

Hiermee stelt u het relatieve pad in voor de statische elementen van de app.

Sleutel: webroot
Type: tekenreeks
standaard: de standaardwaarde is wwwroot. Het pad naar {content root}/wwwroot- moet bestaan. Als het pad niet bestaat, wordt er een no-op bestandsprovider gebruikt.
Instellen met behulp van: UseWebRoot
omgevingsvariabele: ASPNETCORE_WEBROOT

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

Voor meer informatie, zie:

• Basisprincipes: webrootmap
• Inhoudroot

Configuratie overschrijven

Gebruik Configuratie om de webhost te configureren. In het volgende voorbeeld wordt de hostconfiguratie optioneel opgegeven in een hostsettings.json bestand. Elke configuratie die vanuit het hostsettings.json bestand wordt geladen, kan worden overschreven door opdrachtregelargumenten. De ingebouwde configuratie (in config) wordt gebruikt voor het configureren van de host met UseConfiguration. IWebHostBuilder configuratie wordt toegevoegd aan de configuratie van de app, maar het omgekeerde geldt niet—ConfigureAppConfiguration heeft geen invloed op de IWebHostBuilder configuratie.

Het overschrijven van de configuratie geleverd door UseUrls met eerst hostsettings.json configuratie, en ten tweede de opdrachtregelargument configuratie.

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

Om de host uit te voeren op een specifieke URL, kan de gewenste waarde worden doorgegeven vanuit een opdrachtprompt bij het uitvoeren van dotnet run. Het opdrachtregelargument overschrijft de urls waarde van het hostsettings.json bestand en de server luistert op poort 8080:

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

De host beheren

Rennen

De Run methode start de web-app en blokkeert de aanroepende thread totdat de host wordt afgesloten:

host.Run();

Begin

Voer de host op een niet-blokkerende manier uit door zijn methode Start aan te roepen.

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

Als een lijst met URL's wordt doorgegeven aan de Start methode, luistert deze naar de opgegeven URL's:

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

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

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

De app kan een nieuwe host initialiseren en starten met de vooraf geconfigureerde standaardwaarden van CreateDefaultBuilder met behulp van een statische gemaksfunctie. Met deze methoden start de server zonder console-uitvoer en met het wachten op een onderbreking (Ctrl-C/SIGINT of SIGTERM):

Start(RequestDelegate-app)

Begin met een RequestDelegate:

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

Doe een verzoek in de browser naar http://localhost:5000 om het antwoord 'Hallo wereld!' te ontvangen. WaitForShutdown blijft actief totdat er een onderbreking (met Ctrl-C/SIGINT of SIGTERM) wordt gegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

Start(tekenreeks-URL, RequestDelegate-app)

Begin met een URL en 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();
}

Produceert hetzelfde resultaat als Start(RequestDelegate app), behalve dat de app reageert op http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Gebruik een exemplaar van IRouteBuilder (Microsoft.AspNetCore.Routing) om middleware voor routering te gebruiken:

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

Gebruik de volgende browseraanvragen met het voorbeeld:

Aanvraag	Reactie
http://localhost:5000/hello/Martin	Hallo, Martin!
http://localhost:5000/buenosdias/Catrina	Buenos dias, Catrina!
http://localhost:5000/throw/ooops!	Genereert een uitzondering met tekenreeks 'ooops!'
http://localhost:5000/throw	Genereert een uitzondering met tekenreeks 'Uh oh!'
http://localhost:5000/Sante/Kevin	Sante, Kevin!
http://localhost:5000	Hallo mensen!

WaitForShutdown wordt geblokkeerd totdat een onderbreking (Ctrl-C/SIGINT of SIGTERM) wordt uitgegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

Start(String url, Action<IRouteBuilder> routeBuilder)

Gebruik een URL en een exemplaar van 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();
}

Produceert hetzelfde resultaat als Start(Action<IRouteBuilder routeBuilder> ), behalve dat de app reageert op http://localhost:8080.

StartWith(Action<IApplicationBuilder-app> )

Stel een gemachtigde in om een IApplicationBuilder te configureren.

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

Doe een verzoek in de browser naar http://localhost:5000 om het antwoord 'Hallo wereld!' te ontvangen. WaitForShutdown blijft actief totdat er een onderbreking (met Ctrl-C/SIGINT of SIGTERM) wordt gegeven. De app geeft het Console.WriteLine bericht weer en wacht op een toetsdruk om te verlaten.

StartWith(tekenreeks-URL, Action<IApplicationBuilder-app> )

Geef een URL en een afgevaardigde op om een IApplicationBuilder te configureren.

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

Produceert hetzelfde resultaat als StartWith(Action<IApplicationBuilder-app> ), behalve dat de app reageert op http://localhost:8080.

Interface IWebHostEnvironment

De IWebHostEnvironment interface biedt informatie over de webhostingomgeving van de app. Gebruik constructorinjectie om IWebHostEnvironment te verkrijgen en zijn eigenschappen en uitbreidingsmethoden te gebruiken:

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

Een op conventie gebaseerde benadering kan worden gebruikt om de app bij het opstarten te configureren op basis van de omgeving. U kunt ook de IWebHostEnvironment in de Startup constructor injecteren voor gebruik 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;
    }
}

De IWebHostEnvironment service kan ook rechtstreeks worden geïnjecteerd in de methode voor het Configure instellen van de verwerkingspijplijn:

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 kan worden geïnjecteerd in de Invoke methode bij het maken van aangepaste middleware:

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

    var contentRootPath = env.ContentRootPath;
}

Interface voor IHostApplicationLifetime

IHostApplicationLifetime maakt na het voltooien van opstarten en afsluiten activiteiten mogelijk. Drie eigenschappen op de interface zijn annuleringstokens die worden gebruikt om methoden te registreren Action waarmee opstart- en afsluitevenementen worden gedefinieerd.

Annuleringstoken	Geactiveerd wanneer...
ApplicationStarted	De host is volledig gestart.
ApplicationStopped	De host voltooit een zorgvuldige afsluiting. Alle aanvragen moeten worden verwerkt. Afsluiten blokkeert totdat deze gebeurtenis is voltooid.
ApplicationStopping	De host is bezig met een vlekkeloze afsluiting. Aanvragen kunnen nog steeds worden verwerkt. Afsluiten blokkeert totdat deze gebeurtenis is voltooid.

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 vraagt om beëindiging van de app. De volgende klasse gebruikt StopApplication om een app correct af te sluiten wanneer de methode van Shutdown de klasse wordt aangeroepen:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Bereikvalidatie

CreateDefaultBuilder stelt ServiceProviderOptions.ValidateScopes in op true als de omgeving van de app Ontwikkeling is.

Wanneer ValidateScopes is ingesteld op true, voert de standaardserviceprovider controles uit om te verifiëren dat:

• Scoped services worden niet direct of indirect opgelost vanuit de hoofdserviceprovider.
• Scoped services worden niet direct of indirect in singletons geïnjecteerd.

De hoofdserviceprovider wordt gemaakt wanneer BuildServiceProvider wordt aangeroepen. De levensduur van de hoofdserviceprovider komt overeen met de levensduur van de app/server wanneer de provider begint met de app en wordt verwijderd wanneer de app wordt afgesloten.

Scoped services worden verwijderd door de container die ze heeft gemaakt. Als een scoped service wordt gemaakt in de hoofdcontainer, wordt de levensduur van de service effectief gepromoveerd tot singleton omdat deze alleen wordt verwijderd door de hoofdcontainer wanneer de app/server wordt afgesloten. Bij het valideren van servicebereiken worden deze situaties onderschept wanneer BuildServiceProvider wordt aangeroepen.

Als u scopes, inclusief in de productieomgeving, altijd wilt valideren, configureert u de ServiceProviderOptions met UseDefaultServiceProvider op de host builder.

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

Aanvullende bronnen

• Host ASP.NET Core op Windows met IIS
• Host ASP.NET Core op Linux met Nginx
• Host ASP.NET Core in een Windows-service