lingkungan runtime ASP.NET Core

ASP.NET Core mengonfigurasi perilaku aplikasi berdasarkan lingkungan runtime, yang biasanya mencerminkan tempat aplikasi berjalan.

Aplikasi biasanya berjalan di lingkungan Pengembangan selama pengembangan dan pengujian lokal pada komputer pengembang dengan satu set perilaku yang dikonfigurasi. Sebaliknya, mereka berjalan di lingkungan Produksi saat disebarkan ke server dengan serangkaian perilaku yang dikonfigurasi yang berbeda. Sejumlah lingkungan tambahan dapat digunakan, seperti lingkungan Penahapan yang disediakan oleh kerangka kerja untuk penahapan aplikasi sebelum penyebaran langsung atau lingkungan lain yang dibuat pengembang.

Artikel ini menjelaskan lingkungan runtime aplikasi, cara menggunakan lingkungan untuk mengontrol perilaku aplikasi, dan cara mengatur lingkungan.

Untuk Blazor panduan lingkungan, yang menambahkan atau menggantikan panduan dalam artikel ini, lihat lingkungan ASP.NET CoreBlazor.

Environments

Meskipun lingkungan dapat berupa nilai string apa pun, nilai lingkungan berikut disediakan oleh kerangka kerja:

• Development
• Staging
• Production

Lingkungan Produksi dikonfigurasi untuk memaksimalkan keamanan, performa, dan keandalan aplikasi. Pengaturan dan konfigurasi pengembang umum yang berbeda dari lingkungan Pengembangan meliputi:

• Mengaktifkan cache.
• Menggabungkan dan mengecilkan resource klien, bersama dengan menyajikannya dari CDN.
• Menonaktifkan halaman kesalahan diagnostik dan mengaktifkan halaman kesalahan yang ramah pengguna.
• Mengaktifkan pengelogan dan pemantauan produksi. Misalnya, pengelogan diaktifkan untuk Azure Application Insights.

Pengaturan lingkungan terakhir yang dibaca oleh aplikasi menentukan lingkungan aplikasi. Lingkungan aplikasi tidak dapat diubah saat aplikasi sedang berjalan.

Penebangan kayu

Output pada antarmuka baris perintah aplikasi yang sedang berjalan pada saat startup menunjukkan lingkungan dari aplikasi tersebut. Dalam contoh berikut, aplikasi berjalan di lingkungan *Staging*:

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

Variabel lingkungan yang menentukan lingkungan runtime

Untuk menentukan lingkungan runtime, ASP.NET Core membaca dari variabel lingkungan berikut:

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

Saat menggunakan WebApplication, DOTNET_ENVIRONMENT nilai lebih diutamakan daripada ASPNETCORE_ENVIRONMENT. Saat menggunakan WebHost, ASPNETCORE_ENVIRONMENT lebih diutamakan.

DOTNET_ENVIRONMENT Jika variabel lingkungan dan ASPNETCORE_ENVIRONMENT tidak diatur, lingkungan Produksi adalah lingkungan default.

Di Windows dan macOS, nama variabel lingkungan tidak peka terhadap huruf besar atau kecil. Variabel lingkungan Linux peka terhadap huruf besar dan kecil.

Mengontrol eksekusi kode berdasarkan lingkungan

Gunakan WebApplicationBuilder.Environment atau WebApplication.Environment untuk menambahkan layanan atau middleware secara kondisional tergantung pada lingkungan saat ini.

Kode berikut dalam file aplikasi Program :

• Menggunakan WebApplication.Environment untuk membedakan lingkungan.
• UseExceptionHandlerPanggilan , yang menambahkan Middleware Handler Pengecualian ke alur pemrosesan permintaan untuk menangani pengecualian.
• Panggilan UseHsts, yang menambahkan Middleware HSTS untuk menerapkan header Strict-Transport-Security.

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

