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.
- Variabel lingkungan yang diawali dengan
- 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_ENABLEDsama dengantrue. - 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 menunjukkan cara mengambil alih pengaturan penyusun default.
Layanan yang disediakan kerangka kerja
Layanan berikut terdaftar secara otomatis:
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:
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:
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 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: Untuk mengatur nilai ini, gunakan variabel lingkungan atau konfigurasikan Secara default, Kunci: Peringatan Pemisah titik dua ( Beberapa pengaturan host hanya berlaku untuk beban kerja HTTP. Secara default, variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan ini dapat memiliki Metode ekstensi aktif Ketika Kunci: Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan Saat diaktifkan, atau saat lingkungan adalah Kunci: Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan 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: Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan String rakitan startup hosting yang dibatasi titik koma untuk dikecualikan saat startup. Kunci: Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan Port pengalihan HTTPS. Digunakan dalam memberlakukan HTTPS. Kunci: Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan Kunci: Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil 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: Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil Rakitan untuk Kunci: Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil Saat diaktifkan, menekan pesan status startup hosting. Kunci: Untuk mengatur nilai ini, gunakan konfigurasi atau panggilan Daftar alamat IP atau alamat host yang dibatasi titik koma dengan port dan protokol yang harus didengarkan server untuk permintaan. Contohnya, Kunci: Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil Kestrel memiliki API konfigurasi titik akhirnya sendiri. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET CoreKestrel. Properti IWebHostEnvironment.WebRootPath menentukan jalur relatif ke aset statis aplikasi. Jika jalur tidak ada, penyedia file tanpa operasi akan digunakan. Kunci: Untuk mengatur nilai ini, gunakan variabel lingkungan atau panggil Untuk informasi selengkapnya, lihat: 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 menjalankan aplikasi dan memblokir utas panggilan hingga host dimatikan. RunAsync menjalankan aplikasi dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu. RunConsoleAsyncmemungkinkan dukungan konsol, membangun, dan memulai host, dan menunggu Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM dimatikan. Start memulai host secara sinkron. StartAsync memulai host dan mengembalikan Task yang selesai saat token pembatalan atau pematian dipicu. WaitForStartAsync dipanggil pada awal StopAsync mencoba menghentikan host dalam batas waktu yang disediakan. WaitForShutdownmemblokir utas panggilan hingga matikan dipicu oleh IHostLifetime, seperti melalui Ctrl+C/SIGINT (Windows), ⌘+C (macOS), atau SIGTERM. WaitForShutdownAsyncTask mengembalikan yang selesai saat dimatikan dipicu melalui token dan panggilan yang StopAsyncdiberikan .
shutdownTimeoutSeconds
Jenis: int
Default: 30 detik
Variabel lingkungan: {PREFIX_}SHUTDOWNTIMEOUTSECONDSHostOptions. 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
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.hostBuilder:reloadConfigOnChange
Jenis: bool (true atau false)
Default: true
Argumen baris perintah: hostBuilder:reloadConfigOnChange
Variabel lingkungan: {PREFIX_}hostBuilder:reloadConfigOnChange:) tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. Untuk informasi selengkapnya, lihat Variabel lingkungan.Pengaturan untuk aplikasi web
DOTNET_ awalan atau ASPNETCORE_ , yang muncul dalam daftar pengaturan berikut sebagai {PREFIX_} tempat penampung.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
false, kesalahan selama startup mengakibatkan host keluar. Ketika true, host menangkap pengecualian selama startup dan mencoba memulai server.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_}CAPTURESTARTUPERRORSCaptureStartupErrors:
webBuilder.CaptureStartupErrors(true);
DetailedErrors
Development, aplikasi menangkap kesalahan terperinci.detailedErrors
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}DETAILEDERRORSUseSetting:
webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
HostingStartupAssemblies
hostingStartupAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPASSEMBLIESUseSetting:
webBuilder.UseSetting(
WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");
HostingStartupExcludeAssemblies
hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIESUseSetting:
webBuilder.UseSetting(
WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");
HTTPS_Port
https_port
Jenis: string
Default: Nilai default tidak diatur.
Variabel lingkungan: {PREFIX_}HTTPS_PORTUseSetting:
webBuilder.UseSetting("https_port", "8080");
PreferHostingUrls
IWebHostBuilder alih-alih URL yang dikonfigurasi dengan IServer implementasi.preferHostingUrls
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}PREFERHOSTINGURLSPreferHostingUrls:
webBuilder.PreferHostingUrls(true);
PreventHostingStartup
preventHostingStartup
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}PREVENTHOSTINGSTARTUPUseSetting :
webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");
StartupAssembly
Startup mencari kelas.startupAssembly
Jenis: string
Default: Rakitan aplikasi
Variabel lingkungan: {PREFIX_}STARTUPASSEMBLYUseStartup. 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
suppressStatusMessages
Jenis: bool (true/1 atau false/0)
Default: false
Variabel lingkungan: {PREFIX_}SUPPRESSSTATUSMESSAGESUseSetting:
webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");
URL
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.urls
Jenis: string
Default: http://localhost:5000 dan https://localhost:5001
Variabel lingkungan: {PREFIX_}URLSUseUrls:
webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");
Webroot
webroot
Jenis: string
Default: Defaultnya adalah wwwroot. Jalur ke {content root}/wwwroot harus ada.
Variabel lingkungan: {PREFIX_}WEBROOTUseWebRoot pada IWebHostBuilder:
webBuilder.UseWebRoot("public");
Mengelola masa pakai host
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
RunAsync
RunConsoleAsync
Mulai
StartAsync
StartAsync, yang menunggu sampai selesai sebelum melanjutkan. Metode ini dapat digunakan untuk menunda startup hingga disinyalir oleh peristiwa eksternal.StopAsync
WaitForShutdown
WaitForShutdownAsync
Templat ASP.NET Core membuat .NET Core Generic Host (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)
- 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.
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
CreateHostBuilderuntuk membuat dan mengonfigurasi objek penyusun. BuildPanggilan danRunmetode 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.
- Variabel lingkungan yang diawali dengan
- 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_ENABLEDsama dengantrue. - 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 menunjukkan cara mengambil alih pengaturan penyusun default.
Layanan yang disediakan kerangka kerja
Layanan berikut terdaftar secara otomatis:
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:
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:
// 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
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("c:\\content-root")
//...
Untuk informasi selengkapnya, lihat:
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 defaultnya adalah lima detik. Selama periode batas waktu, host:
- 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: 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 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: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 aktif IWebHostBuilder tersedia untuk pengaturan ini. Sampel kode yang menunjukkan cara memanggil metode ekstensi mengasumsikan webBuilder adalah instans IWebHostBuilder, seperti dalam contoh berikut:
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.
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
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: 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:
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 .
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 .NET Core Generic Host (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)
- 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.
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
CreateHostBuilderuntuk membuat dan mengonfigurasi objek penyusun. BuildPanggilan danRunmetode 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.
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.
- Variabel lingkungan yang diawali dengan
- 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 Kestrel server web di ASP.NET Core.
- Menambahkan middleware Pemfilteran Host.
- Menambahkan middleware Header yang Diteruskan jika
ASPNETCORE_FORWARDEDHEADERS_ENABLEDsama dengantrue. - 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 menunjukkan cara mengambil alih pengaturan penyusun default.
Layanan yang disediakan kerangka kerja
Layanan berikut terdaftar secara otomatis:
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:
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:
// 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
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 konfigurasi berikut untuk {PREFIX_} tempat penampung.
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("c:\\content-root")
//...
Untuk informasi selengkapnya, lihat:
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 defaultnya adalah lima detik. Selama periode batas waktu, host:
- 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: 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
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_ .
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:
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.
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
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: 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 Kestrel 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.
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 .
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 .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).
ASP.NET Core
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk