.NET Általános Gazdagép az ASP.NET Core-ban

Cikk
02/03/2025

Jegyzet

Ez nem a cikk legújabb verziója. Az aktuális kiadásért lásd ennek a cikknek a .NET 9-es verzióját.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információ: .NET és .NET Core támogatási szabályzat. Lásd az aktuális kiadást a jelen cikk .NET 9-es verziójában.

Fontos

Ezek az információk egy olyan előzetes termékre vonatkoznak, amelyet a kereskedelmi forgalomba kerülés előtt jelentősen módosíthatnak. A Microsoft nem vállal kifejezett vagy hallgatólagos szavatosságot az itt megadott információkra vonatkozóan.

Az aktuális kiadáshoz lásd a jelen cikk .NET 9-es verzióját.

Ez a cikk a .NET Általános gazdagép ASP.NET Core-ban való használatáról nyújt tájékoztatást.

A ASP.NET Core-sablonok létrehoznak egy WebApplicationBuilder és WebApplication, amely leegyszerűsíti a webalkalmazások Startup osztály nélküli konfigurálását és futtatását. A WebApplicationBuilder és WebApplicationtovábbi információkért lásd: Áttelepítés ASP.NET Core 5.0-ról 6.0-ra.

A .NET Generic Host konzolalkalmazásokban való használatáról további információt .NET Generic Hosttémakörben olvashat.

Hoszt definíció

A host olyan tárgy, amely egy alkalmazás erőforrásait foglalja magában, például:

Függőséginjektálás (DI)
Fakitermelés
Konfiguráció
IHostedService implementációk

Amikor egy hoszt elindul, a szolgáltatástárolóban regisztrált üzemeltetett szolgáltatások gyűjteményében lévő minden IHostedService implementáción meghívja a IHostedService.StartAsync-t. Egy webalkalmazás egyik IHostedService implementációja egy webszolgáltatás, amely elindít egy HTTP-kiszolgáló implementációt.

Az alkalmazás minden egymástól függő erőforrásának egy objektumba való belefogalmazásával szabályozható az alkalmazás indítása és a kecses leállítás.

Gazdagép beállítása

A gazdagép általában a Program.cskóddal van konfigurálva, létrehozva és futtatva. Az alábbi kód létrehoz egy gazdagépet, amelyhez egy IHostedService implementáció kerül hozzáadásra a DI konténerbe.

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

HTTP-számítási feladat esetén hívja meg ConfigureWebHostDefaults CreateDefaultBuilderután:

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

Alapértelmezett szerkesztőbeállítások

A CreateDefaultBuilder módszer:

A(z) tartalomgyökérként állítja be a-et a GetCurrentDirectoryáltal visszaadott elérési útra.
A gazdagép konfigurációját a következő helyről tölti be:
- A DOTNET_előtaggal ellátott környezeti változók.
- Parancssori argumentumok.
Betölti az alkalmazáskonfigurációt a következőből:
- appsettings.json.
- appsettings.{Environment}.json.
- felhasználói titkos kódok, amikor az alkalmazás a Development környezetben fut.
- Környezeti változók.
- Parancssori argumentumok.
A következő naplózási szolgáltatókat adja hozzá:
- Konzol
- Hibakeresés
- EventSource
- EventLog (csak Windows rendszeren futtatva)
Engedélyezi a(z) hatókör érvényesítését és a(z) függőség érvényesítését, ha a környezet fejlesztési.

A ConfigureWebHostDefaults módszer:

Betölti a gazdagép konfigurációját a ASPNETCORE_előtagú környezeti változókból.
Webkiszolgálóként állítja be Kestrel kiszolgálót, és az alkalmazás üzemeltetési konfigurációs szolgáltatóinak használatával konfigurálja. A Kestrel kiszolgáló alapértelmezett beállításaiért lásd A ASP.NET Core Kestrel webkiszolgálóbeállításainak konfigurálása című témakört.
Hozzáadja gazdagépszűrési köztes szoftver.
Hozzáadja Továbbított fejlécek köztes szoftver, ha ASPNETCORE_FORWARDEDHEADERS_ENABLED egyenlő true.
Engedélyezi az IIS-integrációt. Az IIS alapértelmezett beállításaiért lásd: ASP.NET Core tárhely szolgáltatás Windows rendszeren IIS-sel.

A cikk későbbi szakaszaiban a Minden alkalmazástípus beállításai és Webalkalmazások beállításai bemutatják, hogyan bírálhatja felül az alapértelmezett építőbeállításokat.

Keretrendszer által biztosított szolgáltatások

A rendszer automatikusan regisztrálja a következő szolgáltatásokat:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment/IWebHostEnvironment

A keretrendszer által biztosított szolgáltatásokról további információt az ASP.NET Core függőséginjektálásában talál.

IHostApplicationLifetime

A IHostApplicationLifetime (korábban IApplicationLifetime) szolgáltatást bármely osztályba injektálhatja az indítás utáni és a kecses leállítási feladatok kezeléséhez. A felületen három tulajdonság van, amelyek lemondási tokeneket használnak az alkalmazásindítási és alkalmazásleállítási eseménykezelő metódusok regisztrálásához. A felület egy StopApplication metódust is tartalmaz, amely lehetővé teszi az alkalmazások számára, hogy zavartalan leállítást kérjenek.

Kifinomult leállítás végrehajtásakor a gazdagép:

Aktiválja a ApplicationStopping eseménykezelőket, amelyek lehetővé teszik az alkalmazás számára a logika futtatását a leállítási folyamat megkezdése előtt.
Leállítja a kiszolgálót, amely letiltja az új kapcsolatokat. A kiszolgáló megvárja, amíg befejeződnek a meglévő kapcsolatokra vonatkozó kérések, mindaddig, amíg azt a leállítási időtúllépési engedélyezi. A kiszolgáló elküldi a kapcsolat bezárása fejlécet a meglévő kapcsolatokra vonatkozó további kérésekhez.
Aktiválja a ApplicationStopped eseménykezelőket, amelyek lehetővé teszik az alkalmazás számára a logika futtatását az alkalmazás leállítása után.

Az alábbi példa egy IHostedService implementáció, amely IHostApplicationLifetime eseménykezelőket regisztrál:

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
        _hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
        _hostApplicationLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

A IHostLifetime implementáció vezérli, hogy mikor indul el a host rendszer, és mikor áll le. A rendszer az utolsó regisztrált implementációt használja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime az alapértelmezett IHostLifetime implementáció. ConsoleLifetime:

Figyeli Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációt, és meghívja StopApplication a leállítási folyamat elindításához.
Feloldja az olyan bővítmények letiltását, mint például RunAsync és WaitForShutdownAsync.

