Host Generik .NET di ASP.NET Core

Artikel
07/13/2022
30 menit untuk membaca

Artikel ini menyediakan informasi tentang menggunakan Host Generik .NET di ASP.NET Core.

Templat ASP.NET Core membuat WebApplicationBuilder dan WebApplication, yang menyediakan cara yang efisien untuk mengonfigurasi dan menjalankan aplikasi web tanpa Startup kelas. Untuk informasi selengkapnya tentang WebApplicationBuilder dan WebApplication, lihat Migrasi dari ASP.NET Core 5.0 ke 6.0.

Untuk informasi tentang menggunakan Host Generik .NET di aplikasi konsol, lihat Host Generik .NET.

Definisi host

Host adalah objek yang merangkum sumber daya aplikasi, seperti:

Injeksi dependensi (DI)
Pengelogan
Konfigurasi
Implementasi IHostedService

Saat dimulai, host memanggil IHostedService.StartAsync pada setiap implementasi IHostedService yang terdaftar dalam kumpulan layanan yang dihosting kontainer layanan. Dalam aplikasi web, salah IHostedService satu implementasinya adalah layanan web yang memulai implementasi server HTTP.

Menyertakan semua sumber daya aplikasi yang saling diperlukan dalam satu objek memungkinkan kontrol atas pengaktifan aplikasi dan mematikan dengan baik.

Menyiapkan host

Host biasanya dikonfigurasi, dibangun, dan dijalankan oleh kode di Program.cs. Kode berikut membuat host dengan implementasi yang IHostedService ditambahkan ke kontainer DI:

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

Untuk beban kerja HTTP, panggil ConfigureWebHostDefaults setelah CreateDefaultBuilder:

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

Pengaturan penyusun default

Metode CreateDefaultBuilder:

Mengatur akar konten ke jalur yang dikembalikan oleh GetCurrentDirectory.
Memuat konfigurasi host dari:
- Variabel lingkungan yang diawali dengan DOTNET_.
- Argumen baris perintah.
Memuat konfigurasi aplikasi dari:
- appsettings.json.
- appsettings.{Environment}.json.
- Rahasia pengguna saat aplikasi berjalan di Development lingkungan.
- Variabel lingkungan.
- Argumen baris perintah.
Menambahkan penyedia pengelogan berikut:
- Konsol
- Debug
- EventSource
- EventLog (hanya saat menjalankan di Windows)
Mengaktifkan validasi cakupan dan validasi dependensi saat lingkungan adalah Pengembangan.

Metode ConfigureWebHostDefaults:

Memuat konfigurasi host dari variabel lingkungan yang diawali dengan ASPNETCORE_.
Kestrel Mengatur server sebagai server web dan mengonfigurasinya menggunakan penyedia konfigurasi hosting aplikasi. Kestrel Untuk opsi default server, lihat Mengonfigurasi opsi untuk server web ASP.NET CoreKestrel.
Menambahkan middleware Pemfilteran Host.
Menambahkan middleware Header yang Diteruskan jika ASPNETCORE_FORWARDEDHEADERS_ENABLED sama dengan true.
Mengaktifkan integrasi IIS. Untuk opsi default IIS, lihat Host ASP.NET Core di Windows dengan IIS.

Bagian Pengaturan untuk semua jenis aplikasi dan Pengaturan untuk aplikasi web nanti di artikel ini memperlihatkan cara mengganti pengaturan penyusun default.

Layanan yang disediakan kerangka kerja

Layanan berikut terdaftar secara otomatis:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

Untuk informasi selengkapnya tentang layanan yang disediakan kerangka kerja, lihat Injeksi dependensi di ASP.NET Core.

IHostApplicationLifetime

IHostApplicationLifetime Masukkan layanan (sebelumnyaIApplicationLifetime) ke kelas mana pun untuk menangani tugas pasca-startup dan matikan dengan baik. Tiga properti pada antarmuka adalah token pembatalan yang digunakan untuk mendaftarkan metode penanganan aktivitas mulai aplikasi dan penghentian aplikasi. Antarmuka juga menyertakan StopApplication metode , yang memungkinkan aplikasi untuk meminta pematian yang baik.

Saat melakukan pematian dengan baik, host:

Memicu penanganan ApplicationStopping aktivitas, yang memungkinkan aplikasi menjalankan logika sebelum proses pematian dimulai.
Menghentikan server, yang menonaktifkan koneksi baru. Server menunggu permintaan pada koneksi yang ada selesai, selama batas waktu mati memungkinkan. Server mengirimkan header tutup koneksi untuk permintaan lebih lanjut pada koneksi yang ada.
Memicu penanganan ApplicationStopped aktivitas, yang memungkinkan aplikasi menjalankan logika setelah aplikasi dimatikan.

Contoh berikut adalah IHostedService implementasi yang mendaftarkan IHostApplicationLifetime penanganan aktivitas:

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

