.NET Generic Host (Host Chung) trong ASP.NET Core

Nguồn: .NET Generic Host in ASP.NET Core

Các template ASP.NET Core tạo ra các instance của WebApplicationBuilder và WebApplication. Các đối tượng này cung cấp cách cấu hình và chạy web application một cách tinh gọn mà không cần class Startup. Để biết thêm về WebApplicationBuilder và WebApplication, xem Migrate from ASP.NET Core in .NET 5 to .NET 6.

Bài viết này cung cấp thông tin về cách sử dụng .NET Generic Host trong ASP.NET Core. Để biết thông tin về việc sử dụng .NET Generic Host trong console app, xem .NET Generic Host.

Hiểu vai trò của host (máy chủ lưu trữ)

Một host (máy chủ lưu trữ) là một đối tượng đóng gói các tài nguyên của ứng dụng, bao gồm:

Dependency injection (DI) (tiêm phụ thuộc)
Logging (ghi nhật ký)
Configuration (cấu hình)
Các implementation IHostedService

Khi host khởi động, nó gọi phương thức StartAsync trên mỗi instance IHostedService được đăng ký trong collection hosted services của service container. Trong web app, một trong các implementation IHostedService là web service khởi động HTTP server.

Bằng cách bao gồm tất cả các tài nguyên phụ thuộc lẫn nhau của ứng dụng trong một đối tượng, host cho phép kiểm soát việc khởi động ứng dụng và shutdown (tắt) một cách nhẹ nhàng (graceful shutdown).

Thiết lập host

Host thường được cấu hình, xây dựng và chạy bởi code trong file Program.cs.

Đoạn code sau tạo một host với implementation IHostedService được thêm vào DI container:

csharp

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

Với HTTP workload (tác vụ HTTP), gọi phương thức ConfigureWebHostDefaults sau phương thức CreateDefaultBuilder:

csharp

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

Cấu hình default builder settings (cài đặt builder mặc định)

Phương thức CreateDefaultBuilder thực hiện các tác vụ sau:

Đặt content root theo đường dẫn trả về bởi GetCurrentDirectory.
Tải host configuration từ các nguồn sau:
Biến môi trường có tiền tố DOTNET_
Command-line arguments (đối số dòng lệnh)
Tải app configuration theo thứ tự sau:
File appsettings.json
File appsettings.{Environment}.json
User secrets (được tải khi ứng dụng chạy trong môi trường Development sử dụng entry assembly)
Biến môi trường
Command-line arguments
Thêm các logging providers sau:
Console
Debug
EventSource
EventLog (chỉ khi chạy trên Windows)
Bật scope validation và dependency validation khi môi trường là Development.

Phương thức ConfigureWebHostDefaults thực hiện các tác vụ sau:

Tải host configuration từ biến môi trường có tiền tố ASPNETCORE_.
Đặt Kestrel server làm web server và cấu hình nó bằng cách sử dụng các hosting configuration providers của ứng dụng.
Thêm Host Filtering middleware.
Thêm Forwarded Headers middleware nếu thuộc tính ASPNETCORE_FORWARDEDHEADERS_ENABLED được đặt thành true.
Bật tích hợp IIS.

Các services được cung cấp bởi framework

.NET Generic Host tự động đăng ký các services sau:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

IHostApplicationLifetime

Inject IHostApplicationLifetime (trước đây là IApplicationLifetime) vào bất kỳ class nào để xử lý các tác vụ sau startup và graceful shutdown. Ba thuộc tính trên interface là cancellation token dùng để đăng ký app start và app stop event handler methods. Interface cũng bao gồm phương thức StopApplication, cho phép ứng dụng yêu cầu graceful shutdown.

Khi thực hiện graceful shutdown, host:

Kích hoạt các event handler ApplicationStopping, cho phép ứng dụng chạy logic trước khi quá trình shutdown bắt đầu.
Dừng server, điều này vô hiệu hóa các kết nối mới. Server chờ các request trên các kết nối hiện có hoàn thành, trong khoảng thời gian shutdown timeout cho phép.
Kích hoạt các event handler ApplicationStopped, cho phép ứng dụng chạy logic sau khi ứng dụng đã shutdown.

