ASP.NET Core webbvärd

ASP.NET Core-appar konfigurerar och startar en värd. Värden ansvarar för appstart och livslängdshantering. Värden konfigurerar minst en server och en pipeline för bearbetning av begäranden. Värden kan också konfigurera loggning, beroendeinmatning och konfiguration.

Den här artikeln beskriver webbhotellet, som endast är tillgängligt för bakåtkompatibilitet. ASP.NET Core-mallarna skapar en WebApplicationBuilder och WebApplication, som rekommenderas för webbappar. Mer information om WebApplicationBuilder och WebApplicationfinns i Migrera från ASP.NET Core i .NET 5 till .NET 6

Konfigurera en värd

Skapa en värd med hjälp av en instans av IWebHostBuilder. Detta utförs vanligtvis i appens startpunkt, Main metoden i Program.cs. En typisk app anropar CreateDefaultBuilder för att starta konfigurationen av en värd:

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

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

Koden som anropar CreateDefaultBuilder finns i en metod med namnet CreateWebHostBuilder, som skiljer den från koden i Main som anropar Run builder-objektet. Den här separationen krävs om du använder Entity Framework Core-verktyg. Verktygen förväntar sig att hitta en CreateWebHostBuilder metod som de kan anropa vid designtillfället för att konfigurera värd utan att köra appen. Ett alternativ är att implementera IDesignTimeDbContextFactory. Mer information finns i Design-time DbContext Creation.

CreateDefaultBuilder utför följande uppgifter:

• Konfigurerar Kestrel servern som webbserver med hjälp av appens värdkonfigurationsprovidrar. Standardalternativen för Kestrel-servern finns i Konfigurera alternativ för ASP.NET Core Kestrel-webbservern.
• Anger innehållsroten till den sökväg som returneras av Directory.GetCurrentDirectory.
• Läser in värdkonfiguration från :
  • Miljövariabler med prefixet ASPNETCORE_ (till exempel ASPNETCORE_ENVIRONMENT).
  • Kommandoradsargument.
• Läser in appkonfigurationen i följande ordning från:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Användarhemligheter när appen körs i Development miljön med hjälp av inmatningssammansättningen.
  • Miljövariabler.
  • Kommandoradsargument.
• Konfigurerar loggning för konsol- och felsökningsutdata. Loggning innefattar loggfiltreringsregler som anges i en loggningskonfigurationssektion i en appsettings.json- eller appsettings.{Environment}.json-fil.
• När du kör bakom IIS med ASP.NET Core-modulenCreateDefaultBuilder aktiverar du IIS-integrering, som konfigurerar appens basadress och port. IIS-integrering konfigurerar också appen för att fånga upp startfel. Standardalternativen för IIS finns i Host ASP.NET Core on Windows with IIS.
• Sätter ServiceProviderOptions.ValidateScopes till true om applikationens miljö är Utvecklingsläge. Mer information finns i Omfångsverifiering.

Konfigurationen som definieras av CreateDefaultBuilder kan åsidosättas och utökas med ConfigureAppConfiguration, ConfigureLoggingoch andra metoder och tilläggsmetoder för IWebHostBuilder. Några exempel följer:

• ConfigureAppConfiguration används för att ange ytterligare IConfiguration för appen. Följande ConfigureAppConfiguration anrop lägger till en delegat för att inkludera appkonfiguration till appsettings.xml-filen. ConfigureAppConfiguration kan anropas flera gånger. Observera att den här konfigurationen inte gäller för värdenheten (till exempel server-URL:er eller miljöinställningar). Se avsnittet Host konfigurationsvärden.

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

• Följande ConfigureLogging anrop lägger till ett ombud för att konfigurera den lägsta loggningsnivån (SetMinimumLevel) till LogLevel.Warning. Den här inställningen åsidosätter inställningarna i appsettings.Development.json (LogLevel.Debug) och appsettings.Production.json (LogLevel.Error) som konfigurerats av CreateDefaultBuilder. ConfigureLogging kan anropas flera gånger.

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

• Följande anrop till ConfigureKestrel åsidosätter standardvärdet Limits.MaxRequestBodySize på 30 000 000 byte som upprättades när Kestrel konfigurerades av CreateDefaultBuilder:

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

Innehållsroten avgör var värdprogrammet söker efter innehållsfiler, till exempel MVC-visningsfiler. När appen startas från projektets rotmapp används projektets rotmapp som innehållsrot. Det här är standardvärdet som används i Visual Studio och de nya dotnet-mallarna.

Mer information om appkonfiguration finns i Konfiguration i ASP.NET Core.

När du konfigurerar en värd kan metoder för Configure och ConfigureServices anges. Om en Startup klass anges måste den definiera en Configure metod. Mer information finns i Appstart i ASP.NET Core. Flera anrop till ConfigureServices läggs till efter varandra. Flera anrop till Configure eller UseStartup på WebHostBuilder ersätter tidigare inställningar.

Värdkonfigurationsvärden

WebHostBuilder använder följande metoder för att ange värdens konfigurationsvärden:

• Konfiguration av värdbyggare, som innehåller miljövariabler med formatet ASPNETCORE_{configurationKey}. Till exempel ASPNETCORE_ENVIRONMENT.
• Tillägg som UseContentRoot och UseConfiguration (se avsnittet Åsidosätt konfiguration ).
• UseSetting och den associerade nyckeln. När du anger ett värde med UseSettinganges värdet som en sträng oavsett typ.

Värden använder det alternativ som sist anger ett värde. Mer information finns i Åsidosätt konfiguration i nästa avsnitt.

Programnyckel (namn)

Egenskapen IWebHostEnvironment.ApplicationName anges automatiskt när UseStartup eller Configure anropas under värdkonstruktionen. Värdet anges till namnet på sammansättningen som innehåller appens startpunkt. Om du vill ange värdet explicit använder du WebHostDefaults.ApplicationKey:

Nyckel: applicationName
Typ: sträng
Standard: Namnet på sammansättningen som innehåller appens startpunkt.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_APPLICATIONNAME

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

Fånga startfel

Den här inställningen styr insamlingen av startfel.

Nyckel: captureStartupErrors
Typ: bool (true eller 1)
Standard: Standardvärdet är false förutom när appen körs med Kestrel via IIS, där standardvärdet är true.
Ange med:CaptureStartupErrors
Miljövariabel: ASPNETCORE_CAPTURESTARTUPERRORS

När falseinträffar fel vid start resulterar det i att värdenheten avslutas. När truefångar upp undantag under uppstart och försöker starta servern.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Rot för innehåll

Den här inställningen avgör var ASP.NET Core börjar söka efter innehållsfiler.

Nyckel: contentRoot
Typ: sträng
Standard: Standardinställningen är mappen där appsammansättningen finns.
Ange med:UseContentRoot
Miljövariabel: ASPNETCORE_CONTENTROOT

Innehållsroten används också som bassökväg för webbroten. Om innehållsrotsökvägen inte finns, startar värden inte.

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

Mer information finns i:

• Grunderna: Innehållsrot
• Webbrot