IHostEnvironment

A IHostEnvironment szolgáltatás beszúrása egy osztályba a következő beállításokkal kapcsolatos információk lekéréséhez:

ApplicationName
KörnyezetNév
ContentRootPath

A webalkalmazások a IWebHostEnvironment felületet implementálják, amely örökli a IHostEnvironment-et, és hozzáadja a WebRootPath-at.

Gazdagép konfigurációja

A gazdagépkonfiguráció a IHostEnvironment implementáció tulajdonságaihoz használható.

Gazdakó konfiguráció a HostBuilderContext.Configuration a ConfigureAppConfigurationbelül érhető el. A ConfigureAppConfigurationután a HostBuilderContext.Configuration az alkalmazáskonfigurációra lesz cserélve.

Gazdagépkonfiguráció hozzáadásához hívja a ConfigureHostConfiguration a IHostBuilder-re. ConfigureHostConfiguration az additív eredményekkel többször is meghívható. A gazdagép azt a beállítást alkalmazza, amely legutoljára állított be egy értéket egy adott kulcson.

A DOTNET_ előtaggal és parancssori argumentumokkal rendelkező környezeti változószolgáltatót CreateDefaultBuildertartalmazza. Webalkalmazások esetén a rendszer hozzáadja az ASPNETCORE_ előtaggal rendelkező környezeti változószolgáltatót. A környezeti változók beolvasásakor az előtag el lesz távolítva. Az ASPNETCORE_ENVIRONMENT környezeti változó értéke például a environment kulcs gazdagépkonfigurációs értéke lesz.

Az alábbi példa gazdagépkonfigurációt hoz létre:

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(hostConfig =>
    {
        hostConfig.SetBasePath(Directory.GetCurrentDirectory());
        hostConfig.AddJsonFile("hostsettings.json", optional: true);
        hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
        hostConfig.AddCommandLine(args);
    });

Alkalmazáskonfiguráció

Az alkalmazáskonfiguráció a(z) ConfigureAppConfiguration hívásával jön létre a IHostBuilder-on. ConfigureAppConfiguration az additív eredményekkel többször is meghívható. Az alkalmazás bármelyik beállítással állít be egy értéket egy adott kulcsra.

A ConfigureAppConfiguration által létrehozott konfiguráció elérhető a HostBuilderContext.Configuration-nél a későbbi műveletekhez és szolgáltatásként a DI által. A hoszt konfigurációja az alkalmazáskonfigurációhoz is hozzáadódik.

További információ: ASP.NET Corekonfigurációja.

Az összes alkalmazástípus beállításai

Ez a szakasz a HTTP- és nem HTTP-számítási feladatokra egyaránt érvényes gazdagépbeállításokat sorolja fel. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a beállítások alábbi listájában {PREFIX_} helyőrzőként jelennek meg. További információ: Alapértelmezett szerkesztő beállításai szakasz és Konfiguráció: Környezeti változók.

ApplicationName

A IHostEnvironment.ApplicationName tulajdonság a gazdagép beállításaiból van megadva a gazdagép létrehozásakor.

kulcs: applicationName
Típus: string
Alapértelmezett: Az alkalmazás belépési pontját tartalmazó szerelvény neve.
környezeti változó: {PREFIX_}APPLICATIONNAME

Az érték beállításához használja a környezeti változót.

ContentRoot

A IHostEnvironment.ContentRootPath tulajdonság határozza meg, hogy a gazdagép hol kezd tartalomfájlokat keresni. Ha az elérési út nem létezik, a szerver nem indul el.

kulcs: contentRoot
Típus: string
Alapértelmezett: Az a mappa, amelyben az alkalmazásszerelvény található.
környezeti változó: {PREFIX_}CONTENTROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseContentRootIHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

További információ:

KörnyezetNév

A IHostEnvironment.EnvironmentName tulajdonság bármilyen értékre beállítható. A keretrendszer által definiált értékek közé tartozik a Development, a Stagingés a Production. Az értékek nem érzékenyek a kis- és nagybetűkre.

kulcs: environment
Típus: string
alapértelmezett: Production
környezeti változó: {PREFIX_}ENVIRONMENT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseEnvironmentIHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    // ...

Kikapcsolási időkorlát

HostOptions.ShutdownTimeout beállítja a StopAsyncidőtúllépési idejét. Az alapértelmezett érték 30 másodperc. Az időtúllépési időszak alatt a gazdagép:

Eseményindítók IHostApplicationLifetime.ApplicationStopping.
Megkísérli leállítani az üzemeltetett szolgáltatásokat, és naplózza azokat a hibákat, amelyek a szolgáltatások leállítása során jelentkeznek.

Ha az időtúllépési időszak az összes üzemeltetett szolgáltatás leállása előtt lejár, a fennmaradó aktív szolgáltatások leállnak az alkalmazás leállásakor. A szolgáltatások akkor is leállnak, ha még nem fejezték be a feldolgozást. Ha a szolgáltatások leállítása több időt igényel, növelje az időkorlátot.

kulcs: shutdownTimeoutSeconds
Típus: int
alapértelmezett: 30 másodperc
környezeti változó: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Az érték beállításához használja a környezeti változót, vagy konfigurálja HostOptions. Az alábbi példa 20 másodpercre állítja be az időtúllépést:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(options =>
        {
            options.ShutdownTimeout = TimeSpan.FromSeconds(20);
        });
    });

Alkalmazáskonfiguráció újrabetöltésének letiltása a módosításhoz

Alapértelmezés szerint ,, appsettings.json és appsettings.{Environment}.json újratöltődnek a fájl módosításakor. Ha le szeretné tiltani ezt az újratöltési viselkedést ASP.NET Core 5.0-s vagy újabb verziójában, állítsa a hostBuilder:reloadConfigOnChange billentyűt falseértékre.

kulcs: hostBuilder:reloadConfigOnChange
Típus: bool (true vagy false)
alapértelmezett: true
parancssori argumentum: hostBuilder:reloadConfigOnChange
környezeti változó: {PREFIX_}hostBuilder:reloadConfigOnChange

Figyelmeztetés

A kettőspont (:) elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. További információ: Környezeti változók.

Webalkalmazások beállításai

Egyes gazdagépbeállítások csak HTTP terhelésekre vonatkoznak. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a beállítások alábbi listájában {PREFIX_} helyőrzőként jelennek meg.

A IWebHostBuilder bővítménymetelyei ezekhez a beállításokhoz érhetők el. A bővítménymetelyek meghívását bemutató kódminták feltételezik, hogy webBuilderIWebHostBuilderegy példánya, ahogyan az alábbi példában is látható:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

CaptureStartupErrors