Contoh sebelumnya memeriksa lingkungan saat ini untuk alur pemrosesan permintaan. Untuk memeriksa lingkungan saat ini saat mengonfigurasi layanan, gunakan builder.Environment alih-alih app.Environment.

Dalam aplikasi, IHostEnvironment memberikan informasi umum tentang lingkungan hosting aplikasi, dan IHostEnvironment.EnvironmentName properti menunjukkan lingkungan aplikasi saat ini.

Mengontrol konten yang dirender

IHostEnvironment Disuntikkan ke dalam komponen yang dirender oleh server Razor dan gunakan metode ekstensi serta properti EnvironmentName dari layanan untuk menentukan lingkungan untuk menyajikan konten:

@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>
}

Untuk Blazor Web App yang memerlukan lingkungan untuk mengontrol rendering sisi klien, lihat Prarender komponen ASP.NET CoreRazor.

Mengatur lingkungan dalam shell perintah saat aplikasi dijalankan (dotnet run)

-e|--environment Gunakan opsi untuk mengatur lingkungan:

dotnet run -e Staging

Mengatur lingkungan dengan file pengaturan peluncuran (launchSettings.json)

Lingkungan untuk pengembangan lokal dapat diatur dalam Properties\launchSettings.json file proyek. Nilai lingkungan yang diatur dalam launchSettings.json mengambil alih nilai yang ditetapkan oleh lingkungan sistem.

File launchSettings.json:

• Hanya digunakan pada komputer pengembangan lokal.
• Tidak disebarkan saat aplikasi diterbitkan.
• Mungkin berisi beberapa profil, masing-masing mengonfigurasi lingkungan yang berbeda.

Contoh berikut mengonfigurasi lingkungan Penahapan pada profil peluncuran https menggunakan variabel lingkungan ASPNETCORE_ENVIRONMENT.

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

Di Visual Studio, ada dua pendekatan untuk mengatur lingkungan melalui profil peluncuran:

• Tekan Alt+Enter atau pilih Properti setelah mengklik kanan proyek di Penjelajah Solusi. Pilih Debug>Umum, diikuti dengan memilih tautan Buka antarmuka pengguna profil peluncuran debug .

• Dengan proyek dipilih di Penjelajah Solusi, pilih {PROJECT NAME} Properti Debug dari menu Debug di mana placeholder {PROJECT NAME} adalah nama proyek.

Pendekatan sebelumnya membuka dialog Luncurkan Profil tempat Anda dapat mengedit pengaturan variabel lingkungan dalam launchSettings.json file. Perubahan yang dilakukan pada profil proyek mungkin tidak berlaku sampai server web dimulai ulang. Kestrel harus dimulai ulang sebelum dapat mendeteksi perubahan yang dilakukan pada lingkungannya.

Profil dapat dipilih di UI Visual Studio di samping tombol Mulai (►).

Saat solusi berisi beberapa proyek, hanya atur lingkungan untuk proyek startup.

Atau, gunakan perintah dotnet run dengan opsi -lp|--launch-profile yang diatur ke nama profil. Pendekatan ini hanya mendukung profil peluncuran berdasarkan Project perintah .

dotnet run -lp "https"

Saat menggunakan Visual Studio Code dengan C# Dev Kit untuk Visual Studio Code (Memulai C# di VS Code), profil peluncuran dimuat dari file aplikasi launchSettings.json.

Jika C# Dev Kit tidak digunakan, atur ASPNETCORE_ENVIRONMENT variabel lingkungan di .vscode/launch.json bagian env , bersama dengan variabel lingkungan lain yang diatur di bagian :

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

File .vscode/launch.json hanya digunakan oleh Visual Studio Code.

Mengatur lingkungan dengan variabel lingkungan