Ví dụ sau là implementation IHostedService đăng ký các event handler IHostApplicationLifetime:

csharp

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

Implementation IHostLifetime kiểm soát khi nào host khởi động và khi nào nó dừng. Implementation cuối cùng được đăng ký sẽ được sử dụng.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime là implementation IHostLifetime mặc định.

Phương thức ConsoleLifetime thực hiện các tác vụ sau:

Lắng nghe Ctrl+C/SIGINT (Windows), Ctrl+C (macOS), hoặc SIGTERM và gọi StopApplication, để bắt đầu quá trình shutdown.
Mở khóa các extensions như bằng cách chạy các phương thức RunAsync và WaitForShutdownAsync.

IHostEnvironment (IWebHostEnvironment)

Inject service IHostEnvironment vào một class để lấy thông tin về các cài đặt sau:

ApplicationName
EnvironmentName
ContentRootPath

Web app implement interface IWebHostEnvironment, kế thừa IHostEnvironment và thêm WebRootPath.

Thiết lập host configuration (cấu hình host)

Host configuration được sử dụng cho các thuộc tính của implementation IHostEnvironment.

Host configuration có sẵn từ thuộc tính Configuration bên trong phương thức ConfigureAppConfiguration. Sau ConfigureAppConfiguration, HostBuilderContext.Configuration được thay thế bằng app config.

Để thêm host configuration, gọi phương thức ConfigureHostConfiguration trên instance IHostBuilder. ConfigureHostConfiguration có thể được gọi nhiều lần với kết quả bổ sung. Host sử dụng tùy chọn nào đặt giá trị cuối cùng trên một key nhất định.

CreateDefaultBuilder bao gồm environment variable provider với tiền tố DOTNET_ và command-line arguments. Với web app, environment variable provider với tiền tố ASPNETCORE_ được thêm vào. Tiền tố bị xóa khi biến môi trường được đọc.

Ví dụ sau tạo host configuration:

csharp

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

Tạo app configuration (cấu hình ứng dụng)

App configuration được tạo bằng cách gọi phương thức ConfigureAppConfiguration trên instance IHostBuilder. ConfigureAppConfiguration có thể được gọi nhiều lần với kết quả bổ sung. Ứng dụng sử dụng tùy chọn nào đặt giá trị cuối cùng trên một key nhất định.

Để biết thêm, xem Configuration in ASP.NET Core.

Cấu hình settings cho tất cả loại ứng dụng

Phần này liệt kê các host settings áp dụng cho cả HTTP và non-HTTP workloads.

Theo mặc định, biến môi trường dùng để cấu hình các settings này có thể có tiền tố DOTNET_ hoặc ASPNETCORE_, xuất hiện trong danh sách settings sau đây là placeholder {PREFIX_}.

Application name (Tên ứng dụng)

Định nghĩa tên của assembly chứa entry point cho ứng dụng.

Key: applicationName | Type: string | Default: Tên assembly có entry point của ứng dụng | Biến môi trường: {PREFIX_}APPLICATIONNAME

Content root

Xác định nơi host bắt đầu tìm kiếm các file nội dung.

Key: contentRoot | Type: string | Default: Thư mục chứa app assembly | Biến môi trường: {PREFIX_}CONTENTROOT

Nếu đường dẫn không tồn tại, host sẽ không khởi động được.

csharp

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

Environment name (Tên môi trường)

Cung cấp tên cho môi trường.

Key: environment | Type: string | Default: Production | Biến môi trường: {PREFIX_}ENVIRONMENT

Thuộc tính EnvironmentName có thể được đặt thành bất kỳ giá trị nào. Các giá trị được định nghĩa bởi framework bao gồm Development, Staging và Production. Các giá trị không phân biệt chữ hoa/thường.

csharp

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

Shutdown timeout (Thời gian chờ tắt máy)

Chỉ định thời gian chờ để host tắt máy.

Key: shutdownTimeoutSeconds | Type: int | Default: 30 giây | Biến môi trường: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Trong thời gian timeout, host:

Kích hoạt ApplicationStopping.
Cố gắng dừng hosted services, ghi lỗi cho các services không thể dừng.

Ví dụ đặt timeout thành 20 giây:

csharp

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

Reload config on change (Tải lại cấu hình khi thay đổi)