Implementasi IHostLifetime mengontrol waktu host dimulai dan dihentikan. Implementasi terakhir yang terdaftar akan digunakan.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime adalah implementasi IHostLifetime default. ConsoleLifetime:

Mendengarkan Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM dan panggilan StopApplication untuk memulai proses matikan.
Membuka blokir ekstensi seperti RunAsync dan WaitForShutdownAsync.

IHostEnvironment

Injeksikan layanan IHostEnvironment ke dalam kelas untuk mendapatkan informasi tentang pengaturan berikut:

ApplicationName
EnvironmentName
ContentRootPath

Aplikasi web mengimplementasikan IWebHostEnvironment antarmuka, yang mewarisi IHostEnvironment dan menambahkan WebRootPath.

Konfigurasi host

Konfigurasi host digunakan untuk properti IHostEnvironment implementasi.

Konfigurasi host tersedia dari HostBuilderContext.Configuration dalam ConfigureAppConfiguration. Setelah ConfigureAppConfiguration, HostBuilderContext.Configuration diganti dengan konfigurasi aplikasi.

Untuk menambahkan konfigurasi host, panggil ConfigureHostConfiguration di IHostBuilder. ConfigureHostConfiguration dapat dipanggil beberapa kali dengan hasil tambahan. Host menggunakan opsi mana pun yang mengatur nilai terakhir pada kunci tertentu.

Penyedia variabel lingkungan dengan awalan DOTNET_ dan argumen baris perintah disertakan oleh CreateDefaultBuilder. Untuk aplikasi web, penyedia variabel lingkungan dengan awalan ASPNETCORE_ ditambahkan. Awalan dihapus saat variabel lingkungan dibaca. Misalnya, nilai variabel lingkungan untuk ASPNETCORE_ENVIRONMENT menjadi nilai konfigurasi host untuk environment kunci.

Contoh berikut membuat konfigurasi host:

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

Konfigurasi aplikasi

Konfigurasi aplikasi dibuat dengan memanggil ConfigureAppConfiguration di IHostBuilder. ConfigureAppConfiguration dapat dipanggil beberapa kali dengan hasil tambahan. Aplikasi ini menggunakan opsi mana pun yang mengatur nilai terakhir pada kunci tertentu.

Konfigurasi yang dibuat oleh ConfigureAppConfiguration tersedia di HostBuilderContext.Configuration untuk operasi berikutnya dan sebagai layanan dari DI. Konfigurasi host juga ditambahkan ke konfigurasi aplikasi.

Untuk informasi selengkapnya, lihat Konfigurasi di ASP.NET Core.

Pengaturan untuk semua jenis aplikasi

Bagian ini mencantumkan pengaturan host yang berlaku untuk beban kerja HTTP dan non-HTTP. Secara default, variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan ini dapat memiliki DOTNET_ awalan atau ASPNETCORE_ , yang muncul dalam daftar pengaturan berikut sebagai {PREFIX_} tempat penampung. Untuk informasi selengkapnya, lihat bagian Pengaturan penyusun default dan Konfigurasi: Variabel lingkungan.

ApplicationName

Properti IHostEnvironment.ApplicationName diatur dari konfigurasi host selama konstruksi host.

Kunci: applicationName
Jenis: string
Default: Nama assembly yang berisi titik masuk aplikasi.
Variabel lingkungan: {PREFIX_}APPLICATIONNAME

Untuk mengatur nilai ini, gunakan variabel lingkungan.

ContentRoot

Properti IHostEnvironment.ContentRootPath menentukan di mana host mulai mencari file konten. Jika jalur tidak ada, host gagal memulai.

Kunci: contentRoot
Jenis: string
Default: Folder tempat assembly aplikasi berada.
Variabel lingkungan: {PREFIX_}CONTENTROOT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseContentRoot pada IHostBuilder:

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

Untuk informasi selengkapnya, lihat:

EnvironmentName

Properti IHostEnvironment.EnvironmentName dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, , Stagingdan Production. Nilai tidak peka huruf besar/kecil.

Kunci: environment
Jenis: string
Default: Production
Variabel lingkungan: {PREFIX_}ENVIRONMENT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseEnvironment pada IHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout mengatur batas waktu untuk StopAsync. Nilai defaultnya adalah lima detik. Selama periode batas waktu, host:

IHostApplicationLifetime.ApplicationStoppingMemicu .
Upaya untuk menghentikan layanan yang dihosting, mencatat kesalahan untuk layanan yang gagal dihentikan.

Jika periode batas waktu berakhir sebelum semua layanan yang dihosting berhenti, layanan aktif yang tersisa akan dihentikan saat aplikasi dimatikan. Layanan berhenti meskipun belum selesai diproses. Jika layanan memerlukan lebih banyak waktu untuk berhenti, tingkatkan batas waktu.

Kunci: shutdownTimeoutSeconds
Jenis: int
Default: 5 detik
Variabel lingkungan: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau konfigurasikan HostOptions. Contoh berikut mengatur batas waktu menjadi 20 detik:

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

