Môi trường runtime (Runtime environments) của ASP.NET Core

Nguồn: ASP.NET Core runtime environments

ASP.NET Core cấu hình hành vi ứng dụng dựa trên environment (môi trường) runtime, thường phản ánh nơi ứng dụng đang chạy.

Ứng dụng thường chạy trong môi trường Development (phát triển) trong quá trình phát triển và kiểm thử cục bộ trên máy của developer với một bộ hành vi được cấu hình. Ngược lại, chúng chạy trong môi trường Production (sản xuất) khi được triển khai lên server với một bộ hành vi được cấu hình khác. Bất kỳ số lượng môi trường bổ sung nào cũng có thể được sử dụng, chẳng hạn như môi trường Staging (dàn dựng) được cung cấp bởi framework.

Bài viết này mô tả các môi trường runtime của ứng dụng, cách sử dụng môi trường để kiểm soát hành vi ứng dụng và cách đặt môi trường.

Environments (Môi trường)

Mặc dù môi trường có thể là bất kỳ giá trị chuỗi nào, các giá trị môi trường sau được cung cấp bởi framework:

Môi trường Production được cấu hình để tối đa hóa bảo mật, hiệu suất và độ tin cậy của ứng dụng. Các cài đặt developer phổ biến và cấu hình khác với môi trường Development bao gồm:

Bật caching.
Bundling và minifying các tài nguyên client-side, cùng với việc phục vụ chúng từ CDN.
Vô hiệu hóa các trang lỗi diagnostic và bật các trang lỗi thân thiện.
Bật production logging và monitoring. Ví dụ, logging được bật cho Azure Application Insights.

Logging

Output trong command shell của ứng dụng đang chạy khi khởi động cho biết môi trường của ứng dụng. Trong ví dụ sau, ứng dụng đang chạy trong môi trường Staging:

dotnetcli

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Biến môi trường xác định môi trường runtime

Để xác định môi trường runtime, ASP.NET Core đọc từ các biến môi trường sau:

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT

Khi sử dụng WebApplication, giá trị DOTNET_ENVIRONMENT có độ ưu tiên cao hơn ASPNETCORE_ENVIRONMENT. Khi sử dụng WebHost, ASPNETCORE_ENVIRONMENT có độ ưu tiên cao hơn.

Nếu biến môi trường DOTNET_ENVIRONMENT và ASPNETCORE_ENVIRONMENT không được đặt, môi trường Production là môi trường mặc định.

Trên Windows và macOS, tên biến môi trường không phân biệt chữ hoa/thường. Biến môi trường Linux phân biệt chữ hoa/thường.

Kiểm soát thực thi code theo môi trường

Sử dụng WebApplicationBuilder.Environment hoặc WebApplication.Environment để thêm services hoặc middleware có điều kiện tùy thuộc vào môi trường hiện tại.

Đoạn code sau trong file Program của ứng dụng:

Sử dụng WebApplication.Environment để phân biệt môi trường.
Gọi UseExceptionHandler, thêm Exception Handler Middleware vào request processing pipeline để xử lý exceptions.
Gọi UseHsts, thêm HSTS Middleware để áp dụng header Strict-Transport-Security.

csharp

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

Ví dụ trên kiểm tra môi trường hiện tại cho request processing pipeline. Để kiểm tra môi trường hiện tại trong khi cấu hình services, sử dụng builder.Environment thay vì app.Environment.

Kiểm soát nội dung được render

Inject IHostEnvironment vào Razor component được render từ server và sử dụng các extension methods của service cùng thuộc tính EnvironmentName để xác định môi trường cho việc render nội dung:

razor

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Đặt môi trường trong command shell khi chạy ứng dụng (`dotnet run`)

Sử dụng tùy chọn -e|--environment để đặt môi trường:

dotnetcli

dotnet run -e Staging

Đặt môi trường với file launch settings (`launchSettings.json`)

Môi trường cho local development có thể được đặt trong file Properties\launchSettings.json của project. Các giá trị môi trường được đặt trong launchSettings.json sẽ ghi đè các giá trị được đặt bởi system environment.

File launchSettings.json:

Chỉ được sử dụng trên máy development cục bộ.
Không được triển khai khi ứng dụng được publish.
Có thể chứa nhiều profiles, mỗi profile cấu hình một môi trường khác nhau.

Ví dụ sau đặt môi trường Staging cho launch profile https sử dụng biến môi trường ASPNETCORE_ENVIRONMENT:

json

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

Trong Visual Studio, có hai cách tiếp cận để đặt môi trường thông qua launch profiles:

Nhấn Alt+Enter hoặc chọn Properties sau khi nhấp chuột phải vào project trong Solution Explorer. Chọn Debug > General, sau đó chọn liên kết Open debug launch profiles UI.
Với project được chọn trong Solution Explorer, chọn {PROJECT NAME} Debug Properties từ menu Debug.