Ha false, az indítás során előforduló hibák a gazdagép kilépését okozzák. Ha true, a gazdagép rögzíti a kivételeket az indításkor, és megpróbálja elindítani a kiszolgálót.

kulcs: captureStartupErrors
Típus: bool (true/1 vagy false/0)
Alapértelmezett: Alapértelmezés szerint false, kivéve, ha az alkalmazás az IIS mögött Kestrel módban fut, ahol az alapértelmezett érték true.
környezeti változó: {PREFIX_}CAPTURESTARTUPERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Részletes hibák

Ha engedélyezve van, vagy ha a környezet Development, az alkalmazás részletes hibákat rögzít.

kulcs: detailedErrors
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}DETAILEDERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

Az indításkor betöltendő, pontosvesszővel elválasztott összeállítások karakterlánca. Bár a konfigurációs érték alapértelmezett értéke egy üres sztring, az üzemeltetési indítási szerelvények mindig tartalmazzák az alkalmazás szerelvényét. Ha biztosítják az indítási szerelvényeket, azokat az alkalmazás szerelvényéhez adják hozzá, hogy betöltődhessenek, amikor az alkalmazás az indítás során létrehozza a közös szolgáltatásait.

kulcs: hostingStartupAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

Indításkor kizárandó, pontosvesszővel elválasztott, hosting indító szerelvények sztringje.

kulcs: hostingStartupExcludeAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

Állítsa be a HTTPS-portot, amelyre átirányít, ha nem HTTPS-kapcsolatot észlel. A HTTPS-kényszerítésénél használt. Ez a beállítás nem okozza, hogy a kiszolgáló a megadott porton figyel. Ez azt is lehetővé teszi, hogy véletlenül átirányítsa a kéréseket egy nem használt portra.

kulcs: https_portTípus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORT

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting("https_port", "8080");

HTTPS_Ports

A HTTPS-kapcsolatok figyeléséhez használt portok.

kulcs: https_ports
Típus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORTS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting("https_ports", "8080");

Hostolási URL-ek preferálása

Azt jelzi, hogy figyelnie kell-e a gazdagépnek a IWebHostBuilder-val konfigurált URL-címekre a IServer megvalósítással konfigurált URL-címek helyett.

kulcs: preferHostingUrls
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREFERHOSTINGURLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Megakadályozza a hosztindító szerelvények automatikus betöltését, beleértve az alkalmazás szerelvénye által konfigurált hosztindító szerelvényeket is. További információért lásd: Indítási összetevők üzemeltetése az ASP.NET Core-ban.

billentyű: preventHostingStartup
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREVENTHOSTINGSTARTUP

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

A Startup osztály keresésére szolgáló összeállítás.

kulcs: startupAssembly
Típus: string
Alapértelmezett: Az alkalmazás összeállítása
környezeti változó: {PREFIX_}STARTUPASSEMBLY

Az érték beállításához használja a környezeti változót, vagy hívja meg UseStartup. UseStartup szerelvénynevet (string) vagy típust (TStartup) vehet fel. Ha több UseStartup metódust hív meg, az utolsó élvez elsőbbséget.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Ha engedélyezve van, elnyomja a hosztolási indítási állapotüzeneteket.

kulcs: suppressStatusMessages
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}SUPPRESSSTATUSMESSAGES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

URL-címek

Pontosvesszővel tagolt IP-címek vagy gazdagépcímek listája, amelyekhez tartozó portokkal és protokollokkal a kiszolgálónak figyelnie kell a kéréseket. Például http://localhost:123. A "*" használatával jelezheti, hogy a kiszolgálónak a megadott port és protokoll (például http://*:5000) használatával kell figyelnie a kéréseket bármely IP-címen vagy gazdagépnéven. A protokollt (http:// vagy https://) minden URL-címhez hozzá kell adni. A támogatott formátumok kiszolgálók között eltérőek lehetnek.

kulcs: urls
Típus: string
Alapértelmezett: http://localhost:5000 és https://localhost:5001
környezeti változó: {PREFIX_}URLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseUrls:

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

Kestrel saját végpontkonfigurációs API-val rendelkezik. További információ: Az ASP.NET Core Kestrel webkiszolgáló végpontjainak konfigurálása.

WebRoot

Az IWebHostEnvironment.WebRootPath tulajdonság határozza meg az alkalmazás statikus eszközeinek relatív elérési útját. Ha az elérési út nem létezik, a rendszer egy no-op fájlszolgáltatót használ.

kulcs: webroot
Típus: string
Alapértelmezett: Az alapértelmezett wwwroot. A elérési útnak {content root}/wwwroot léteznie kell.
környezeti változó: {PREFIX_}WEBROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

További információ:

A gazdagép élettartamának kezelése

Az alkalmazás elindításához és leállításához hívja meg a beépített IHost implementáció metódusait. Ezek a módszerek a szolgáltatástárolóban regisztrált összes IHostedService implementációra hatással vannak.

A Run* és Start* metódusok között az a különbség, hogy a Run* metódusok megvárják, amíg a gazdagép befejezi a műveleteit a visszatérés előtt, míg a Start* metódusok azonnal visszatérnek. A Run* metódusokat általában konzolalkalmazásokban használják, míg a Start* metódusokat általában hosszú ideig futó szolgáltatásokban használják.

Fut

Run futtatja az alkalmazást, és letiltja a hívó szálat, amíg a gazdagép le nem áll.

RunAsync

RunAsync futtatja az alkalmazást, és visszaad egy Task-et, amely befejeződik a lemondási token vagy a leállítás aktiválásakor.

RunConsoleAsync

RunConsoleAsync lehetővé teszi a konzol támogatását, létrehozza és elindítja a gazdagépet, és megvárja, amíg a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy a SIGTERM leáll.

Elkezd

Start szinkron módon indítja el a "hostot".

StartAsync

StartAsync elindítja a gazdagépet, és visszaad egy Task-et, amely akkor fejeződik be, amikor a lemondási token vagy a leállítás aktiválódik.

WaitForStartAsync a StartAsyncelején hívásra kerül, és StartAsyncmegvárja a befejezést, mielőtt folytatná. Ezzel a módszerrel késleltetheti az indítást, amíg egy külső esemény nem jelzi.

StopAsync

StopAsync megkísérli leállítani a gazdagépet a megadott időkorláton belül.

Várakozás leállításra

WaitForShutdown blokkolja a hívószálat, amíg az IHostLifetime által meg nem történik a leállítás, például a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációval.

WaitForShutdownAsync

WaitForShutdownAsync egy Task ad vissza, amely akkor fejeződik be, amikor a leállítás a megadott jogkivonaton keresztül aktiválódik, és meghívja StopAsync.