Detaljerade fel

Avgör om detaljerade fel ska registreras.

Nyckel: detaljeradeFel
Typ: bool (true eller 1)
Standard: false
Ange med:UseSetting
Miljövariabel: ASPNETCORE_DETAILEDERRORS

När den är aktiverad (eller när miljön är inställd på Development) samlar appen in detaljerade undantag.

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

Miljö

Anger appens miljö.

Nyckel: miljö
Typ: sträng
Standard: Produktion
Ange med:UseEnvironment
Miljövariabel: ASPNETCORE_ENVIRONMENT

Miljön kan anges till valfritt värde. Ramverksdefinierade värden omfattar Development, Stagingoch Production. Värden är inte skiftlägeskänsliga. Som standard läss miljön från ASPNETCORE_ENVIRONMENT miljövariabeln. När du använder Visual Studio kan miljövariabler anges i launchSettings.json filen. Mer information finns i ASP.NET Core-körningsmiljöer.

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

Värd för startupträffar

Anger appens värdbaserade startsammansättningar.

Nyckel: hostingStartupAssemblies
Typ: sträng
Standard: Tom sträng
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

En semikolonavgränsad sträng som är värd för startsammansättningar för att läsa in vid start.

Även om konfigurationsvärdet som standard är en tom sträng inkluderar värdstartssammansättningarna alltid appens sammansättning. När du tillhandahåller värdtjänster för startsammansättningar läggs de till i appens sammansättning för inläsning när appen skapar sina gemensamma tjänster under starten.

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

HTTPS-port

Ange HTTPS-porten som omdirigering till om du får en icke-HTTPS-anslutning. Används i att upprätthålla HTTPS. Den här inställningen gör inte att servern lyssnar på den angivna porten. Det är alltså möjligt att oavsiktligt omdirigera begäranden till en oanvänd port.

Nyckel: https_port
Typ: sträng
Standard: Ett standardvärde har inte angetts.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HTTPS_PORT

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

HTTPS-portar

Ställ in portarna för att lyssna på HTTPS-anslutningar.

Nyckel: https_ports Typ: sträng
Standard: Ett standardvärde har inte angetts.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HTTPS_PORTS

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

HTTP-portar

Ställ in portarna för att lyssna på HTTP-anslutningar.

Nyckel: http_ports Typ: sträng
Standard: Ett standardvärde har inte angetts.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HTTP_PORTS

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

Värd för start exkludera sammansättningar

En semikolonavgränsad sträng med uppstartssammansättningar som ska undantas vid start.

Nyckel: hostingStartupExcludeAssemblies
Typ: sträng
Standard: Tom sträng
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Föredrar värd-URL:er

Indikerar om hosten ska lyssna på URL:er som konfigurerats med WebHostBuilder, istället för de som konfigurerats med implementeringen IServer.

Nyckel: preferHostingUrls
Typ: bool (true eller 1)
Standard: false
Ange med:PreferHostingUrls
Miljövariabel: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Förhindra att hosting startar

Förhindrar automatisk läsning av värdstartssamlingar, inklusive sådana som konfigurerats av appens samling. För mer information, se Användning av värdstartssammansättningar i ASP.NET Core.

Nyckel: preventHostingStartup
Typ: bool (true eller 1)
Standard: false
Ange med:UseSetting
Miljövariabel: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Server-URL:er

Anger IP-adresser eller värdadresser med portar och protokoll som servern ska lyssna på efter begäranden.

Nyckel: URL:er
Typ: sträng
Standard: http://localhost:5000
Ange med:UseUrls
Miljövariabel: ASPNETCORE_URLS

Ställ in till en semikolonavgränsad (;) lista över URL-prefix som servern ska svara på. Till exempel http://localhost:123. Använd "*" för att ange att servern ska lyssna efter begäranden på alla IP-adresser eller värdnamn med den angivna porten och protokollet (till exempel http://*:5000). Protokollet (http:// eller https://) måste ingå i varje URL. Format som stöds varierar mellan servrar.

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

Kestrel har ett eget API för slutpunktskonfiguration. Mer information finns i Konfigurera slutpunkter för ASP.NET Core Kestrel-webbservern.

Tidsgräns för avstängning

Anger hur lång tid det tar att vänta tills webbvärden stängs av.

Nyckel: avstängningstidsekunder
Typ: int
Standard: 5
Ange med:UseShutdownTimeout
Miljövariabel: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Även om nyckeln accepterar en int med UseSetting (till exempel .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), UseShutdownTimeout tar tilläggsmetoden en TimeSpan.

Under timeout-perioden, värdskap:

• Utlösare IApplicationLifetime.ApplicationStopping.
• Försöker stoppa värdbaserade tjänster och loggar eventuella fel för tjänster som inte kan stoppas.

Om tidsgränsen går ut innan alla värdbaserade tjänster stoppas stoppas alla återstående aktiva tjänster när appen stängs av. Tjänsterna stoppas även om de inte har slutfört bearbetningen. Om tjänster kräver ytterligare tid för att stoppa ökar du tidsgränsen.

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

Startsammansättning

Avgör den sammansättning som ska användas för att söka efter Startup-klassen.

Nyckel: startupAssembly
Typ: sträng
Standard: Appens sammansättning
Ange med:UseStartup
Miljövariabel: ASPNETCORE_STARTUPASSEMBLY

Sammansättningen efter namn (string) eller typ (TStartup) kan refereras till. Om flera UseStartup metoder anropas har den sista företräde.

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

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

Webbrotsplats

Anger den relativa sökvägen till appens statiska tillgångar.

Nyckel: webroot
Typ: sträng
standard: Standardvärdet är wwwroot. Sökvägen till {content root}/wwwroot måste finnas. Om sökvägen inte finns används en no-op filprovider.
Ange med:UseWebRoot
Miljövariabel: ASPNETCORE_WEBROOT

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

Mer information finns i:

• grunderna: Webbroten
• Innehållsrot

Åsidosätt konfiguration

Använd Konfiguration för att konfigurera webbvärd. I följande exempel anges värdkonfigurationen valfritt i en hostsettings.json fil. Alla konfigurationer som läses in från hostsettings.json filen kan åsidosättas av kommandoradsargument. Den byggda konfigurationen (i config) används för att konfigurera värdenheten UseConfiguration. IWebHostBuilder konfigurationen läggs till i appens konfiguration, men det omvända är inte sant–ConfigureAppConfiguration påverkar inte konfigurationen IWebHostBuilder .

Åsidosätta konfigurationen som tillhandahålls av UseUrls med hostsettings.json config first, kommandoradsargument 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"
}

För att specificera värden som körs på en viss URL kan önskat värde anges från ett kommandofönster när du kör dotnet run. Kommandoradsargumentet urls åsidosätter värdet från hostsettings.json filen och servern lyssnar på port 8080:

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

Hantera värd

Springa

Metoden Run startar webbappen och blockerar den anropande tråden tills värdtjänsten stängs av.

host.Run();

Starta

Kör värden i ett icke-blockerande läge genom att anropa dess Start-metod.

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