Để chạy với launch profile khác, sử dụng tùy chọn -lp|--launch-profile với lệnh dotnet run:

dotnetcli

dotnet run -lp "https"

Đặt môi trường với biến môi trường

Thường hữu ích khi đặt một môi trường cụ thể để kiểm thử với biến môi trường hoặc cài đặt platform. Nếu môi trường không được đặt, nó mặc định là môi trường Production.

Azure App Service

Ứng dụng được triển khai lên Azure App Service mặc định áp dụng môi trường Production.

Để đặt biến môi trường ASPNETCORE_ENVIRONMENT, xem Configure an App Service app.

Đặt biến môi trường cho một process

Để đặt biến môi trường ASPNETCORE_ENVIRONMENT cho session hiện tại (command shell) khi ứng dụng được khởi động sử dụng dotnet run, sử dụng các lệnh sau.

Sử dụng PowerShell, ví dụ sau đặt môi trường Staging:

powershell

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

Đặt biến môi trường toàn cục

Khi biến môi trường ASPNETCORE_ENVIRONMENT được đặt toàn cục, nó có hiệu lực cho lệnh dotnet run trong bất kỳ command shell nào được mở sau khi giá trị được đặt.

Đặt môi trường cho ứng dụng được triển khai lên IIS

Để đặt biến môi trường ASPNETCORE_ENVIRONMENT với file web.config, xem web.config file.

Để đặt biến môi trường khi triển khai lên IIS, bao gồm thuộc tính <EnvironmentName> trong publish profile (.pubxml) hoặc project file. Ví dụ sau đặt môi trường thành Staging trong web.config khi project được publish:

xml

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

Docker

Để đặt môi trường trong Dockerfile:

code

ENV ASPNETCORE_ENVIRONMENT=Staging

Với Docker Compose:

code

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Đặt môi trường trong startup code của ứng dụng

Để đặt môi trường trong code, sử dụng WebApplicationOptions.EnvironmentName khi tạo WebApplicationBuilder:

csharp

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
});

Tải cấu hình theo môi trường

Để tải cấu hình theo môi trường, xem Configuration in ASP.NET Core.

Truy cập môi trường từ class `Startup`

Inject IWebHostEnvironment vào constructor Startup để kiểm soát thực thi code. Cách tiếp cận này hữu ích khi ứng dụng yêu cầu cấu hình startup code chỉ cho một vài môi trường với sự khác biệt code tối thiểu mỗi môi trường.

Trong ví dụ sau, môi trường được giữ trong trường _env và kiểm soát thực thi code dựa trên môi trường ứng dụng:

csharp

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Environment-specific `Startup` class (Class Startup theo môi trường)

Ứng dụng có thể định nghĩa nhiều class Startup cho các môi trường khác nhau với quy ước đặt tên Startup{EnvironmentName}.

Class có tên suffix khớp với môi trường hiện tại được ưu tiên. Nếu không tìm thấy class Startup{EnvironmentName} phù hợp, class Startup sẽ được sử dụng.

csharp

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Gọi HostingAbstractionsWebHostBuilderExtensions.UseStartup với tên assembly:

csharp

public static IHostBuilder CreateHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

Environment-specific `Startup` class methods (Phương thức Startup theo môi trường)

Các phương thức Configure và ConfigureServices hỗ trợ các phiên bản theo môi trường của dạng Configure{ENVIRONMENT NAME} và Configure{ENVIRONMENT NAME}Services.

csharp

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

Môi trường runtime (Runtime environments) của ASP.NET Core

Environments (Môi trường)

Logging

Biến môi trường xác định môi trường runtime

Kiểm soát thực thi code theo môi trường

Kiểm soát nội dung được render

Đặt môi trường trong command shell khi chạy ứng dụng (dotnet run)

Đặt môi trường với file launch settings (launchSettings.json)

Đặt môi trường với biến môi trường

Azure App Service

Đặt biến môi trường cho một process

Đặt biến môi trường toàn cục

Đặt môi trường cho ứng dụng được triển khai lên IIS

Docker

Đặt môi trường trong startup code của ứng dụng

Tải cấu hình theo môi trường

Truy cập môi trường từ class Startup

Environment-specific Startup class (Class Startup theo môi trường)

Environment-specific Startup class methods (Phương thức Startup theo môi trường)

Đặt môi trường trong command shell khi chạy ứng dụng (`dotnet run`)

Đặt môi trường với file launch settings (`launchSettings.json`)

Truy cập môi trường từ class `Startup`

Environment-specific `Startup` class (Class Startup theo môi trường)

Environment-specific `Startup` class methods (Phương thức Startup theo môi trường)