Az ASP.NET Core-sablonok létrehoznak egy .NET Core Generic Hostot (HostBuilder).

Ez a cikk a .NET Generic Host ASP.NET Core-ban való használatáról nyújt tájékoztatást. A .NET Generic Host konzolalkalmazásokban való használatáról további információt a .NET Generic Host című témakörben talál.

Hoszt definíció

A gazdagép olyan objektum, amely egy alkalmazás erőforrásait foglalja magában, például:

Függőséginjektálás (DI)
Fakitermelés
Konfiguráció
IHostedService implementációk

Amikor egy gazdagép elindul, meghívja IHostedService.StartAsync a szolgáltatástároló üzemeltetett szolgáltatások gyűjteményében regisztrált IHostedService minden implementációjára. A webalkalmazások egyik IHostedService implementációja egy webszolgáltatás, amely elindítja egy HTTP-szerver implementáció-t.

Az alkalmazás összes egymástól függő erőforrásának egy objektumba való belefogalmazásának fő oka az élettartam-kezelés: az alkalmazásindítás és a kecses leállítás vezérlése.

Kiszolgáló beállítása

A gazdagépet jellemzően a Program osztályban lévő kód konfigurálja, készíti el és futtatja. A Main módszer:

Meghív egy CreateHostBuilder metódust egy szerkesztőobjektum létrehozásához és konfigurálásához.
Meghívja Build és Run metódusokat a szerkesztőobjektumon.

Az ASP.NET Core-websablonok a következő kódot generálják egy gazdagép létrehozásához:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Az alábbi kód létrehoz egy nem HTTP-alapú számítási feladatot a DI-tárolóhoz hozzáadott IHostedService-implementációval.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

HTTP-számítási feladatok esetén a Main metódus ugyanaz, de CreateHostBuilder hívások ConfigureWebHostDefaults:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Ha az alkalmazás Entity Framework Core-t használ, ne módosítsa a CreateHostBuilder metódus nevét vagy aláírását. Az Entity Framework Core-eszközök elvárhatóan megkeresnek egy CreateHostBuilder metódust, amely az alkalmazás futtatása nélkül konfigurálja a kiszolgálót. További információért lásd: Tervezési időben létrehozott DbContext.

Alapértelmezett szerkesztőbeállítások

A CreateDefaultBuilder módszer:

A tartalomgyökér a GetCurrentDirectoryáltal visszaadott elérési útra lesz beállítva.
A gazdagép konfigurációját innen tölti be:
- A DOTNET_előtaggal ellátott környezeti változók.
- Parancssori argumentumok.
Betölti az alkalmazáskonfigurációt a következőből:
- appsettings.json.
- appsettings.{Environment}.json.
- felhasználói titkos kódok, amikor az alkalmazás a Development környezetben fut.
- Környezeti változók.
- Parancssori argumentumok.
A következő naplózási szolgáltatókat adja hozzá:
- Konzol
- Hibakeresés
- EventSource
- EventLog (csak Windows rendszeren futtatva)
Engedélyezi a hatókör érvényesítést és függőség érvényesítést, amikor a környezet a Fejlesztési.

A ConfigureWebHostDefaults módszer:

Betölti a gazdagép konfigurációját a ASPNETCORE_előtagú környezeti változókból.
Webkiszolgálóként állítja be Kestrel kiszolgálót, és az alkalmazás üzemeltetési konfigurációs szolgáltatóinak használatával konfigurálja. A Kestrel kiszolgáló alapértelmezett beállításaiért lásd A ASP.NET Core Kestrel webkiszolgálóbeállításainak konfigurálása című témakört.
Hozzáadja a host szűrő middleware-t.
Hozzáadja a Továbbított fejlécek köztes rétegét, ha ASPNETCORE_FORWARDEDHEADERS_ENABLED egyenlő true.
Engedélyezi az IIS-integrációt. Az IIS alapértelmezett beállításaiért tekintse meg a ASP.NET Core tárhely Windows rendszeren IIScímű részt.

A Beállítások minden alkalmazástípushoz és Webalkalmazások beállításai szakaszok a cikk későbbi részeiben bemutatják, hogyan bírálhatja felül az alapértelmezett építő beállításokat.

Keretrendszer által biztosított szolgáltatások

A rendszer automatikusan regisztrálja a következő szolgáltatásokat:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

A keretrendszer által biztosított szolgáltatásokról további információt az ASP.NET Core függőséginjektáláscímű részében talál.

IHostApplicationLifetime

A IHostApplicationLifetime (korábban IApplicationLifetime) szolgáltatást bármely osztályba injektálhatja az indítás utáni és a kecses leállítási feladatok kezeléséhez. A felületen három tulajdonság van, amelyeket lemondási tokenekként használnak az alkalmazás indítási és leállítási eseménykezelő metódusainak regisztrálásához. Az interfész egy StopApplication metódust is tartalmaz.

Az alábbi példa egy IHostedService implementáció, amely IHostApplicationLifetime eseményeket regisztrál:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

A IHostLifetime implementáció szabályozza, hogy a gazdagép mikor indul el és mikor áll le. A rendszer az utolsó regisztrált implementációt használja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime az alapértelmezett IHostLifetime implementáció. ConsoleLifetime:

Figyeli Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációt, és meghívja StopApplication a leállítási folyamat elindításához.
Feloldja az olyan bővítmények letiltását, mint például RunAsync és WaitForShutdownAsync.

IHostEnvironment

A IHostEnvironment szolgáltatás beszúrása egy osztályba a következő beállításokkal kapcsolatos információk lekéréséhez:

ApplicationName
EnvironmentName
ContentRootPath

A webalkalmazások implementálják a IWebHostEnvironment felületet, amely a IHostEnvironment-et örökli, és hozzáadja a WebRootPath-at.

Gazdagép konfigurációja

A gazdagépkonfiguráció a IHostEnvironment implementáció tulajdonságaihoz használható.

A gazda konfiguráció a HostBuilderContext.Configuration-n belül elérhető a ConfigureAppConfiguration-ből. A ConfigureAppConfigurationután a HostBuilderContext.Configuration helyére az alkalmazás beállításai kerülnek.

Gazdagépkonfiguráció hozzáadásához hívja meg ConfigureHostConfiguration a IHostBuilder. ConfigureHostConfiguration az additív eredményekkel többször is meghívható. A gazdagép azt a beállítást használja, amelyik utoljára állít be egy értéket egy adott kulcson.

Az alábbi példa gazdagépkonfigurációt hoz létre:

// using Microsoft.Extensions.Configuration;

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    });

Alkalmazáskonfiguráció