Menonaktifkan muatan ulang konfigurasi aplikasi saat perubahan

Secara default, appsettings.json dan appsettings.{Environment}.json dimuat ulang saat file berubah. Untuk menonaktifkan perilaku muat ulang ini di ASP.NET Core 5.0 atau yang lebih baru, atur kunci ke hostBuilder:reloadConfigOnChangefalse.

Kunci: hostBuilder:reloadConfigOnChange
Jenis: bool (true atau false)
Default: true
Argumen baris perintah: hostBuilder:reloadConfigOnChange
Variabel lingkungan: {PREFIX_}hostBuilder:reloadConfigOnChange

Peringatan

Pemisah titik dua (:) tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. Untuk informasi selengkapnya, lihat Variabel lingkungan.

Pengaturan untuk aplikasi web

Beberapa pengaturan host hanya berlaku untuk beban kerja HTTP. Secara default, variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan ini dapat memiliki DOTNET_ awalan atau ASPNETCORE_ , yang muncul dalam daftar pengaturan berikut sebagai {PREFIX_} tempat penampung.

Metode ekstensi pada IWebHostBuilder tersedia untuk pengaturan ini. Sampel kode yang menunjukkan cara memanggil metode ekstensi mengasumsikan webBuilder adalah instans , IWebHostBuilderseperti dalam contoh berikut:

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

CaptureStartupErrors

Ketika false, kesalahan selama startup mengakibatkan host keluar. Ketika true, host menangkap pengecualian selama startup dan mencoba memulai server.

Kunci: captureStartupErrors
Jenis: bool (true/1 atau false/0)
Default: Default ke false kecuali aplikasi berjalan dengan Kestrel di belakang IIS, di mana defaultnya adalah true.
Variabel lingkungan: {PREFIX_}CAPTURESTARTUPERRORS

Untuk mengatur nilai ini, gunakan konfigurasi atau panggil CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Saat diaktifkan, atau saat lingkungan adalah Development, aplikasi menangkap kesalahan terperinci.

Kunci: detailedErrors
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}DETAILEDERRORS

Untuk mengatur nilai ini, gunakan konfigurasi atau panggil UseSetting:

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

HostingStartupAssemblies

String rakitan startup hosting yang dibatasi titik koma untuk dimuat saat startup. Meskipun nilai konfigurasi default ke string kosong, rakitan startup hosting selalu menyertakan assembly aplikasi. Saat menghosting rakitan startup disediakan, mereka ditambahkan ke assembly aplikasi untuk dimuat saat aplikasi membangun layanan umumnya selama startup.

Kunci: hostingStartupAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggil UseSetting:

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

HostingStartupExcludeAssemblies

String rakitan startup hosting yang dibatasi titik koma untuk dikecualikan saat startup.

Kunci: hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggil UseSetting:

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

HTTPS_Port

Port pengalihan HTTPS. Digunakan dalam memberlakukan HTTPS.

Kunci: https_port
Jenis: string
Default: Nilai default tidak diatur.
Variabel lingkungan: {PREFIX_}HTTPS_PORT

Untuk mengatur nilai ini, gunakan konfigurasi atau panggil UseSetting:

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

PreferHostingUrls

Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan IWebHostBuilder alih-alih URL yang dikonfigurasi dengan IServer implementasi.

Kunci: preferHostingUrls
Jenis: bool (true/1 atau false/0)
Default: true
Variabel lingkungan: {PREFIX_}PREFERHOSTINGURLS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Mencegah pemuatan otomatis rakitan startup hosting, termasuk rakitan startup hosting yang dikonfigurasi oleh rakitan aplikasi. Untuk informasi selengkapnya, lihat Menggunakan rakitan startup hosting di ASP.NET Core.

Kunci: preventHostingStartup
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}PREVENTHOSTINGSTARTUP

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseSetting :

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

StartupAssembly

Perakitan untuk Startup mencari kelas .

Kunci: startupAssembly
Jenis: string
Default: Rakitan aplikasi
Variabel lingkungan: {PREFIX_}STARTUPASSEMBLY

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseStartup. UseStartup dapat mengambil nama rakitan (string) atau jenis (TStartup). Jika beberapa UseStartup metode dipanggil, metode terakhir lebih diutamakan.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Saat diaktifkan, menekan pesan status startup hosting.

Kunci: suppressStatusMessages
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}SUPPRESSSTATUSMESSAGES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

URL

Daftar alamat IP atau alamat host yang dibatasi titik koma dengan port dan protokol yang harus didengarkan server untuk permintaan. Contohnya:http://localhost:123 Gunakan "*" untuk menunjukkan bahwa server harus mendengarkan permintaan pada alamat IP atau nama host apa pun menggunakan port dan protokol yang ditentukan (misalnya, http://*:5000). Protokol (http:// atau https://) harus disertakan dengan setiap URL. Format yang didukung bervariasi di antara server.