Om en lista med URL:er skickas till Start metoden lyssnar den på de angivna URL:erna:

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

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

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

Appen kan initiera och starta en ny värd med de förkonfigurerade standardinställningarna CreateDefaultBuilder för att använda en statisk bekvämlighetsmetod. Dessa metoder startar servern utan konsolutdata och väntar WaitForShutdown på en paus (Ctrl-C/SIGINT eller SIGTERM):

Start(RequestDelegate-app)

Börja med en RequestDelegate:

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

Gör en begäran i webbläsaren till http://localhost:5000 för att få svaret "Hello World!" WaitForShutdown blockeras tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

Start(sträng-URL, RequestDelegate-app)

Börja med en URL och 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();
}

Ger samma resultat som Start(RequestDelegate-appen), förutom att appen svarar på http://localhost:8080.

Start(Åtgärd<IRouteBuilder> routeBuilder)

Använd en instans av IRouteBuilder (Microsoft.AspNetCore.Routing) för att använda routning mellanprogram:

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

Använd följande webbläsarbegäranden med exemplet:

Begäran	Svar
http://localhost:5000/hello/Martin	Hej, Martin!
http://localhost:5000/buenosdias/Catrina	Buenos dias, Catrina!
http://localhost:5000/throw/ooops!	Genererar ett undantag med strängen "ooops!"
http://localhost:5000/throw	Utlöser ett undantag med strängen "Uh oh!"
http://localhost:5000/Sante/Kevin	Sante, Kevin!
http://localhost:5000	Hej världen!

WaitForShutdown blockerar tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

Start(string url, Action<IRouteBuilder> routeBuilder)

Använd en URL och en instans av 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();
}

Ger samma resultat som Start(Action<IRouteBuilder> routeBuilder), förutom att appen svarar på http://localhost:8080.

StartWith(åtgärdsappen<IApplicationBuilder> )

Tillhandahåll en delegat för att konfigurera en 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();
}

Gör en begäran i webbläsaren till http://localhost:5000 för att få svaret "Hello World!" WaitForShutdown blockeras tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

StartWith(string URL, Action<IApplicationBuilder> app)

Ange en URL och ett ombud för att konfigurera en 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();
}

Ger samma resultat som StartWith(Action<IApplicationBuilder>-appen), förutom att appen svarar på http://localhost:8080.

IWebHostEnvironment-gränssnitt

Gränssnittet IWebHostEnvironment innehåller information om appens webbvärdmiljö. Använd konstruktorinmatning för att hämta IWebHostEnvironment för att använda dess egenskaper och tilläggsmetoder:

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

En konventionsbaserad metod kan användas för att konfigurera appen vid start baserat på miljön. Alternativt kan du mata in IWebHostEnvironment i konstruktorn Startup för att använda i 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;
    }
}

Tjänsten IWebHostEnvironment kan också matas in direkt i Configure metoden för att konfigurera bearbetningspipelinen:

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 matas in i Invoke metoden när du skapar anpassade mellanprogram:

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

IHostApplicationLifetime-gränssnitt

IHostApplicationLifetime tillåter aktiviteter efter start och avstängning. Tre egenskaper i gränssnittet är annulleringstoken som används för att registrera Action metoder som definierar start- och avstängningshändelser.

Annullerings-token	Utlöses när...
ApplicationStarted	Värden har startat fullt.
ApplicationStopped	Värden slutför en graciös avstängning. Alla begäranden ska bearbetas. Nedstängningen blockeras tills den här händelsen har slutförts.
ApplicationStopping	Värden utför en graciös avstängning. Begäranden kan fortfarande bearbetas. Nedstängningen blockeras tills den här händelsen har slutförts.

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 begär avslutning av appen. Följande klass använder StopApplication för att på ett smidigt sätt stänga av en app när klassens -metod anropas Shutdown :

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Omfångsverifiering

CreateDefaultBuilder ställer in ServiceProviderOptions.ValidateScopes om true appens miljö är Utvecklingsmiljö.

När ValidateScopes är inställt truepå utför standardtjänstleverantören kontroller för att kontrollera att:

• Tjänster med begränsad omfattning löses inte direkt eller indirekt från grundserviceleverantören.
• Tjänster med begränsat omfång injiceras inte direkt eller indirekt i singletons.

Rottjänstprovidern skapas när BuildServiceProvider anropas. Rottjänstleverantörens livslängd motsvarar appens/serverns livslängd när providern börjar med appen och tas bort när appen stängs av.

Tjänster med avgränsat omfång avvecklas av den container som skapade dem. Om en begränsad tjänst skapas i rotcontainern höjs tjänstens livslängd effektivt till singleton eftersom den endast tas bort av rotcontainern när appen/servern stängs av. Validering av tjänstens omfång identifierar dessa situationer när BuildServiceProvider anropas.

Om du alltid vill validera omfång, inklusive i produktionsmiljön, konfigurerar du ServiceProviderOptions med UseDefaultServiceProvider på värdbyggaren:

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

Ytterligare resurser

• Köra ASP.NET Core på Windows med IIS
• Hosting av ASP.NET Core på Linux med Nginx
• Driva ASP.NET Core som en Windows-tjänst

ASP.NET Core-appar konfigurerar och startar en värd. Värden ansvarar för appstart och livslängdshantering. Värden konfigurerar minst en server och en pipeline för bearbetning av begäranden. Värden kan också konfigurera loggning, beroendeinmatning och konfiguration.

Den här artikeln beskriver webbhotellet, som endast är tillgängligt för bakåtkompatibilitet. ASP.NET Core-mallarna skapar en .NET Generic Host, som rekommenderas för alla apptyper.

Konfigurera en värd

Skapa en värd med hjälp av en instans av IWebHostBuilder. Detta utförs vanligtvis i appens startpunkt, Main metoden.

I projektmallarna Main finns i Program.cs. En typisk app anropar CreateDefaultBuilder för att starta konfigurationen av en värd:

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

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

Koden som anropar CreateDefaultBuilder finns i en metod med namnet CreateWebHostBuilder, som skiljer den från koden i Main som anropar Run builder-objektet. Den här separationen krävs om du använder Entity Framework Core-verktyg. Verktygen förväntar sig att hitta en CreateWebHostBuilder metod som de kan anropa vid designtillfället för att konfigurera värd utan att köra appen. Ett alternativ är att implementera IDesignTimeDbContextFactory. Mer information finns i Design-time DbContext Creation.

CreateDefaultBuilder utför följande uppgifter:

• Konfigurerar Kestrel servern som webbserver med hjälp av appens värdkonfigurationsprovidrar. Standardalternativen för Kestrel-servern finns i Konfigurera alternativ för ASP.NET Core Kestrel-webbservern.
• Anger innehållsroten till den sökväg som returneras av Directory.GetCurrentDirectory.
• Läser in värdkonfiguration från :
  • Miljövariabler med prefixet ASPNETCORE_ (till exempel ASPNETCORE_ENVIRONMENT).
  • Kommandoradsargument.