Az alkalmazáskonfiguráció a IHostBuilder-en a ConfigureAppConfiguration meghívásával jön létre. ConfigureAppConfiguration az additív eredményekkel többször is meghívható. Az alkalmazás az utoljára beállított beállítással állít be egy értéket egy adott kulcsra.

A ConfigureAppConfiguration által létrehozott konfiguráció elérhető a HostBuilderContext.Configuration-nél a későbbi műveletekhez, valamint a DI szolgáltatásaként. A kiszolgáló konfigurációja az alkalmazáskonfigurációhoz is hozzáadódik.

További információkért lásd az ASP.NET Core részletes konfigurációs leírását azrészben.

Az összes alkalmazástípus beállításai

AlkalmazásNeve

A IHostEnvironment.ApplicationName tulajdonság a gazdagép konfigurációjából kerül beállításra a gazdagép létrehozása során.

kulcs: applicationName
Típus: string
Alapértelmezett: Az alkalmazás belépési pontját tartalmazó szerelvény neve.
környezeti változó: {PREFIX_}APPLICATIONNAME

Az érték beállításához használja a környezeti változót.

ContentRoot

A IHostEnvironment.ContentRootPath tulajdonság meghatározza, hogy a szerver hol kezdi a tartalomfájlok keresését. Ha az elérési út nem létezik, a kiszolgáló nem indul el.

kulcs: contentRoot
Típus: string
Alapértelmezett: Az a mappa, amelyben az alkalmazásszerelvény található.
környezeti változó: {PREFIX_}CONTENTROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseContentRootIHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

További információ:

KörnyezetiNév

billentyű: environment
Típus: string
alapértelmezett: Production
környezeti változó: {PREFIX_}ENVIRONMENT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseEnvironmentIHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

Leállítási időkorlát

HostOptions.ShutdownTimeout beállítja az időtúllépést a StopAsyncszámára. Az alapértelmezett érték öt másodperc. Az időtúllépési időszak alatt a gazdagép:

Eseményindítók IHostApplicationLifetime.ApplicationStopping.
Megkísérli leállítani az üzemeltetett szolgáltatásokat, és naplózza a hibákat azoknál a szolgáltatásoknál, amelyek nem állnak le.

kulcs: shutdownTimeoutSeconds
Típus: int
Alapértelmezett: 5 másodperc
környezeti változó: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Az érték beállításához használja a környezeti változót, vagy konfigurálja HostOptions. Az alábbi példa 20 másodpercre állítja az időtúllépési időt.

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Alkalmazáskonfiguráció újrabetöltésének letiltása a módosításhoz

Az alapértelmezett appsettings.json és appsettings.{Environment}.json újratöltődnek a fájl módosításakor. Ha le szeretné tiltani ezt az újratöltési viselkedést ASP.NET Core 5.0-s vagy újabb verziójában, állítsa a hostBuilder:reloadConfigOnChange billentyűt falseértékre.

Figyelmeztetés

A kettőspont (:) elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. További információ: Környezeti változók.

Webalkalmazások beállításai

Egyes gazdagépbeállítások csak HTTP-alapú munkaterhelésekre vonatkoznak. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a beállítások alábbi listájában {PREFIX_} helyőrzőként jelennek meg.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

IndításiHibákRögzítése

Ha false, az indítás során előforduló hibák a gazdagép kilépését eredményezik. Ha true, a gazdagép rögzíti a kivételeket az indításkor, és megpróbálja elindítani a kiszolgálót.

kulcs: captureStartupErrors
Típus: bool (true/1 vagy false/0)
Alapértelmezett: Alapértelmezés szerint false, kivéve, ha az alkalmazás az IIS mögött Kestrel-ként fut, ahol az alapértelmezett true.
környezeti változó: {PREFIX_}CAPTURESTARTUPERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Részletes Hibák

Ha engedélyezve van, vagy ha a környezet Development, az alkalmazás részletes hibákat rögzít.

kulcs: detailedErrors
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}DETAILEDERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

Az indításkor betöltendő hosztingindítási szerelvények pontosvesszővel tagolt sztringje. Bár a konfigurációs érték alapértelmezett értéke egy üres karakterlánc, a hosztolási indítási összetevők mindig tartalmazzák az alkalmazás összetevőjét. Amikor indító szerelvényeket biztosítanak, azok hozzáadódnak az alkalmazás szerelvényéhez a betöltéshez, amikor az alkalmazás indítása során létrehozza közös szolgáltatásait.

kulcs: hostingStartupAssemblies
Típus: string
Alapértelmezett: Üres karaktersorozat
környezeti változó: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

TárolásIndításKizáróÖsszeállítások

Az indításkor kizárandó, pontosvesszővel elválasztott hosting indítási egységek sztringje.

kulcs: hostingStartupExcludeAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_port

A HTTPS-átirányítási port. A HTTPS kényszerítésérehasználva.

kulcs: https_port
Típus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORT

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferáltTárhelyURL-ek

Azt jelzi, hogy a gazdagépnek, a IServer alapján beállított URL-címek helyett, a IWebHostBuilder alapján beállított URL-címeket kell-e figyelnie.

gomb: preferHostingUrls
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREFERHOSTINGURLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

HostingIndításMegelőzése

Megakadályozza a hosztolási indítási szerelvények automatikus betöltését, beleértve az alkalmazás szerelvénye által konfigurált hosztolási indítási szerelvényeket is. További információért lásd: Indítási szerelvények használata ASP.NET Core-ban.

kulcs: preventHostingStartup
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREVENTHOSTINGSTARTUP

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

A Startup osztály keresésére szolgáló egység.

kulcs: startupAssembly
Típus: string
Alapértelmezett: Az alkalmazás összeállítása
környezeti változó: {PREFIX_}STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

ÁllapotüzenetekElrejtése

Ha engedélyezve van, elnyomja az üzemeltetési indítási állapotüzeneteket.

kulcs: suppressStatusMessages
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}SUPPRESSSTATUSMESSAGES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

URL-címek

Olyan IP-címek vagy gazdagépcímek listája, amelyeket pontosvessző választ el, és olyan portokkal és protokollokkal rendelkezik, amelyeknél a kiszolgálónak figyelnie kell a kéréseket. Például http://localhost:123. A "*" használatával jelezheti, hogy a kiszolgálónak a megadott port és protokoll (például http://*:5000) használatával kell figyelnie a kéréseket bármely IP-címen vagy gazdagépnéven. A protokollt (http:// vagy https://) minden URL-címhez hozzá kell adni. A támogatott formátumok kiszolgálók között eltérőek lehetnek.

kulcs: urls
Típus: string
Alapértelmezett: http://localhost:5000 és https://localhost:5001
környezeti változó: {PREFIX_}URLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseUrls:

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

Kestrel saját végpontkonfigurációs API-val rendelkezik. További információkért lásd: Végpontok konfigurálása az ASP.NET Core Kestrel webkiszolgáló számára.

WebRoot

kulcs: webroot
Típus: string
Alapértelmezett: Az alapértelmezett érték wwwroot. A(z) {content root}/wwwroot elérési útjának léteznie kell.
környezeti változó: {PREFIX_}WEBROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

További információ:

A gazdagép élettartamának kezelése

A Run* és Start* módszerek között az a különbség, hogy a Run* módszerek a visszatérés előtt megvárják a gazdagép befejezését, míg a Start* módszerek azonnal visszatérnek. A Run* metódusokat általában konzolalkalmazásokban használják, míg a Start* metódusokat általában hosszú ideig futó szolgáltatásokban használják.

Fut

Run futtatja az alkalmazást, és letiltja a hívó szálat, amíg a gazdagép le nem áll.

RunAsync

RunAsync futtatja az alkalmazást, és visszaad egy Task-et, amely befejeződik a törlési token vagy a leállítás aktiválásakor.

RunConsoleAsync

RunConsoleAsync lehetővé teszi a konzol támogatását, létrehozza és elindítja a gazdagépet, és megvárja, amíg a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy a SIGTERM leáll.

Kezdés

Start szinkron módon indítja a gazdagépet.

StartAsync

StartAsync elindítja a gazdagépet, és visszaad egy Task-et, amely befejeződik, amikor a megszakítási token vagy a leállítás aktiválódik.

WaitForStartAsync-t a StartAsyncelején hívják meg, amely megvárja, amíg teljes nem lesz, mielőtt folytatódik. Ezzel a módszerrel késleltetheti az indítást, amíg egy külső esemény nem jelzi.

StopAsync

StopAsync megkísérli leállítani a gazdagépet a megadott időkorláton belül.

VárakozásLeállításra

WaitForShutdown blokkolja a hívó szálat, amíg az IHostLifetime leállítást nem indít, például a Ctrl+C/SIGINT (Windows), a Ctrl+C (macOS) vagy a SIGTERM billentyűkombinációval.

WaitForShutdownAsync

WaitForShutdownAsync egy Task-et ad vissza, amely befejeződik, amikor a megadott tokenen keresztül aktiválódik a leállítás, és meghívja StopAsync-t.

Külső vezérlő

A gazdagép élettartamának közvetlen vezérlése külsőleg hívható metódusokkal érhető el:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

Az ASP.NET Core-sablonok létrehoznak egy .NET Core Generikus Gazdagépet (HostBuilder).

Hoszt definíció

A gazdagép olyan objektum, amely egy alkalmazás erőforrásait foglalja magában, például:

Függőséginjektálás (DI)
Fakitermelés
Konfiguráció
IHostedService implementációk

Amikor egy gazdagép elindul, a IHostedService.StartAsync hívja meg a(z) IHostedService minden implementációját, amelyek a szolgáltatáskonténer üzemeltetett szolgáltatások gyűjteményében vannak regisztrálva. A webalkalmazások egyik IHostedService implementációja egy webszolgáltatás, amely elindít egy HTTP-kiszolgáló implementációt.

Az alkalmazás összes egymástól függő erőforrásának egy objektumba való belefogalmazásának fő oka az élettartam-kezelés: az alkalmazásindítás és a kecses leállítás vezérlése.

Host szerver beállítása

A gazdagépet általában az Program osztály kódja alapján konfigurálják, építik fel és futtatják. A Main módszer:

Meghív egy CreateHostBuilder metódust egy szerkesztőobjektum létrehozásához és konfigurálásához.
Meghívja Build és Run metódusokat a szerkesztőobjektumon.

Az ASP.NET Core websablonok a következő kódot hozzák létre egy generikus gazdagép létrehozásához.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Az alábbi kód létrehoz egy általános gazdagépet nem HTTP-alapú számítási feladat használatával. A IHostedService implementáció hozzáadódik a DI-tárolóhoz:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

HTTP-terhelés esetén a Main metódus ugyanaz, de a CreateHostBuilder hívja a ConfigureWebHostDefaults.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Az előző kódot a ASP.NET Core-sablonok generálják.

Ha az alkalmazás Entity Framework Core-t használ, ne módosítsa a CreateHostBuilder metódus nevét vagy aláírását. Az Entity Framework Core-eszközök várhatóan találnak egy CreateHostBuilder metódust, amely az alkalmazás futtatása nélkül konfigurálja a gazdagépet. További információért lásd a(z) 'Tervezés idejű DbContext létrehozása'.

Alapértelmezett szerkesztőbeállítások

A CreateDefaultBuilder módszer:

A tartalomgyökeret a GetCurrentDirectoryáltal visszaadott elérési útra állítja be.
A gazdagép beállításait innen tölti be:
- A DOTNET_előtaggal ellátott környezeti változók.
- Parancssori argumentumok.
Betölti az alkalmazáskonfigurációt a következőből:
- appsettings.json.
- appsettings.{Environment}.json.
- felhasználói titkos kódok, amikor az alkalmazás a Development környezetben fut.
- Környezeti változók.
- Parancssori argumentumok.
A következő naplózási szolgáltatókat adja hozzá:
- Konzol
- Hibakeresés
- Eseményforrás
- EventLog (csak Windows rendszeren futtatva)
Engedélyezi a hatókör-érvényesítést és a függőség-érvényesítést, amikor a környezet fejlesztési.

A ConfigureWebHostDefaults módszer:

Betölti a gazdagép konfigurációját a ASPNETCORE_előtagú környezeti változókból.
Webkiszolgálóként állítja be Kestrel kiszolgálót, és az alkalmazás üzemeltetési konfigurációs szolgáltatóinak használatával konfigurálja. A Kestrel kiszolgáló alapértelmezett beállításaiért lásd Kestrel webkiszolgálót ASP.NET Core.
Hozzáadja a gazdagépszűrő köztes réteget.
Hozzáadja a Továbbított fejlécek köztes rétegét, ha ASPNETCORE_FORWARDEDHEADERS_ENABLED egyenlő true.
Engedélyezi az IIS-integrációt. Az IIS alapértelmezett beállításaiért lásd: ASP.NET Core tárolása a Windows rendszeren IIS.

A Beállítások minden alkalmazástípushoz és WebAlkalmazások beállításai jelen cikk későbbi szakaszai bemutatják, hogyan bírálhatja felül az alapértelmezett szerkesztőbeállításokat.

Keretrendszer által biztosított szolgáltatások