Seringkali berguna untuk mengatur lingkungan tertentu untuk pengujian dengan variabel lingkungan atau pengaturan platform. Jika lingkungan tidak diatur, maka secara otomatis akan mengarah ke lingkungan Produksi, yang akan menonaktifkan sebagian besar fitur debugging. Metode untuk mengatur lingkungan tergantung pada sistem operasi.

Azure App Service

Aplikasi yang disebarkan ke Azure App Service mengadopsi lingkungan Produksi secara default.

Untuk mengatur ASPNETCORE_ENVIRONMENT variabel lingkungan, lihat sumber daya berikut dalam dokumentasi Azure:

• Mengonfigurasi aplikasi App Service
• Menyiapkan lingkungan penahapan di Azure App Service

Azure App Service secara otomatis memulai ulang aplikasi setelah pengaturan aplikasi ditambahkan, diubah, atau dihapus.

Mengatur variabel lingkungan untuk proses

Untuk mengatur ASPNETCORE_ENVIRONMENT variabel lingkungan untuk sesi saat ini (shell perintah) saat aplikasi mulai menggunakan dotnet run, gunakan perintah berikut. Setelah variabel lingkungan diatur, aplikasi dimulai tanpa profil peluncuran menggunakan opsi --no-launch-profile.

1. Di shell perintah, atur variabel lingkungan menggunakan pendekatan yang sesuai untuk sistem operasi Anda.

2. Jalankan dotnet run perintah tanpa menggunakan profil peluncuran:

   dotnet run --no-launch-profile
   

Saat menggunakan PowerShell, langkah-langkah sebelumnya dapat digabungkan dalam dua perintah berikut. Contoh berikut mengkonfigurasi lingkungan Penahapan:

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

Mengatur variabel lingkungan secara global

Gunakan panduan yang sesuai untuk sistem operasi Anda untuk mengatur ASPNETCORE_ENVIRONMENT variabel lingkungan.

Ketika variabel lingkungan ASPNETCORE_ENVIRONMENT diatur secara global, variabel tersebut berlaku untuk perintah dotnet run di dalam shell perintah apa pun yang dibuka setelah nilai tersebut diatur. Nilai lingkungan yang ditetapkan oleh profil peluncuran dalam berkas launchSettings.json akan menimpa nilai yang ditetapkan untuk lingkungan sistem.

Mengatur lingkungan untuk aplikasi yang disebarkan ke IIS

Untuk mengatur variabel lingkungan ASPNETCORE_ENVIRONMENT dengan file web.config, lihat web.config file.

Untuk mengatur variabel lingkungan pada penyebaran ke IIS, sertakan <EnvironmentName> properti dalam profil penerbitan (.pubxml) atau file proyek. Contoh berikut menetapkan variabel lingkungan di web.config ke lingkungan Staging ketika proyek dipublikasikan:

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

Untuk mengatur ASPNETCORE_ENVIRONMENT variabel lingkungan untuk aplikasi yang berjalan di Kumpulan Aplikasi terisolasi (didukung pada IIS 10.0 atau yang lebih baru), lihat Variabel Lingkungan <variabelLingkungan>. ASPNETCORE_ENVIRONMENT Ketika variabel lingkungan diatur untuk Kumpulan Aplikasi, nilainya mengambil alih pengaturan di tingkat sistem.

Saat menghosting aplikasi di IIS dan menambahkan atau mengubah ASPNETCORE_ENVIRONMENT variabel lingkungan, gunakan salah satu pendekatan berikut agar nilai baru berlaku untuk menjalankan aplikasi:

• Jalankan net stop was /y diikuti dengan net start w3svc dalam shell perintah.
• Mulai ulang server.

Docker

Atur lingkungan aplikasi menggunakan salah satu pendekatan di bagian ini.

Menggunakan Dockerfile

Atur variabel lingkungan ASPNETCORE_ENVIRONMENT dalam Dockerfile menggunakan perintah ENV instruksi:

ENV ASPNETCORE_ENVIRONMENT=Staging

Menggunakan Docker Compose