• Läser in appkonfigurationen i följande ordning från:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Användarhemligheter när appen körs i Development miljön med hjälp av inmatningssammansättningen.
  • Miljövariabler.
  • Kommandoradsargument.
• Konfigurerar loggning för konsol- och felsökningsutdata. Loggning innefattar loggfiltreringsregler som anges i en loggningskonfigurationssektion i en appsettings.json- eller appsettings.{Environment}.json-fil.
• När du kör bakom IIS med ASP.NET Core-modulenCreateDefaultBuilder aktiverar du IIS-integrering, som konfigurerar appens basadress och port. IIS-integrering konfigurerar också appen för att fånga upp startfel. Standardalternativen för IIS finns i Host ASP.NET Core on Windows with IIS.
• Sätter ServiceProviderOptions.ValidateScopes till true om applikationens miljö är Utvecklingsläge. Mer information finns i Omfångsverifiering.

Konfigurationen som definieras av CreateDefaultBuilder kan åsidosättas och utökas med ConfigureAppConfiguration, ConfigureLoggingoch andra metoder och tilläggsmetoder för IWebHostBuilder. Några exempel följer:

• ConfigureAppConfiguration används för att ange ytterligare IConfiguration för appen. Följande ConfigureAppConfiguration anrop lägger till en delegat för att inkludera appkonfiguration till appsettings.xml-filen. ConfigureAppConfiguration kan anropas flera gånger. Observera att den här konfigurationen inte gäller för värdenheten (till exempel server-URL:er eller miljöinställningar). Se avsnittet Host konfigurationsvärden.

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

• Följande ConfigureLogging anrop lägger till ett ombud för att konfigurera den lägsta loggningsnivån (SetMinimumLevel) till LogLevel.Warning. Den här inställningen åsidosätter inställningarna i appsettings.Development.json (LogLevel.Debug) och appsettings.Production.json (LogLevel.Error) som konfigurerats av CreateDefaultBuilder. ConfigureLogging kan anropas flera gånger.

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

• Följande anrop till ConfigureKestrel åsidosätter standardvärdet Limits.MaxRequestBodySize på 30 000 000 byte som upprättades när Kestrel konfigurerades av CreateDefaultBuilder:

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

Innehållsroten avgör var värdprogrammet söker efter innehållsfiler, till exempel MVC-visningsfiler. När appen startas från projektets rotmapp används projektets rotmapp som innehållsrot. Det här är standardvärdet som används i Visual Studio och de nya dotnet-mallarna.

Mer information om appkonfiguration finns i Konfiguration i ASP.NET Core.

När du konfigurerar en värd kan metoder för Configure och ConfigureServices anges. Om en Startup klass anges måste den definiera en Configure metod. Mer information finns i Appstart i ASP.NET Core. Flera anrop till ConfigureServices läggs till efter varandra. Flera anrop till Configure eller UseStartup på WebHostBuilder ersätter tidigare inställningar.

Värdkonfigurationsvärden

WebHostBuilder använder följande metoder för att ange värdens konfigurationsvärden:

• Konfiguration av värdbyggare, som innehåller miljövariabler med formatet ASPNETCORE_{configurationKey}. Till exempel ASPNETCORE_ENVIRONMENT.
• Tillägg som UseContentRoot och UseConfiguration (se avsnittet Åsidosätt konfiguration ).
• UseSetting och den associerade nyckeln. När du anger ett värde med UseSettinganges värdet som en sträng oavsett typ.

Värden använder det alternativ som sist anger ett värde. Mer information finns i Åsidosätt konfiguration i nästa avsnitt.

Programnyckel (namn)

Egenskapen IWebHostEnvironment.ApplicationName anges automatiskt när UseStartup eller Configure anropas under värdkonstruktionen. Värdet anges till namnet på sammansättningen som innehåller appens startpunkt. Om du vill ange värdet explicit använder du WebHostDefaults.ApplicationKey:

Nyckel: applicationName
Typ: sträng
Standard: Namnet på sammansättningen som innehåller appens startpunkt.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_APPLICATIONNAME

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

Fånga startfel

Den här inställningen styr insamlingen av startfel.

Nyckel: captureStartupErrors
Typ: bool (true eller 1)
Standard: Standardvärdet är false förutom när appen körs med Kestrel via IIS, där standardvärdet är true.
Ange med:CaptureStartupErrors
Miljövariabel: ASPNETCORE_CAPTURESTARTUPERRORS

När falseinträffar fel vid start resulterar det i att värdenheten avslutas. När truefångar upp undantag under uppstart och försöker starta servern.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Rot för innehåll

Den här inställningen avgör var ASP.NET Core börjar söka efter innehållsfiler.

Nyckel: contentRoot
Typ: sträng
Standard: Standardinställningen är mappen där appsammansättningen finns.
Ange med:UseContentRoot
Miljövariabel: ASPNETCORE_CONTENTROOT

Innehållsroten används också som bassökväg för webbroten. Om innehållsrotsökvägen inte finns, startar värden inte.

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

Mer information finns i:

• Grunderna: Innehållsrot
• Webbrot

Detaljerade fel

Avgör om detaljerade fel ska registreras.

Nyckel: detaljeradeFel
Typ: bool (true eller 1)
Standard: false
Ange med:UseSetting
Miljövariabel: ASPNETCORE_DETAILEDERRORS

När den är aktiverad (eller när miljön är inställd på Development) samlar appen in detaljerade undantag.

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

Miljö

Anger appens miljö.

Nyckel: miljö
Typ: sträng
Standard: Produktion
Ange med:UseEnvironment
Miljövariabel: ASPNETCORE_ENVIRONMENT

Miljön kan anges till valfritt värde. Ramverksdefinierade värden omfattar Development, Stagingoch Production. Värden är inte skiftlägeskänsliga. Som standard läss miljön från ASPNETCORE_ENVIRONMENT miljövariabeln. När du använder Visual Studio kan miljövariabler anges i launchSettings.json filen. Mer information finns i ASP.NET Core-körningsmiljöer.

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

Värd för startupträffar

Anger appens värdbaserade startsammansättningar.

Nyckel: hostingStartupAssemblies
Typ: sträng
Standard: Tom sträng
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

En semikolonavgränsad sträng som är värd för startsammansättningar för att läsa in vid start.

Även om konfigurationsvärdet som standard är en tom sträng inkluderar värdstartssammansättningarna alltid appens sammansättning. När du tillhandahåller värdtjänster för startsammansättningar läggs de till i appens sammansättning för inläsning när appen skapar sina gemensamma tjänster under starten.

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

HTTPS-port

Ställ in HTTPS-omdirigeringsporten. Används i att upprätthålla HTTPS.

Nyckel: https_port
Typ: sträng
Standard: Ett standardvärde har inte angetts.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HTTPS_PORTS

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

Värd för start exkludera sammansättningar

En semikolonavgränsad sträng med uppstartssammansättningar som ska undantas vid start.

Nyckel: hostingStartupExcludeAssemblies
Typ: sträng
Standard: Tom sträng
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Föredrar värd-URL:er