Kunci: urls
Jenis: string
Default: http://localhost:5000 dan https://localhost:5001
Variabel lingkungan: {PREFIX_}URLS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseUrls:

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

Kestrel memiliki API konfigurasi titik akhirnya sendiri. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET CoreKestrel.

Webroot

Properti IWebHostEnvironment.WebRootPath menentukan jalur relatif ke aset statis aplikasi. Jika jalur tidak ada, penyedia file tanpa operasi akan digunakan.

Kunci: webroot
Jenis: string
Default: Defaultnya adalah wwwroot. Jalur ke {content root}/wwwroot harus ada.
Variabel lingkungan: {PREFIX_}WEBROOT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseWebRoot pada IWebHostBuilder:

webBuilder.UseWebRoot("public");

Untuk informasi selengkapnya, lihat:

Mengelola masa pakai host

Panggil metode pada implementasi bawaan IHost untuk memulai dan menghentikan aplikasi. Metode ini memengaruhi semua IHostedService implementasi yang terdaftar dalam kontainer layanan.

jalankan

Run menjalankan aplikasi dan memblokir utas panggilan hingga host dimatikan.

RunAsync

RunAsync menjalankan aplikasi dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu.

RunConsoleAsync

RunConsoleAsync memungkinkan dukungan konsol, membangun, dan memulai host, dan menunggu Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM dimatikan.

Mulai

Start memulai host secara sinkron.

StartAsync

StartAsync memulai host dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu.

WaitForStartAsync dipanggil pada awal StartAsync, yang menunggu sampai selesai sebelum melanjutkan. Metode ini dapat digunakan untuk menunda startup hingga disinyalir oleh peristiwa eksternal.

StopAsync

StopAsync mencoba untuk menghentikan host dalam batas waktu yang disediakan.

WaitForShutdown

WaitForShutdown memblokir utas panggilan hingga matikan dipicu oleh IHostLifetime, seperti melalui Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync Task mengembalikan yang selesai ketika pematian dipicu melalui token dan panggilan yang StopAsyncdiberikan .

Templat ASP.NET Core membuat Host Generik .NET Core (HostBuilder).

Artikel ini menyediakan informasi tentang menggunakan Host Generik .NET di ASP.NET Core. Untuk informasi tentang menggunakan Host Generik .NET di aplikasi konsol, lihat Host Generik .NET.

Definisi host

Host adalah objek yang merangkum sumber daya aplikasi, seperti:

Injeksi dependensi (DI)
Pengelogan
Konfigurasi
Implementasi IHostedService

Alasan utama untuk menyertakan semua sumber daya aplikasi yang saling bergantung dalam satu objek adalah pengelolaan masa pakai: kontrol atas pengaktifan dan penonaktifan aplikasi dengan baik.

Menyiapkan host

Host biasanya dikonfigurasi, dibangun, dan dijalankan oleh kode di kelas Program. Metode Main:

Memanggil metode CreateHostBuilder untuk membuat dan mengonfigurasi objek penyusun.
Build Panggilan dan Run metode pada objek penyusun.

Templat web ASP.NET Core menghasilkan kode berikut untuk membuat host:

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

Kode berikut membuat beban kerja non-HTTP dengan implementasi yang IHostedService ditambahkan ke kontainer DI.

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

Untuk beban kerja HTTP, Main metodenya sama tetapi CreateHostBuilder memanggil ConfigureWebHostDefaults:

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

Jika aplikasi menggunakan Entity Framework Core, jangan ubah nama atau tanda tangan CreateHostBuilder metode. Alat Entity Framework Core mengharapkan untuk menemukan CreateHostBuilder metode yang mengonfigurasi host tanpa menjalankan aplikasi. Untuk informasi selengkapnya, lihat Pembuatan DbContext waktu desain.

Pengaturan penyusun default

Metode CreateDefaultBuilder:

Mengatur akar konten ke jalur yang dikembalikan oleh GetCurrentDirectory.
Memuat konfigurasi host dari:
- Variabel lingkungan yang diawali dengan DOTNET_.
- Argumen baris perintah.
Memuat konfigurasi aplikasi dari:
- appsettings.json.
- appsettings.{Environment}.json.
- Rahasia pengguna saat aplikasi berjalan di Development lingkungan.
- Variabel lingkungan.
- Argumen baris perintah.
Menambahkan penyedia pengelogan berikut:
- Konsol
- Debug
- EventSource
- EventLog (hanya saat menjalankan di Windows)
Mengaktifkan validasi cakupan dan validasi dependensi saat lingkungan adalah Pengembangan.

Metode ConfigureWebHostDefaults:

Memuat konfigurasi host dari variabel lingkungan yang diawali dengan ASPNETCORE_.
Kestrel Mengatur server sebagai server web dan mengonfigurasinya menggunakan penyedia konfigurasi hosting aplikasi. Kestrel Untuk opsi default server, lihat Mengonfigurasi opsi untuk server web ASP.NET CoreKestrel.
Menambahkan middleware Pemfilteran Host.
Menambahkan middleware Header yang Diteruskan jika ASPNETCORE_FORWARDEDHEADERS_ENABLED sama dengan true.
Memungkinkan integrasi IIS. Untuk opsi default IIS, lihat Host ASP.NET Core di Windows dengan IIS.

Bagian Pengaturan untuk semua jenis aplikasi dan Pengaturan untuk aplikasi web nanti di artikel ini memperlihatkan cara mengambil alih pengaturan penyusun default.

Layanan yang disediakan kerangka kerja

Layanan berikut terdaftar secara otomatis:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

Untuk informasi selengkapnya tentang layanan yang disediakan kerangka kerja, lihat Injeksi dependensi di ASP.NET Core.

IHostApplicationLifetime

IHostApplicationLifetime Masukkan layanan (sebelumnyaIApplicationLifetime) ke kelas mana pun untuk menangani tugas pasca-startup dan shutdown yang lancar. Tiga properti pada antarmuka adalah token pembatalan yang digunakan untuk mendaftarkan metode penanganan aktivitas mulai aplikasi dan penghentian aplikasi. Antarmuka juga mencakup metode StopApplication.

Contoh berikut adalah implementasi IHostedService yang mendaftarkan peristiwa IHostApplicationLifetime:

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

Implementasi IHostLifetime mengontrol waktu host dimulai dan dihentikan. Implementasi terakhir yang terdaftar akan digunakan.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime adalah implementasi IHostLifetime default. ConsoleLifetime:

Mendengarkan Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM dan panggilan StopApplication untuk memulai proses matikan.
Membuka blokir ekstensi seperti RunAsync dan WaitForShutdownAsync.

IHostEnvironment

Injeksikan layanan IHostEnvironment ke dalam kelas untuk mendapatkan informasi tentang pengaturan berikut:

ApplicationName
EnvironmentName
ContentRootPath

Aplikasi web mengimplementasikan IWebHostEnvironment antarmuka , yang mewarisi IHostEnvironment dan menambahkan WebRootPath.

Konfigurasi host

Konfigurasi host digunakan untuk properti IHostEnvironment implementasi.

Contoh berikut membuat konfigurasi host:

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

Konfigurasi aplikasi

Untuk informasi selengkapnya, lihat Konfigurasi di ASP.NET Core.

Pengaturan untuk semua jenis aplikasi

ApplicationName

Properti IHostEnvironment.ApplicationName diatur dari konfigurasi host selama konstruksi host.

Kunci: applicationName
Jenis: string
Default: Nama assembly yang berisi titik masuk aplikasi.
Variabel lingkungan: {PREFIX_}APPLICATIONNAME

Untuk mengatur nilai ini, gunakan variabel lingkungan.

ContentRoot

Properti IHostEnvironment.ContentRootPath menentukan di mana host mulai mencari file konten. Jika jalur tidak ada, host gagal memulai.

Kunci: contentRoot
Jenis: string
Default: Folder tempat assembly aplikasi berada.
Variabel lingkungan: {PREFIX_}CONTENTROOT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseContentRoot pada IHostBuilder:

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

Untuk informasi selengkapnya, lihat:

EnvironmentName

Properti IHostEnvironment.EnvironmentName dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, , Stagingdan Production. Nilai tidak peka huruf besar/kecil.

Kunci: environment
Jenis: string
Default: Production
Variabel lingkungan: {PREFIX_}ENVIRONMENT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseEnvironment pada IHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout mengatur batas waktu untuk StopAsync. Nilai defaultnya adalah lima detik. Selama periode batas waktu, host:

IHostApplicationLifetime.ApplicationStoppingMemicu .
Upaya untuk menghentikan layanan yang dihosting, mencatat kesalahan untuk layanan yang gagal dihentikan.

Kunci: shutdownTimeoutSeconds
Jenis: int
Default: 5 detik
Variabel lingkungan: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau konfigurasikan HostOptions. Contoh berikut mengatur batas waktu menjadi 20 detik:

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

Menonaktifkan muat ulang konfigurasi aplikasi saat perubahan

Peringatan

Pemisah titik dua (:) tidak berfungsi dengan kunci hierarkis variabel lingkungan di semua platform. Untuk informasi selengkapnya, lihat Variabel lingkungan.

Pengaturan untuk aplikasi web

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

CaptureStartupErrors

Ketika false, kesalahan selama startup mengakibatkan host keluar. Ketika true, host menangkap pengecualian selama startup dan mencoba memulai server.

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailEdErrors

Saat diaktifkan, atau saat lingkungan adalah Development, aplikasi menangkap kesalahan terperinci.

Kunci: detailedErrors
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}DETAILEDERRORS

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

HostingStartupAssemblies