Untuk aplikasi multi-layanan yang dikelola dengan Docker Compose, tentukan ASPNETCORE_ENVIRONMENT variabel lingkungan dalam docker-compose.yml file:

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

Lingkungan yang ditetapkan pada waktu proses dengan Docker Compose menggantikan lingkungan yang ditetapkan oleh Dockerfile.

Gunakan perintah docker run

Saat menjalankan kontainer Docker dengan docker run perintah , Atur ASPNETCORE_ENVIRONMENT variabel lingkungan dengan -e|--env opsi :

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Lingkungan yang ditentukan pada saat runtime dengan docker run menggantikan lingkungan yang ditetapkan oleh Dockerfile.

Berkas konfigurasi lingkungan Docker

Atur ASPNETCORE_ENVIRONMENT variabel lingkungan menggunakan file lingkungan Docker (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Muat file dengan opsi --env-file saat menggunakan perintah docker run:

docker run --env-file ./env_variables.env aspnet_core_image

Lingkungan yang ditentukan pada saat runtime dengan docker run menggantikan lingkungan yang ditetapkan oleh Dockerfile.

Mengatur lingkungan dalam kode startup aplikasi

Untuk mengatur lingkungan dalam kode, gunakan WebApplicationOptions.EnvironmentName saat membuat WebApplicationBuilder, seperti yang ditunjukkan dalam contoh berikut:

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

Memuat konfigurasi menurut lingkungan

Untuk memuat konfigurasi menurut lingkungan, lihat Konfigurasi di ASP.NET Core.

Mengakses lingkungan dari Startup kelas

Penggunaan kelas Startup (Startup.cs) dengan metode Configure dan ConfigureServices diwajibkan sebelum rilis .NET 6 dan tetap didukung.

Suntikkan IWebHostEnvironment ke dalam Startup konstruktor untuk mengontrol eksekusi kode. Pendekatan ini berguna ketika aplikasi memerlukan konfigurasi kode startup hanya untuk beberapa lingkungan dengan perbedaan kode minimal per lingkungan.

Dalam contoh berikut, lingkungan ditahan di _env bidang dan mengontrol eksekusi kode berdasarkan lingkungan aplikasi:

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
        {
            ...
        }

        ...
    }
}

Kelas khusus Startup lingkungan

Aplikasi dapat menentukan beberapa kelas Startup untuk lingkungan yang berbeda dengan penamaan kelas Startup{EnvironmentName}, di mana {ENVIRONMENT NAME} pengganti adalah nama lingkungan.

Kelas yang akhiran namanya cocok dengan lingkungan saat ini diprioritaskan. Jika kelas yang Startup{EnvironmentName} cocok tidak ditemukan, Startup kelas akan digunakan.

Untuk menerapkan kelas berbasis Startup lingkungan, buat kelas sebanyak Startup{EnvironmentName} yang diperlukan dan kelas fallback Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Di mana pembangun host dibuat, panggil HostingAbstractionsWebHostBuilderExtensions.UseStartup, yang menerima nama rakitan untuk memuat kelas yang benar Startup :

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

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

Metode-metode kelas yang khusus untuk Startup lingkungan

Metode Configure dan ConfigureServices mendukung versi-versi formulir Configure{ENVIRONMENT NAME} dan Configure{ENVIRONMENT NAME}Services yang spesifik terhadap lingkungan, di mana {ENVIRONMENT NAME} tempat penampung adalah nama lingkungan. Jika nama lingkungan yang cocok tidak ditemukan untuk metode bernama, maka metode ConfigureServices atau Configure digunakan masing-masing sesuai kondisi tersebut.

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

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

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

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

Sumber daya tambahan

• Melihat atau mengunduh kode sampel (cara mengunduh)
• Startup aplikasi di ASP.NET Core
• Konfigurasi di ASP.NET Core
• Lingkungan Blazor ASP.NET Core