Indikerar om hosten ska lyssna på URL:er som konfigurerats med WebHostBuilder, istället för de som konfigurerats med implementeringen IServer.

Nyckel: preferHostingUrls
Typ: bool (true eller 1)
Standard: false
Ange med:PreferHostingUrls
Miljövariabel: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Förhindra att hosting startar

Förhindrar automatisk läsning av värdstartssamlingar, inklusive sådana som konfigurerats av appens samling. För mer information, se Användning av värdstartssammansättningar i ASP.NET Core.

Nyckel: preventHostingStartup
Typ: bool (true eller 1)
Standard: false
Ange med:UseSetting
Miljövariabel: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Server-URL:er

Anger IP-adresser eller värdadresser med portar och protokoll som servern ska lyssna på efter begäranden.

Nyckel: URL:er
Typ: sträng
Standard: http://localhost:5000
Ange med:UseUrls
Miljövariabel: ASPNETCORE_URLS

Ställ in till en semikolonavgränsad (;) lista över URL-prefix som servern ska svara på. Till exempel http://localhost:123. Använd "*" för att ange att servern ska lyssna efter begäranden på alla IP-adresser eller värdnamn med den angivna porten och protokollet (till exempel http://*:5000). Protokollet (http:// eller https://) måste ingå i varje URL. Format som stöds varierar mellan servrar.

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

Kestrel har ett eget API för slutpunktskonfiguration. Mer information finns i Konfigurera slutpunkter för ASP.NET Core Kestrel-webbservern.

Tidsgräns för avstängning

Anger hur lång tid det tar att vänta tills webbvärden stängs av.

Nyckel: avstängningstidsekunder
Typ: int
Standard: 5
Ange med:UseShutdownTimeout
Miljövariabel: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Även om nyckeln accepterar en int med UseSetting (till exempel .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), UseShutdownTimeout tar tilläggsmetoden en TimeSpan.

Under timeout-perioden, värdskap:

• Utlösare IApplicationLifetime.ApplicationStopping.
• Försöker stoppa värdbaserade tjänster och loggar eventuella fel för tjänster som inte kan stoppas.

Om tidsgränsen går ut innan alla värdbaserade tjänster stoppas stoppas alla återstående aktiva tjänster när appen stängs av. Tjänsterna stoppas även om de inte har slutfört bearbetningen. Om tjänster kräver ytterligare tid för att stoppa ökar du tidsgränsen.

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

Startsammansättning

Avgör den sammansättning som ska användas för att söka efter Startup-klassen.

Nyckel: startupAssembly
Typ: sträng
Standard: Appens sammansättning
Ange med:UseStartup
Miljövariabel: ASPNETCORE_STARTUPASSEMBLY

Sammansättningen efter namn (string) eller typ (TStartup) kan refereras till. Om flera UseStartup metoder anropas har den sista företräde.

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

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

Webbrotsplats

Anger den relativa sökvägen till appens statiska tillgångar.

Nyckel: webroot
Typ: sträng
standard: Standardvärdet är wwwroot. Sökvägen till {content root}/wwwroot måste finnas. Om sökvägen inte finns används en no-op filprovider.
Ange med:UseWebRoot
Miljövariabel: ASPNETCORE_WEBROOT

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

Mer information finns i:

• grunderna: Webbroten
• Innehållsrot

Åsidosätt konfiguration

Använd Konfiguration för att konfigurera webbvärd. I följande exempel anges värdkonfigurationen valfritt i en hostsettings.json fil. Alla konfigurationer som läses in från hostsettings.json filen kan åsidosättas av kommandoradsargument. Den byggda konfigurationen (i config) används för att konfigurera värdenheten UseConfiguration. IWebHostBuilder konfigurationen läggs till i appens konfiguration, men det omvända är inte sant–ConfigureAppConfiguration påverkar inte konfigurationen IWebHostBuilder .

Åsidosätta konfigurationen som tillhandahålls av UseUrls med hostsettings.json config first, kommandoradsargument 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"
}

För att specificera värden som körs på en viss URL kan önskat värde anges från ett kommandofönster när du kör dotnet run. Kommandoradsargumentet urls åsidosätter värdet från hostsettings.json filen och servern lyssnar på port 8080:

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

Hantera värd

Springa

Metoden Run startar webbappen och blockerar den anropande tråden tills värdtjänsten stängs av.

host.Run();

Starta

Kör värden i ett icke-blockerande läge genom att anropa dess Start-metod.

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

Om en lista med URL:er skickas till Start metoden lyssnar den på de angivna URL:erna:

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

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

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

Appen kan initiera och starta en ny värd med de förkonfigurerade standardinställningarna CreateDefaultBuilder för att använda en statisk bekvämlighetsmetod. Dessa metoder startar servern utan konsolutdata och väntar WaitForShutdown på en paus (Ctrl-C/SIGINT eller SIGTERM):

Start(RequestDelegate-app)

Börja med en RequestDelegate:

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

Gör en begäran i webbläsaren till http://localhost:5000 för att få svaret "Hello World!" WaitForShutdown blockeras tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

Start(sträng-URL, RequestDelegate-app)

Börja med en URL och 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();
}

Ger samma resultat som Start(RequestDelegate-appen), förutom att appen svarar på http://localhost:8080.

Start(Åtgärd<IRouteBuilder> routeBuilder)

Använd en instans av IRouteBuilder (Microsoft.AspNetCore.Routing) för att använda routning mellanprogram:

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

Använd följande webbläsarbegäranden med exemplet:

Begäran	Svar
http://localhost:5000/hello/Martin	Hej, Martin!
http://localhost:5000/buenosdias/Catrina	Buenos dias, Catrina!
http://localhost:5000/throw/ooops!	Genererar ett undantag med strängen "ooops!"
http://localhost:5000/throw	Utlöser ett undantag med strängen "Uh oh!"
http://localhost:5000/Sante/Kevin	Sante, Kevin!
http://localhost:5000	Hej världen!

WaitForShutdown blockerar tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

Start(string url, Action<IRouteBuilder> routeBuilder)

Använd en URL och en instans av 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();
}

Ger samma resultat som Start(Action<IRouteBuilder> routeBuilder), förutom att appen svarar på http://localhost:8080.

StartWith(åtgärdsappen<IApplicationBuilder> )

Tillhandahåll en delegat för att konfigurera en 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();
}

Gör en begäran i webbläsaren till http://localhost:5000 för att få svaret "Hello World!" WaitForShutdown blockeras tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

StartWith(string URL, Action<IApplicationBuilder> app)

Ange en URL och ett ombud för att konfigurera en 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();
}

Ger samma resultat som StartWith(Action<IApplicationBuilder>-appen), förutom att appen svarar på http://localhost:8080.

IWebHostEnvironment-gränssnitt

Gränssnittet IWebHostEnvironment innehåller information om appens webbvärdmiljö. Använd konstruktorinmatning för att hämta IWebHostEnvironment för att använda dess egenskaper och tilläggsmetoder:

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