String rakitan startup hosting yang dibatasi titik koma untuk dimuat saat startup. Meskipun nilai konfigurasi default ke string kosong, rakitan startup hosting selalu menyertakan assembly aplikasi. Saat rakitan startup hosting disediakan, mereka ditambahkan ke assembly aplikasi untuk dimuat saat aplikasi membangun layanan umumnya selama startup.

Kunci: hostingStartupAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

HostingStartupExcludeAssemblies

String rakitan startup hosting yang dibatasi titik koma untuk dikecualikan saat startup.

Kunci: hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

HTTPS_Port

Port pengalihan HTTPS. Digunakan dalam memberlakukan HTTPS.

Kunci: https_port
Jenis: string
Default: Nilai default tidak diatur.
Variabel lingkungan: {PREFIX_}HTTPS_PORT

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

PreferHostingUrls

Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan IWebHostBuilder alih-alih URL yang dikonfigurasi dengan IServer implementasi.

Kunci: preferHostingUrls
Jenis: bool (true/1 atau false/0)
Default: true
Variabel lingkungan: {PREFIX_}PREFERHOSTINGURLS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Kunci: preventHostingStartup
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}PREVENTHOSTINGSTARTUP

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseSetting :

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

StartupAssembly

Perakitan untuk Startup mencari kelas .

Kunci: startupAssembly
Jenis: string
Default: Rakitan aplikasi
Variabel lingkungan: {PREFIX_}STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Saat diaktifkan, menekan pesan status startup hosting.

Kunci: suppressStatusMessages
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}SUPPRESSSTATUSMESSAGES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

URL

Kunci: urls
Jenis: string
Default: http://localhost:5000 dan https://localhost:5001
Variabel lingkungan: {PREFIX_}URLS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseUrls:

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

Kestrel memiliki API konfigurasi titik akhirnya sendiri. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET CoreKestrel.

Webroot

Properti IWebHostEnvironment.WebRootPath menentukan jalur relatif ke aset statis aplikasi. Jika jalur tidak ada, penyedia file tanpa operasi akan digunakan.

Kunci: webroot
Jenis: string
Default: Defaultnya adalah wwwroot. Jalur ke {content root}/wwwroot harus ada.
Variabel lingkungan: {PREFIX_}WEBROOT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseWebRoot pada IWebHostBuilder:

webBuilder.UseWebRoot("public");

Untuk informasi selengkapnya, lihat:

Mengelola masa pakai host

Panggil metode pada implementasi bawaan IHost untuk memulai dan menghentikan aplikasi. Metode ini memengaruhi semua IHostedService implementasi yang terdaftar dalam kontainer layanan.

jalankan

Run menjalankan aplikasi dan memblokir utas panggilan hingga host dimatikan.

RunAsync

RunAsync menjalankan aplikasi dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu.

RunConsoleAsync

RunConsoleAsync memungkinkan dukungan konsol, membangun, dan memulai host, dan menunggu Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM dimatikan.

Mulai

Start memulai host secara sinkron.

StartAsync

StartAsync memulai host dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu.

WaitForStartAsync dipanggil pada awal StartAsync, yang menunggu sampai selesai sebelum melanjutkan. Metode ini dapat digunakan untuk menunda startup hingga disinyalir oleh peristiwa eksternal.

StopAsync

StopAsync mencoba untuk menghentikan host dalam batas waktu yang disediakan.

WaitForShutdown

WaitForShutdown memblokir utas panggilan hingga matikan dipicu oleh IHostLifetime, seperti melalui Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync Task mengembalikan yang selesai ketika pematian dipicu melalui token dan panggilan yang StopAsyncdiberikan .

Kontrol eksternal

Kontrol langsung masa pakai host dapat dicapai menggunakan metode yang dapat dipanggil secara eksternal:

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

Templat ASP.NET Core membuat Host Generik .NET Core (HostBuilder).

Artikel ini menyediakan informasi tentang menggunakan Host Generik .NET di ASP.NET Core. Untuk informasi tentang menggunakan Host Generik .NET di aplikasi konsol, lihat Host Generik .NET.

Definisi host

Host adalah objek yang merangkum sumber daya aplikasi, seperti:

Injeksi dependensi (DI)
Pengelogan
Konfigurasi
Implementasi IHostedService

Alasan utama untuk menyertakan semua sumber daya aplikasi yang saling bergantung dalam satu objek adalah pengelolaan masa pakai: kontrol atas pengaktifan dan penonaktifan aplikasi dengan baik.

Menyiapkan host

Host biasanya dikonfigurasi, dibangun, dan dijalankan oleh kode di kelas Program. Metode Main:

Memanggil metode CreateHostBuilder untuk membuat dan mengonfigurasi objek penyusun.
Build Panggilan dan Run metode pada objek penyusun.

Templat web ASP.NET Core menghasilkan kode berikut untuk membuat Host Generik:

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

Kode berikut membuat Host Generik menggunakan beban kerja non-HTTP. Implementasi IHostedService ditambahkan ke kontainer DI:

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