A rendszer automatikusan regisztrálja a következő szolgáltatásokat:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment/IWebHostEnvironment

A keretrendszer által biztosított szolgáltatásokról további információt a ASP.NET Core függőséginjektálásában talál.

IHostApplicationLifetime

A IHostApplicationLifetime (korábban IApplicationLifetime) szolgáltatást bármely osztályba injektálhatja az indítás utáni és a kecses leállítási feladatok kezeléséhez. Az interfészen három tulajdonság található, amelyek az alkalmazás indítása és leállítása eseménykezelő metódusainak regisztrálására szolgáló lemondási tokenek. Az interfész egy StopApplication metódust is tartalmaz.

Az alábbi példa egy IHostedService implementáció, amely IHostApplicationLifetime eseményeket regisztrál:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

A IHostLifetime implementáció szabályozza, hogy mikor indul el a gazdagép, és mikor áll le. A rendszer az utolsó regisztrált implementációt használja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime az alapértelmezett IHostLifetime implementáció. ConsoleLifetime:

Figyeli Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációt, és meghívja StopApplication a leállítási folyamat elindításához.
Feloldja az olyan bővítmények letiltását, mint például RunAsync és WaitForShutdownAsync.

IHostEnvironment

A IHostEnvironment szolgáltatás beszúrása egy osztályba a következő beállításokkal kapcsolatos információk lekéréséhez:

ApplicationName
KörnyezetNeve
ContentRootPath

A webalkalmazások implementálják a IWebHostEnvironment felületet, amely örökli a IHostEnvironment-et, és hozzáadja a WebRootPath-at.

Gazdagép konfiguráció

A gazdagépkonfigurációt a IHostEnvironment implementáció tulajdonságaihoz használják.

A gazda konfiguráció elérhető a HostBuilderContext.Configuration belül ConfigureAppConfiguration. A ConfigureAppConfigurationután a HostBuilderContext.Configuration az alkalmazáskonfigurációra cserélődik.

Az alábbi példa hosztkonfigurációt hoz létre:

// using Microsoft.Extensions.Configuration;

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    });

Alkalmazáskonfiguráció

Az alkalmazáskonfiguráció létrejön a IHostBuilderConfigureAppConfiguration meghívásával. ConfigureAppConfiguration az additív eredményekkel többször is meghívható. Az alkalmazás a legutolsó beállítást használja, amely értéket állít be egy adott kulcsra.

A ConfigureAppConfiguration által létrehozott konfiguráció elérhető a HostBuilderContext.Configuration-nél a későbbi műveletekhez és szolgáltatásként a DI által. A kiszolgáló konfigurációja az alkalmazáskonfigurációhoz is hozzáadódik.

További információért lásd az ASP.NET Core konfigurációját.

Az összes alkalmazástípus beállításai

Ez a szakasz a HTTP- és nem HTTP-számítási feladatokra egyaránt érvényes gazdagépbeállításokat sorolja fel. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a {PREFIX_} helyőrző következő konfigurációjában jelennek meg.

AlkalmazásNeve

A IHostEnvironment.ApplicationName tulajdonság a gazdagép konfigurációjából van beállítva a gazdagép létrehozása során.

kulcs: applicationName
Típus: string
Alapértelmezett: Az alkalmazás belépési pontját tartalmazó szerelvény neve.
környezeti változó: {PREFIX_}APPLICATIONNAME

Az érték beállításához használja a környezeti változót.

ContentRoot

A IHostEnvironment.ContentRootPath tulajdonság határozza meg, hogy a gazdagép hol kezd tartalomfájlokat keresni. Ha az elérési út nem létezik, a gazdagép nem indul el.

kulcs: contentRoot
Típus: string
Alapértelmezett: Az a mappa, amelyben az alkalmazásszerelvény található.
környezeti változó: {PREFIX_}CONTENTROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseContentRootIHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

További információ:

KörnyezetiNév

kulcs: environment
Típus: string
alapértelmezett: Production
környezeti változó: {PREFIX_}ENVIRONMENT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseEnvironmentIHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

Leállási időkorlát

HostOptions.ShutdownTimeout beállítja a StopAsyncidőtúllépését. Az alapértelmezett érték öt másodperc. A szünet ideje alatt a házigazda:

Eseményindítók IHostApplicationLifetime.ApplicationStopping.
Megkísérli leállítani az üzemeltetett szolgáltatásokat, és naplózza a hibákat azoknál a szolgáltatásoknál, amelyek nem állnak le.

kulcs: shutdownTimeoutSeconds
Típus: int
Alapértelmezett: 5 másodperc
környezeti változó: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Az érték beállításához használja a környezeti változót, vagy konfigurálja HostOptions. Az alábbi példa 20 másodpercesre állítja az időtúllépést.

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Webalkalmazások beállításai

Egyes gazdagépbeállítások csak a HTTP-munkaterhelésekre vonatkoznak. A beállítások konfigurálásához használt környezeti változók alapértelmezés szerint DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

IndításiHibákRögzítése

gomb: captureStartupErrors
Típus: bool (true/1 vagy false/0)
Alapértelmezett: Alapértelmezés szerint false, kivéve, ha az alkalmazás az IIS mögötti Kestrel fut, ahol az alapértelmezett érték true.
környezeti változó: {PREFIX_}CAPTURESTARTUPERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

RészletesHibák

Ha engedélyezve van, vagy ha a környezet Development, az alkalmazás részletes hibákat rögzít.

kulcs: detailedErrors
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}DETAILEDERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

Az indításkor betöltendő szerelvények pontosvesszővel tagolt karakterlánca. Bár a konfiguráció alapértelmezett értéke egy üres karakterlánc, az üzemeltetési indítási összetevők mindig tartalmazzák az alkalmazás összetevőjét. Amikor a hosztolási indító összeállítások rendelkezésre állnak, az alkalmazás összeállításához adjuk hozzá őket, hogy betöltődhessenek, amikor az alkalmazás az indítás során létrehozza a közös szolgáltatásait.

kulcs: hostingStartupAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

Az indításkor kizárt alkalmazásösszetevők pontosvesszővel tagolt szövege.

kulcs: hostingStartupExcludeAssemblies
Típus: string
Alapértelmezett: Üres sztring
környezeti változó: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

A HTTPS-átirányítási port. Az használatos a HTTPS-kényszerítésére.

kulcs: https_port
Típus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORT

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting("https_port", "8080");

Előnyben részesített hosztolási URL-ek

Azt jelzi, hogy a gazdagépnek a IServer implementációval konfigurált URL-címek helyett a IWebHostBuilder konfigurált URL-címeket kell-e figyelnie.