En konventionsbaserad metod kan användas för att konfigurera appen vid start baserat på miljön. Alternativt kan du mata in IWebHostEnvironment i konstruktorn Startup för att använda i 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;
    }
}

Tjänsten IWebHostEnvironment kan också matas in direkt i Configure metoden för att konfigurera bearbetningspipelinen:

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 matas in i Invoke metoden när du skapar anpassade mellanprogram:

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

IHostApplicationLifetime-gränssnitt

IHostApplicationLifetime tillåter aktiviteter efter start och avstängning. Tre egenskaper i gränssnittet är annulleringstoken som används för att registrera Action metoder som definierar start- och avstängningshändelser.

Annullerings-token	Utlöses när...
ApplicationStarted	Värden har startat fullt.
ApplicationStopped	Värden slutför en graciös avstängning. Alla begäranden ska bearbetas. Nedstängningen blockeras tills den här händelsen har slutförts.
ApplicationStopping	Värden utför en graciös avstängning. Begäranden kan fortfarande bearbetas. Nedstängningen blockeras tills den här händelsen har slutförts.

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 begär avslutning av appen. Följande klass använder StopApplication för att på ett smidigt sätt stänga av en app när klassens -metod anropas Shutdown :

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Omfångsverifiering

CreateDefaultBuilder ställer in ServiceProviderOptions.ValidateScopes om true appens miljö är Utvecklingsmiljö.

När ValidateScopes är inställt truepå utför standardtjänstleverantören kontroller för att kontrollera att:

• Tjänster med begränsad omfattning löses inte direkt eller indirekt från grundserviceleverantören.
• Tjänster med begränsat omfång injiceras inte direkt eller indirekt i singletons.

Rottjänstprovidern skapas när BuildServiceProvider anropas. Rottjänstleverantörens livslängd motsvarar appens/serverns livslängd när providern börjar med appen och tas bort när appen stängs av.

Tjänster med avgränsat omfång avvecklas av den container som skapade dem. Om en begränsad tjänst skapas i rotcontainern höjs tjänstens livslängd effektivt till singleton eftersom den endast tas bort av rotcontainern när appen/servern stängs av. Validering av tjänstens omfång identifierar dessa situationer när BuildServiceProvider anropas.

Om du alltid vill validera omfång, inklusive i produktionsmiljön, konfigurerar du ServiceProviderOptions med UseDefaultServiceProvider på värdbyggaren:

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

Ytterligare resurser

• Köra ASP.NET Core på Windows med IIS
• Hosting av ASP.NET Core på Linux med Nginx
• Driva ASP.NET Core som en Windows-tjänst

ASP.NET Core-appar konfigurerar och startar en värd. Värden ansvarar för appstart och livslängdshantering. Värden konfigurerar minst en server och en pipeline för bearbetning av begäranden. Värden kan också konfigurera loggning, beroendeinmatning och konfiguration.

Den här artikeln beskriver webbhotellet, som endast är tillgängligt för bakåtkompatibilitet. ASP.NET Core-mallarna skapar en .NET Generic Host, som rekommenderas för alla apptyper.

Konfigurera en värd

Skapa en värd med hjälp av en instans av IWebHostBuilder. Detta utförs vanligtvis i appens startpunkt, Main metoden.

I projektmallarna Main finns i Program.cs. En typisk app anropar CreateDefaultBuilder för att starta konfigurationen av en värd:

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

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

Koden som anropar CreateDefaultBuilder finns i en metod med namnet CreateWebHostBuilder, som skiljer den från koden i Main som anropar Run builder-objektet. Den här separationen krävs om du använder Entity Framework Core-verktyg. Verktygen förväntar sig att hitta en CreateWebHostBuilder metod som de kan anropa vid designtillfället för att konfigurera värd utan att köra appen. Ett alternativ är att implementera IDesignTimeDbContextFactory. Mer information finns i Design-time DbContext Creation.

CreateDefaultBuilder utför följande uppgifter:

• Konfigurerar Kestrel servern som webbserver med hjälp av appens värdkonfigurationsprovidrar. Standardalternativen för Kestrel-servern finns i Kestrel webbserver i ASP.NET Core.
• Anger innehållsroten till den sökväg som returneras av Directory.GetCurrentDirectory.
• Läser in värdkonfiguration från :
  • Miljövariabler med prefixet ASPNETCORE_ (till exempel ASPNETCORE_ENVIRONMENT).
  • Kommandoradsargument.
• Läser in appkonfigurationen i följande ordning från:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Användarhemligheter när appen körs i Development miljön med hjälp av inmatningssammansättningen.
  • Miljövariabler.
  • Kommandoradsargument.
• Konfigurerar loggning för konsol- och felsökningsutdata. Loggning innefattar loggfiltreringsregler som anges i en loggningskonfigurationssektion i en appsettings.json- eller appsettings.{Environment}.json-fil.
• När du kör bakom IIS med ASP.NET Core-modulenCreateDefaultBuilder aktiverar du IIS-integrering, som konfigurerar appens basadress och port. IIS-integrering konfigurerar också appen för att fånga upp startfel. Standardalternativen för IIS finns i Host ASP.NET Core on Windows with IIS.
• Sätter ServiceProviderOptions.ValidateScopes till true om applikationens miljö är Utvecklingsläge. Mer information finns i Omfångsverifiering.

Konfigurationen som definieras av CreateDefaultBuilder kan åsidosättas och utökas med ConfigureAppConfiguration, ConfigureLoggingoch andra metoder och tilläggsmetoder för IWebHostBuilder. Några exempel följer:

• ConfigureAppConfiguration används för att ange ytterligare IConfiguration för appen. Följande ConfigureAppConfiguration anrop lägger till en delegat för att inkludera appkonfiguration till appsettings.xml-filen. ConfigureAppConfiguration kan anropas flera gånger. Observera att den här konfigurationen inte gäller för värdenheten (till exempel server-URL:er eller miljöinställningar). Se avsnittet Host konfigurationsvärden.

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

• Följande ConfigureLogging anrop lägger till ett ombud för att konfigurera den lägsta loggningsnivån (SetMinimumLevel) till LogLevel.Warning. Den här inställningen åsidosätter inställningarna i appsettings.Development.json (LogLevel.Debug) och appsettings.Production.json (LogLevel.Error) som konfigurerats av CreateDefaultBuilder. ConfigureLogging kan anropas flera gånger.

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

• Följande anrop till ConfigureKestrel åsidosätter standardvärdet Limits.MaxRequestBodySize på 30 000 000 byte som upprättades när Kestrel konfigurerades av CreateDefaultBuilder:

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

Innehållsroten avgör var värdprogrammet söker efter innehållsfiler, till exempel MVC-visningsfiler. När appen startas från projektets rotmapp används projektets rotmapp som innehållsrot. Det här är standardvärdet som används i Visual Studio och de nya dotnet-mallarna.

Mer information om appkonfiguration finns i Konfiguration i ASP.NET Core.

När du konfigurerar en värd kan metoder för Configure och ConfigureServices anges. Om en Startup klass anges måste den definiera en Configure metod. Mer information finns i Appstart i ASP.NET Core. Flera anrop till ConfigureServices läggs till efter varandra. Flera anrop till Configure eller UseStartup på WebHostBuilder ersätter tidigare inställningar.