Untuk beban kerja HTTP, Main metodenya sama tetapi CreateHostBuilder memanggil ConfigureWebHostDefaults:

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

Kode sebelumnya dihasilkan oleh templat ASP.NET Core.

Pengaturan penyusun default

Metode CreateDefaultBuilder:

Mengatur akar konten ke jalur yang dikembalikan oleh GetCurrentDirectory.
Memuat konfigurasi host dari:
- Variabel lingkungan yang diawali dengan DOTNET_.
- Argumen baris perintah.
Memuat konfigurasi aplikasi dari:
- appsettings.json.
- appsettings.{Environment}.json.
- Rahasia pengguna saat aplikasi berjalan di Development lingkungan.
- Variabel lingkungan.
- Argumen baris perintah.
Menambahkan penyedia pengelogan berikut:
- Konsol
- Debug
- EventSource
- EventLog (hanya saat menjalankan di Windows)
Mengaktifkan validasi cakupan dan validasi dependensi saat lingkungan adalah Pengembangan.

Metode ConfigureWebHostDefaults:

Memuat konfigurasi host dari variabel lingkungan yang diawali dengan ASPNETCORE_.
Kestrel Mengatur server sebagai server web dan mengonfigurasinya menggunakan penyedia konfigurasi hosting aplikasi. Kestrel Untuk opsi default server, lihat Kestrel implementasi server web di ASP.NET Core.
Menambahkan middleware Pemfilteran Host.
Menambahkan middleware Header yang Diteruskan jika ASPNETCORE_FORWARDEDHEADERS_ENABLED sama dengan true.
Mengaktifkan integrasi IIS. Untuk opsi default IIS, lihat Host ASP.NET Core di Windows dengan IIS.

Bagian Pengaturan untuk semua jenis aplikasi dan Pengaturan untuk aplikasi web nanti di artikel ini memperlihatkan cara mengganti pengaturan penyusun default.

Layanan yang disediakan kerangka kerja

Layanan berikut terdaftar secara otomatis:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

Untuk informasi selengkapnya tentang layanan yang disediakan kerangka kerja, lihat Injeksi dependensi di ASP.NET Core.

IHostApplicationLifetime

Contoh berikut adalah implementasi IHostedService yang mendaftarkan peristiwa IHostApplicationLifetime:

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

Implementasi IHostLifetime mengontrol waktu host dimulai dan dihentikan. Implementasi terakhir yang terdaftar akan digunakan.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime adalah implementasi IHostLifetime default. ConsoleLifetime:

Mendengarkan Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM dan panggilan StopApplication untuk memulai proses matikan.
Membuka blokir ekstensi seperti RunAsync dan WaitForShutdownAsync.

IHostEnvironment

Injeksikan layanan IHostEnvironment ke dalam kelas untuk mendapatkan informasi tentang pengaturan berikut:

ApplicationName
EnvironmentName
ContentRootPath

Aplikasi web mengimplementasikan IWebHostEnvironment antarmuka, yang mewarisi IHostEnvironment dan menambahkan WebRootPath.

Konfigurasi host

Konfigurasi host digunakan untuk properti IHostEnvironment implementasi.

Contoh berikut membuat konfigurasi host:

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

Konfigurasi aplikasi

Untuk informasi selengkapnya, lihat Konfigurasi di ASP.NET Core.

Pengaturan untuk semua jenis aplikasi

Bagian ini mencantumkan pengaturan host yang berlaku untuk beban kerja HTTP dan non-HTTP. Secara default, variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan ini dapat memiliki DOTNET_ awalan atau ASPNETCORE_ , yang muncul dalam konfigurasi berikut untuk {PREFIX_} tempat penampung.

ApplicationName

Properti IHostEnvironment.ApplicationName diatur dari konfigurasi host selama konstruksi host.

Kunci: applicationName
Jenis: string
Default: Nama assembly yang berisi titik masuk aplikasi.
Variabel lingkungan: {PREFIX_}APPLICATIONNAME

Untuk mengatur nilai ini, gunakan variabel lingkungan.

ContentRoot

Properti IHostEnvironment.ContentRootPath menentukan tempat host mulai mencari file konten. Jika jalur tidak ada, host gagal memulai.

Kunci: contentRoot
Jenis: string
Default: Folder tempat rakitan aplikasi berada.
Variabel lingkungan: {PREFIX_}CONTENTROOT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseContentRoot pada IHostBuilder:

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

Untuk informasi selengkapnya, lihat:

EnvironmentName

Properti IHostEnvironment.EnvironmentName dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, , Stagingdan Production. Nilai tidak peka huruf besar/kecil.

Kunci: environment
Jenis: string
Default: Production
Variabel lingkungan: {PREFIX_}ENVIRONMENT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseEnvironment pada IHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout mengatur batas waktu untuk StopAsync. Nilai defaultnya adalah lima detik. Selama periode batas waktu, host:

IHostApplicationLifetime.ApplicationStoppingPemicu .
Upaya untuk menghentikan layanan yang dihosting, kesalahan pengelogan untuk layanan yang gagal dihentikan.

Kunci: shutdownTimeoutSeconds
Jenis: int
Default: 5 detik
Variabel lingkungan: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau konfigurasikan HostOptions. Contoh berikut mengatur batas waktu menjadi 20 detik:

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

Pengaturan untuk aplikasi web

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

CaptureStartupErrors

Ketika false, kesalahan selama startup mengakibatkan host keluar. Ketika true, host menangkap pengecualian selama startup dan mencoba memulai server.

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailEdErrors

Saat diaktifkan, atau saat lingkungan adalah Development, aplikasi menangkap kesalahan terperinci.

Kunci: detailedErrors
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}DETAILEDERRORS

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

HostingStartupAssemblies

String rakitan startup hosting yang dibatasi titik koma untuk dimuat saat startup. Meskipun nilai konfigurasi default ke string kosong, rakitan startup hosting selalu menyertakan assembly aplikasi. Saat rakitan startup hosting disediakan, mereka ditambahkan ke assembly aplikasi untuk dimuat saat aplikasi membangun layanan umumnya selama startup.

Kunci: hostingStartupAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

HostingStartupExcludeAssemblies

String rakitan startup hosting yang dibatasi titik koma untuk dikecualikan saat startup.

Kunci: hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

HTTPS_Port

Port pengalihan HTTPS. Digunakan dalam memberlakukan HTTPS.

Kunci: https_port
Jenis: string
Default: Nilai default tidak diatur.
Variabel lingkungan: {PREFIX_}HTTPS_PORT

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

PreferHostingUrls

Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan IWebHostBuilder alih-alih URL yang dikonfigurasi dengan IServer implementasi.

Kunci: preferHostingUrls
Jenis: bool (true/1 atau false/0)
Default: true
Variabel lingkungan: {PREFIX_}PREFERHOSTINGURLS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Kunci: preventHostingStartup
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}PREVENTHOSTINGSTARTUP

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseSetting :

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

StartupAssembly

Perakitan untuk Startup mencari kelas .

Kunci: startupAssembly
Jenis: string
Default: Rakitan aplikasi
Variabel lingkungan: {PREFIX_}STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Saat diaktifkan, menekan pesan status startup hosting.

Kunci: suppressStatusMessages
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}SUPPRESSSTATUSMESSAGES

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

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

URL

Kunci: urls
Jenis: string
Default: http://localhost:5000 dan https://localhost:5001
Variabel lingkungan: {PREFIX_}URLS

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseUrls:

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

Kestrel memiliki API konfigurasi titik akhirnya sendiri. Untuk informasi selengkapnya, lihat Kestrel implementasi server web di ASP.NET Core.

Webroot

Properti IWebHostEnvironment.WebRootPath menentukan jalur relatif ke aset statis aplikasi. Jika jalur tidak ada, penyedia file tanpa operasi akan digunakan.

Kunci: webroot
Jenis: string
Default: Defaultnya adalah wwwroot. Jalur ke {content root}/wwwroot harus ada.
Variabel lingkungan: {PREFIX_}WEBROOT

Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil UseWebRoot pada IWebHostBuilder:

webBuilder.UseWebRoot("public");

Untuk informasi selengkapnya, lihat:

Mengelola masa pakai host

Panggil metode pada implementasi bawaan IHost untuk memulai dan menghentikan aplikasi. Metode ini memengaruhi semua IHostedService implementasi yang terdaftar dalam kontainer layanan.

jalankan

Run menjalankan aplikasi dan memblokir utas panggilan hingga host dimatikan.

RunAsync

RunAsync menjalankan aplikasi dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu.

RunConsoleAsync

RunConsoleAsync memungkinkan dukungan konsol, membangun, dan memulai host, dan menunggu Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM dimatikan.

Mulai

Start memulai host secara sinkron.

StartAsync

StartAsync memulai host dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu.

WaitForStartAsync dipanggil pada awal StartAsync, yang menunggu sampai selesai sebelum melanjutkan. Metode ini dapat digunakan untuk menunda startup hingga disinyalir oleh peristiwa eksternal.

StopAsync

StopAsync mencoba untuk menghentikan host dalam batas waktu yang disediakan.

WaitForShutdown

WaitForShutdown memblokir utas panggilan hingga matikan dipicu oleh IHostLifetime, seperti melalui Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync Task mengembalikan yang selesai ketika pematian dipicu melalui token yang diberikan dan panggilan StopAsync.

Kontrol eksternal

Kontrol langsung masa pakai host dapat dicapai menggunakan metode yang dapat dipanggil secara eksternal:

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

Sumber Daya Tambahan:

Tugas latar belakang dengan layanan yang dihosting di ASP.NET Core
Tautan GitHub ke sumber Host Generik

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis berikutnya .NET. Untuk memilih tag untuk rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag . Untuk informasi selengkapnya, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).