kulcs: preferHostingUrls
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREFERHOSTINGURLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Megakadályozza a hosztoló indítószerelvények automatikus betöltését, beleértve az alkalmazás szerelvénye által konfiguráltakat is. További információért lásd: Indítás összeállítások használata az ASP.NET Core alkalmazásban.

kulcs: preventHostingStartup
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREVENTHOSTINGSTARTUP

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

A Startup osztály keresésére szolgáló összeállítás.

kulcs: startupAssembly
Típus: string
Alapértelmezett: Az alkalmazás összeállítása
környezeti változó: {PREFIX_}STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

Állapotüzenetek elnyomása

Ha engedélyezve van, elnyomja a hosztolás indítási állapotüzeneteit.

kulcs: suppressStatusMessages
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}SUPPRESSSTATUSMESSAGES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

URL-címek

Pontosvesszővel tagolt IP-címek vagy gazdagépcímek pontosvesszővel tagolt listája olyan portokkal és protokollokkal, amelyekre a kiszolgálónak figyelnie kell a kéréseket. Például http://localhost:123. A "*" használatával jelezheti, hogy a kiszolgálónak a megadott port és protokoll (például http://*:5000) használatával kell figyelnie a kéréseket bármely IP-címen vagy gazdagépnéven. A protokollt (http:// vagy https://) minden URL-címhez hozzá kell adni. A támogatott formátumok kiszolgálók között eltérőek lehetnek.

kulcs: urls
Típus: string
Alapértelmezett: http://localhost:5000 és https://localhost:5001
környezeti változó: {PREFIX_}URLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseUrls:

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

Kestrel saját végpontkonfigurációs API-val rendelkezik. További információ: az Kestrel webkiszolgáló az ASP.NET Core-ben.

WebRoot

kulcs: webroot
Típus: string
Alapértelmezett: Az alapértelmezett wwwroot. A(z) elérési útnak {content root}/wwwroot léteznie kell.
környezeti változó: {PREFIX_}WEBROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

További információ:

A gazdagép élettartamának kezelése

A Run* és Start* metódusok közötti különbség az, hogy a Run* metódusok megvárják, amíg a gazdagép befejezi a műveleteit, mielőtt visszatérnek, míg a Start* metódusok azonnal visszatérnek. A Run* metódusokat általában konzolalkalmazásokban használják, míg a Start* metódusokat általában hosszú ideig futó szolgáltatásokban használják.

Fuss

Run futtatja az alkalmazást, és letiltja a hívó szálat, amíg a gazdagép le nem áll.

RunAsync

RunAsync futtatja az alkalmazást, és visszaad egy Task, amely befejeződik a lemondási jogkivonat vagy a leállítás aktiválásakor.

RunConsoleAsync

RunConsoleAsync lehetővé teszi a konzol támogatását, létrehozza és elindítja a gazdagépet, és megvárja, amíg a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy a SIGTERM leáll.

Kezd

Start szinkron módon indítja el a gazdagépet.

StartAsync

StartAsync elindítja a gazdagépet, és visszaad egy olyan Task, amely a törlési jogkivonat vagy a leállítás aktiválásakor befejeződik.

WaitForStartAsync a StartAsyncelején hívódik meg, amely megvárja a befejezést, mielőtt folytatódik. Ezzel a módszerrel késleltetheti az indítást, amíg egy külső esemény nem jelzi.

StopAsync

StopAsync megpróbálja leállítani a hostot a megadott időhatáron belül.

WaitForShutdown

WaitForShutdown blokkolja a hívó szálat, amíg a leállítás nem indul el az IHostLifetime által kiváltva, például a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS), vagy a SIGTERM által.

VárakozásLeállásraAszinkron

WaitForShutdownAsync egy Task ad vissza, amely akkor fejeződik be, amikor a leállítás a megadott jogkivonaton keresztül aktiválódik, és meghívja StopAsync.

Külső vezérlő

A gazdagép élettartamának közvetlen vezérlése külsőleg hívható metódusokkal érhető el:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

További erőforrások

Háttérfeladatok az ASP.NET Core üzemeltetett szolgáltatásaival
GitHub-hivatkozás az általános szerver forráskódjához

Jegyzet

A .NET referenciaforrásra mutató dokumentációs hivatkozások általában betöltik az adattár alapértelmezett ágát, amely a .NET következő kiadásának aktuális fejlesztését jelöli. Egy adott kiadás címkéjének kiválasztásához használja az Ágak vagy címkék váltása legördülő listát. További információ: A ASP.NET Core-forráskód (dotnet/AspNetCore.Docs #26205) verziócímkéjének kiválasztása.

Megosztás a következőn keresztül:

.NET Általános Gazdagép az ASP.NET Core-ban

Hoszt definíció

Gazdagép beállítása

Alapértelmezett szerkesztőbeállítások

Keretrendszer által biztosított szolgáltatások

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Gazdagép konfigurációja

Alkalmazáskonfiguráció

Az összes alkalmazástípus beállításai

ApplicationName

ContentRoot

KörnyezetNév

Kikapcsolási időkorlát

Alkalmazáskonfiguráció újrabetöltésének letiltása a módosításhoz

Webalkalmazások beállításai

CaptureStartupErrors

Részletes hibák

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

HTTPS_Ports

Hostolási URL-ek preferálása

PreventHostingStartup

StartupAssembly

SuppressStatusMessages

URL-címek

WebRoot

A gazdagép élettartamának kezelése

Fut

RunAsync

RunConsoleAsync

Elkezd

StartAsync

StopAsync

Várakozás leállításra

WaitForShutdownAsync

Hoszt definíció

Kiszolgáló beállítása

Alapértelmezett szerkesztőbeállítások

Keretrendszer által biztosított szolgáltatások

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Gazdagép konfigurációja

Alkalmazáskonfiguráció

Az összes alkalmazástípus beállításai

AlkalmazásNeve

ContentRoot

KörnyezetiNév

Leállítási időkorlát

Alkalmazáskonfiguráció újrabetöltésének letiltása a módosításhoz

Webalkalmazások beállításai

IndításiHibákRögzítése

Részletes Hibák

HostingStartupAssemblies

TárolásIndításKizáróÖsszeállítások

HTTPS_port

PreferáltTárhelyURL-ek

HostingIndításMegelőzése

StartupAssembly

ÁllapotüzenetekElrejtése

URL-címek

WebRoot

A gazdagép élettartamának kezelése

Fut

RunAsync

RunConsoleAsync

Kezdés

StartAsync

StopAsync

VárakozásLeállításra

WaitForShutdownAsync

Külső vezérlő

Hoszt definíció

Host szerver beállítása

Alapértelmezett szerkesztőbeállítások

Keretrendszer által biztosított szolgáltatások