Värdkonfigurationsvärden

WebHostBuilder använder följande metoder för att ange värdens konfigurationsvärden:

• Konfiguration av värdbyggare, som innehåller miljövariabler med formatet ASPNETCORE_{configurationKey}. Till exempel ASPNETCORE_ENVIRONMENT.
• Tillägg som UseContentRoot och UseConfiguration (se avsnittet Åsidosätt konfiguration ).
• UseSetting och den associerade nyckeln. När du anger ett värde med UseSettinganges värdet som en sträng oavsett typ.

Värden använder det alternativ som sist anger ett värde. Mer information finns i Åsidosätt konfiguration i nästa avsnitt.

Programnyckel (namn)

Egenskapen IWebHostEnvironment.ApplicationName anges automatiskt när UseStartup eller Configure anropas under värdkonstruktionen. Värdet anges till namnet på sammansättningen som innehåller appens startpunkt. Om du vill ange värdet explicit använder du WebHostDefaults.ApplicationKey:

Nyckel: applicationName
Typ: sträng
Standard: Namnet på sammansättningen som innehåller appens startpunkt.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_APPLICATIONNAME

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

Fånga startfel

Den här inställningen styr insamlingen av startfel.

Nyckel: captureStartupErrors
Typ: bool (true eller 1)
Standard: Standardvärdet är false förutom när appen körs med Kestrel via IIS, där standardvärdet är true.
Ange med:CaptureStartupErrors
Miljövariabel: ASPNETCORE_CAPTURESTARTUPERRORS

När falseinträffar fel vid start resulterar det i att värdenheten avslutas. När truefångar upp undantag under uppstart och försöker starta servern.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Rot för innehåll

Den här inställningen avgör var ASP.NET Core börjar söka efter innehållsfiler.

Nyckel: contentRoot
Typ: sträng
Standard: Standardinställningen är mappen där appsammansättningen finns.
Ange med:UseContentRoot
Miljövariabel: ASPNETCORE_CONTENTROOT

Innehållsroten används också som bassökväg för webbroten. Om innehållsrotsökvägen inte finns, startar värden inte.

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

Mer information finns i:

• Grunderna: Innehållsrot
• Webbrot

Detaljerade fel

Avgör om detaljerade fel ska registreras.

Nyckel: detaljeradeFel
Typ: bool (true eller 1)
Standard: false
Ange med:UseSetting
Miljövariabel: ASPNETCORE_DETAILEDERRORS

När den är aktiverad (eller när miljön är inställd på Development) samlar appen in detaljerade undantag.

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

Miljö

Anger appens miljö.

Nyckel: miljö
Typ: sträng
Standard: Produktion
Ange med:UseEnvironment
Miljövariabel: ASPNETCORE_ENVIRONMENT

Miljön kan anges till valfritt värde. Ramverksdefinierade värden omfattar Development, Stagingoch Production. Värden är inte skiftlägeskänsliga. Som standard läss miljön från ASPNETCORE_ENVIRONMENT miljövariabeln. När du använder Visual Studio kan miljövariabler anges i launchSettings.json filen. Mer information finns i ASP.NET Core-körningsmiljöer.

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

Värd för startupträffar

Anger appens värdbaserade startsammansättningar.

Nyckel: hostingStartupAssemblies
Typ: sträng
Standard: Tom sträng
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

En semikolonavgränsad sträng som är värd för startsammansättningar för att läsa in vid start.

Även om konfigurationsvärdet som standard är en tom sträng inkluderar värdstartssammansättningarna alltid appens sammansättning. När du tillhandahåller värdtjänster för startsammansättningar läggs de till i appens sammansättning för inläsning när appen skapar sina gemensamma tjänster under starten.

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

HTTPS-port

Ställ in HTTPS-omdirigeringsporten. Används i att upprätthålla HTTPS.

Nyckel: https_port
Typ: sträng
Standard: Ett standardvärde har inte angetts.
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HTTPS_PORTS

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

Värd för start exkludera sammansättningar

En semikolonavgränsad sträng med uppstartssammansättningar som ska undantas vid start.

Nyckel: hostingStartupExcludeAssemblies
Typ: sträng
Standard: Tom sträng
Ange med:UseSetting
Miljövariabel: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Föredrar värd-URL:er

Indikerar om hosten ska lyssna på URL:er som konfigurerats med WebHostBuilder, istället för de som konfigurerats med implementeringen IServer.

Nyckel: preferHostingUrls
Typ: bool (true eller 1)
Standard: false
Ange med:PreferHostingUrls
Miljövariabel: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Förhindra att hosting startar

Förhindrar automatisk läsning av värdstartssamlingar, inklusive sådana som konfigurerats av appens samling. För mer information, se Användning av värdstartssammansättningar i ASP.NET Core.

Nyckel: preventHostingStartup
Typ: bool (true eller 1)
Standard: false
Ange med:UseSetting
Miljövariabel: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Server-URL:er

Anger IP-adresser eller värdadresser med portar och protokoll som servern ska lyssna på efter begäranden.

Nyckel: URL:er
Typ: sträng
Standard: http://localhost:5000
Ange med:UseUrls
Miljövariabel: ASPNETCORE_URLS

Ställ in till en semikolonavgränsad (;) lista över URL-prefix som servern ska svara på. Till exempel http://localhost:123. Använd "*" för att ange att servern ska lyssna efter begäranden på alla IP-adresser eller värdnamn med den angivna porten och protokollet (till exempel http://*:5000). Protokollet (http:// eller https://) måste ingå i varje URL. Format som stöds varierar mellan servrar.

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

Kestrel har ett eget API för slutpunktskonfiguration. Mer information finns i Kestrel webbserver i ASP.NET Core.

Tidsgräns för avstängning

Anger hur lång tid det tar att vänta tills webbvärden stängs av.

Nyckel: avstängningstidsekunder
Typ: int
Standard: 5
Ange med:UseShutdownTimeout
Miljövariabel: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Även om nyckeln accepterar en int med UseSetting (till exempel .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), UseShutdownTimeout tar tilläggsmetoden en TimeSpan.

Under timeout-perioden, värdskap:

• Utlösare IApplicationLifetime.ApplicationStopping.
• Försöker stoppa värdbaserade tjänster och loggar eventuella fel för tjänster som inte kan stoppas.

Om tidsgränsen går ut innan alla värdbaserade tjänster stoppas stoppas alla återstående aktiva tjänster när appen stängs av. Tjänsterna stoppas även om de inte har slutfört bearbetningen. Om tjänster kräver ytterligare tid för att stoppa ökar du tidsgränsen.

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

Startsammansättning

Avgör den sammansättning som ska användas för att söka efter Startup-klassen.

Nyckel: startupAssembly
Typ: sträng
Standard: Appens sammansättning
Ange med:UseStartup
Miljövariabel: ASPNETCORE_STARTUPASSEMBLY

