Host Generik .NET di ASP.NET Core

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)
• Pencatatan
• 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 satu implementasinya IHostedService adalah layanan web yang memulai implementasi server HTTP.

Termasuk semua sumber daya aplikasi yang saling bergantung dalam satu objek memungkinkan kontrol atas startup aplikasi dan pematian yang anggun.

Menyiapkan host

Host biasanya dikonfigurasi, dibangun, dan dijalankan berdasarkan 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, hubungi 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 lingkungan Development.
  • 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 dalam 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 menyertakan StopApplication metode , yang memungkinkan aplikasi untuk meminta pematian yang anggun.

Saat melakukan pematian yang anggun, 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 mengirim 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 lebih lanjut, 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 rakitan 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("/path/to/content/root")
    // ...

Untuk informasi selengkapnya, lihat:

• Dasar-dasar: Akar konten
• WebRoot

EnvironmentName

Properti IHostEnvironment.EnvironmentName dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, Staging, dan 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 {i>default

• IHostApplicationLifetime.ApplicationStoppingPemicu .
• Upaya untuk menghentikan layanan yang dihosting, kesalahan pengelogan 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: 30 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 reload konfigurasi aplikasi saat diubah

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:reloadConfigOnChange false.

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 aktif IWebHostBuilder tersedia untuk pengaturan ini. Sampel kode yang menunjukkan cara memanggil metode ekstensi mengasumsikan webBuilder adalah instans IWebHostBuilder, seperti 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 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 rakitan aplikasi. Saat rakitan startup hosting disediakan, rakitan tersebut ditambahkan ke perakitan 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

Atur port HTTPS untuk dialihkan jika Anda mendapatkan koneksi non-HTTPS. Digunakan dalam memberlakukan HTTPS. Pengaturan ini tidak menyebabkan server mendengarkan port yang ditentukan. Artinya, dimungkinkan untuk mengalihkan permintaan secara tidak sengaja ke port yang tidak digunakan.

Kunci: https_portKetik: 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");

HTTPS_Ports

Port yang akan didengarkan untuk koneksi HTTPS.

Kunci: https_ports
Jenis: string
Default: Nilai default tidak diatur.
Variabel lingkungan: {PREFIX_}HTTPS_PORTS

Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan UseSetting:

webBuilder.UseSetting("https_ports", "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: false
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

Rakitan 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:

• Dasar-dasar: Akar web
• ContentRoot

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.

Perbedaan antara Run* metode dan Start* adalah bahwa Run* metode menunggu host selesai sebelum kembali, sedangkan Start* metode segera kembali. Metode Run* ini biasanya digunakan dalam aplikasi konsol, sedangkan Start* metode biasanya digunakan dalam layanan yang berjalan lama.

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

RunConsoleAsyncmemungkinkan 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 menghentikan host dalam batas waktu yang disediakan.

WaitForShutdown

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

WaitForShutdownAsync

WaitForShutdownAsyncTask mengembalikan yang selesai saat dimatikan dipicu melalui token dan panggilan yang StopAsyncdiberikan .

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 .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).