Tải lại các file appsettings.json và appsettings.{Environment}.json khi file thay đổi. Hành vi này là mặc định.

Key: hostBuilder:reloadConfigOnChange | Type: bool | Default: true

Cấu hình settings cho web app

Một số host settings chỉ áp dụng cho HTTP workloads. Theo mặc định, biến môi trường dùng để cấu hình các settings này có thể có tiền tố DOTNET_ hoặc ASPNETCORE_, xuất hiện là placeholder {PREFIX_}.

Các extension methods trên IWebHostBuilder có sẵn cho các settings này. Ví dụ code giả định webBuilder là instance của IWebHostBuilder:

csharp

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

Capture startup errors (Bắt lỗi khởi động)

Kiểm soát việc bắt lỗi khởi động.

Key: captureStartupErrors | Default: false (Nếu ứng dụng chạy với Kestrel phía sau IIS, mặc định là true)

Khi false, lỗi trong quá trình khởi động dẫn đến host thoát. Khi true, host bắt exception trong quá trình khởi động và cố gắng khởi động server.

csharp

webBuilder.CaptureStartupErrors(true);

Detailed errors (Lỗi chi tiết)

Xác định có bắt lỗi chi tiết hay không.

Key: detailedErrors | Default: false

Khi được bật, hoặc khi môi trường được đặt thành Development, ứng dụng bắt lỗi chi tiết.

csharp

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

Hosting startup assemblies (Assembly khởi động hosting)

Cung cấp chuỗi phân cách bởi dấu chấm phẩy của các hosting startup assemblies để tải khi khởi động.

Key: hostingStartupAssemblies | Default: Chuỗi rỗng

csharp

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

HTTPS port

Đặt HTTPS port để chuyển hướng nếu nhận được kết nối không phải HTTPS.

Key: https_port

csharp

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

Server URLs (URL của server)

Chỉ định các địa chỉ IP hoặc host addresses với ports và protocols mà server nên lắng nghe requests.

Key: urls | Default: http://localhost:5000 và https://localhost:5001

Đặt thành danh sách phân cách bởi dấu chấm phẩy ; các URL prefix mà server phải phản hồi.

csharp

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

Kestrel có API cấu hình endpoint riêng. Để biết thêm, xem Configure endpoints for Kestrel web server.

Web root

Đặt đường dẫn tương đối đến các static assets của ứng dụng.

Key: webroot | Default: wwwroot

csharp

webBuilder.UseWebRoot("public");

Startup assembly (Assembly khởi động)

Chỉ định assembly để tìm kiếm class Startup.

Key: startupAssembly | Default: Application assembly

csharp

webBuilder.UseStartup("StartupAssemblyName");

csharp

webBuilder.UseStartup<Startup>();

Quản lý host lifetime (vòng đời host)

Để khởi động và dừng ứng dụng, gọi các phương thức trên implementation IHost. Các phương thức ảnh hưởng đến tất cả các implementation IHostedService được đăng ký trong service container.

Sự khác biệt giữa các phương thức Run* và Start* là phương thức Run* chờ host hoàn thành trước khi trả về, trong khi phương thức Start* trả về ngay lập tức.

Run

Phương thức Run chạy ứng dụng và block calling thread cho đến khi host shutdown.

RunAsync

Phương thức RunAsync chạy ứng dụng và trả về đối tượng Task hoàn thành khi cancellation token hoặc shutdown được kích hoạt.

Start

Phương thức Start khởi động host đồng bộ.

StartAsync

Phương thức StartAsync khởi động host và trả về đối tượng Task hoàn thành khi cancellation token hoặc shutdown được kích hoạt.

StopAsync

Phương thức StopAsync cố gắng dừng host trong thời gian timeout được cung cấp.

WaitForShutdown

Phương thức WaitForShutdown block calling thread cho đến khi implementation IHostLifetime kích hoạt shutdown thông qua Ctrl+C/SIGINT (Windows), Ctrl+C (macOS), hoặc SIGTERM.

WaitForShutdownAsync

Phương thức WaitForShutdownAsync trả về đối tượng Task hoàn thành khi shutdown được kích hoạt thông qua token đã cho, sau đó gọi phương thức StopAsync.