Sammansättningen efter namn (string) eller typ (TStartup) kan refereras till. Om flera UseStartup metoder anropas har den sista företräde.

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

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

Webbrotsplats

Anger den relativa sökvägen till appens statiska tillgångar.

Nyckel: webroot
Typ: sträng
standard: Standardvärdet är wwwroot. Sökvägen till {content root}/wwwroot måste finnas. Om sökvägen inte finns används en no-op filprovider.
Ange med:UseWebRoot
Miljövariabel: ASPNETCORE_WEBROOT

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

Mer information finns i:

• grunderna: Webbroten
• Innehållsrot

Åsidosätt konfiguration

Använd Konfiguration för att konfigurera webbvärd. I följande exempel anges värdkonfigurationen valfritt i en hostsettings.json fil. Alla konfigurationer som läses in från hostsettings.json filen kan åsidosättas av kommandoradsargument. Den byggda konfigurationen (i config) används för att konfigurera värdenheten UseConfiguration. IWebHostBuilder konfigurationen läggs till i appens konfiguration, men det omvända är inte sant–ConfigureAppConfiguration påverkar inte konfigurationen IWebHostBuilder .

Åsidosätta konfigurationen som tillhandahålls av UseUrls med hostsettings.json config first, kommandoradsargument 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"
}

För att specificera värden som körs på en viss URL kan önskat värde anges från ett kommandofönster när du kör dotnet run. Kommandoradsargumentet urls åsidosätter värdet från hostsettings.json filen och servern lyssnar på port 8080:

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

Hantera värd

Springa

Metoden Run startar webbappen och blockerar den anropande tråden tills värdtjänsten stängs av.

host.Run();

Starta

Kör värden i ett icke-blockerande läge genom att anropa dess Start-metod.

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

Om en lista med URL:er skickas till Start metoden lyssnar den på de angivna URL:erna:

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

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

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

Appen kan initiera och starta en ny värd med de förkonfigurerade standardinställningarna CreateDefaultBuilder för att använda en statisk bekvämlighetsmetod. Dessa metoder startar servern utan konsolutdata och väntar WaitForShutdown på en paus (Ctrl-C/SIGINT eller SIGTERM):

Start(RequestDelegate-app)

Börja med en RequestDelegate:

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

Gör en begäran i webbläsaren till http://localhost:5000 för att få svaret "Hello World!" WaitForShutdown blockeras tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

Start(sträng-URL, RequestDelegate-app)

Börja med en URL och 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();
}

Ger samma resultat som Start(RequestDelegate-appen), förutom att appen svarar på http://localhost:8080.

Start(Åtgärd<IRouteBuilder> routeBuilder)

Använd en instans av IRouteBuilder (Microsoft.AspNetCore.Routing) för att använda routning mellanprogram:

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

Använd följande webbläsarbegäranden med exemplet:

Begäran	Svar
http://localhost:5000/hello/Martin	Hej, Martin!
http://localhost:5000/buenosdias/Catrina	Buenos dias, Catrina!
http://localhost:5000/throw/ooops!	Genererar ett undantag med strängen "ooops!"
http://localhost:5000/throw	Utlöser ett undantag med strängen "Uh oh!"
http://localhost:5000/Sante/Kevin	Sante, Kevin!
http://localhost:5000	Hej världen!

WaitForShutdown blockerar tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

Start(string url, Action<IRouteBuilder> routeBuilder)

Använd en URL och en instans av 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();
}

Ger samma resultat som Start(Action<IRouteBuilder> routeBuilder), förutom att appen svarar på http://localhost:8080.

StartWith(åtgärdsappen<IApplicationBuilder> )

Tillhandahåll en delegat för att konfigurera en 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();
}

Gör en begäran i webbläsaren till http://localhost:5000 för att få svaret "Hello World!" WaitForShutdown blockeras tills ett avbrott (Ctrl-C/SIGINT eller SIGTERM) utfärdas. Appen visar meddelandet Console.WriteLine och väntar på en tangenttryckning för att avsluta.

StartWith(string URL, Action<IApplicationBuilder> app)

Ange en URL och ett ombud för att konfigurera en 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();
}

Ger samma resultat som StartWith(Action<IApplicationBuilder>-appen), förutom att appen svarar på http://localhost:8080.

IWebHostEnvironment-gränssnitt

Gränssnittet IWebHostEnvironment innehåller information om appens webbvärdmiljö. Använd konstruktorinmatning för att hämta IWebHostEnvironment för att använda dess egenskaper och tilläggsmetoder:

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

En konventionsbaserad metod kan användas för att konfigurera appen vid start baserat på miljön. Alternativt kan du mata in IWebHostEnvironment i konstruktorn Startup för att använda i 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;
    }
}

Tjänsten IWebHostEnvironment kan också matas in direkt i Configure metoden för att konfigurera bearbetningspipelinen:

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 matas in i Invoke metoden när du skapar anpassade mellanprogram:

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

IHostApplicationLifetime-gränssnitt

IHostApplicationLifetime tillåter aktiviteter efter start och avstängning. Tre egenskaper i gränssnittet är annulleringstoken som används för att registrera Action metoder som definierar start- och avstängningshändelser.

Annullerings-token	Utlöses när...
ApplicationStarted	Värden har startat fullt.
ApplicationStopped	Värden slutför en graciös avstängning. Alla begäranden ska bearbetas. Nedstängningen blockeras tills den här händelsen har slutförts.
ApplicationStopping	Värden utför en graciös avstängning. Begäranden kan fortfarande bearbetas. Nedstängningen blockeras tills den här händelsen har slutförts.

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 begär avslutning av appen. Följande klass använder StopApplication för att på ett smidigt sätt stänga av en app när klassens -metod anropas Shutdown :

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Omfångsverifiering

CreateDefaultBuilder ställer in ServiceProviderOptions.ValidateScopes om true appens miljö är Utvecklingsmiljö.

När ValidateScopes är inställt truepå utför standardtjänstleverantören kontroller för att kontrollera att:

• Tjänster med begränsad omfattning löses inte direkt eller indirekt från grundserviceleverantören.
• Tjänster med begränsat omfång injiceras inte direkt eller indirekt i singletons.

Rottjänstprovidern skapas när BuildServiceProvider anropas. Rottjänstleverantörens livslängd motsvarar appens/serverns livslängd när providern börjar med appen och tas bort när appen stängs av.

Tjänster med avgränsat omfång avvecklas av den container som skapade dem. Om en begränsad tjänst skapas i rotcontainern höjs tjänstens livslängd effektivt till singleton eftersom den endast tas bort av rotcontainern när appen/servern stängs av. Validering av tjänstens omfång identifierar dessa situationer när BuildServiceProvider anropas.

Om du alltid vill validera omfång, inklusive i produktionsmiljön, konfigurerar du ServiceProviderOptions med UseDefaultServiceProvider på värdbyggaren:

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

Ytterligare resurser

• Köra ASP.NET Core på Windows med IIS
• Hosting av ASP.NET Core på Linux med Nginx
• Driva ASP.NET Core som en Windows-tjänst