Gunakan beberapa lingkungan di ASP.NET Core

Oleh Rick Anderson dan Kirk Larkin

ASP.NET Core mengonfigurasi perilaku aplikasi berdasarkan lingkungan runtime menggunakan variabel lingkungan.

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

Lingkungan

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

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT ketika metode dipanggil WebApplication.CreateBuilder . Templat aplikasi web ASP.NET Core default memanggil WebApplication.CreateBuilder. Nilai DOTNET_ENVIRONMENT mengesampingkan ASPNETCORE_ENVIRONMENT saat WebApplicationBuilder digunakan. Untuk host lain, seperti ConfigureWebHostDefaults dan WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT memiliki prioritas yang lebih tinggi.

IHostEnvironment.EnvironmentName dapat diatur ke nilai apa pun, tetapi nilai berikut disediakan oleh kerangka kerja:

• Development: File launchSettings.json diatur ASPNETCORE_ENVIRONMENT ke Development pada komputer lokal.
• Staging
• Production: Default jika DOTNET_ENVIRONMENT dan ASPNETCORE_ENVIRONMENT belum ditetapkan.

Kode berikut:

• Mirip dengan kode yang dihasilkan oleh templat ASP.NET Core.
• Mengaktifkan Halaman Pengecualian Pengembang saat ASPNETCORE_ENVIRONMENT diatur ke Development. Ini dilakukan secara otomatis dengan WebApplication.CreateBuilder metode .
• UseExceptionHandler Memanggil ketika nilai ASPNETCORE_ENVIRONMENT adalah apa pun selain Development.
• IWebHostEnvironment Menyediakan instans di Environment properti .WebApplication

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Pembantu Tag Lingkungan menggunakan nilai IHostEnvironment.EnvironmentName untuk menyertakan atau mengecualikan markup dalam elemen:

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

Halaman Tentang dari kode sampel menyertakan markup sebelumnya dan menampilkan nilai IWebHostEnvironment.EnvironmentName.

Di Windows dan macOS, variabel dan nilai lingkungan tidak peka huruf besar/kecil. Variabel dan nilai lingkungan Linux peka huruf besar/kecil secara default.

Membuat EnvironmentsSample

Kode sampel yang digunakan dalam artikel ini didasarkan pada Razor proyek Pages bernama EnvironmentsSample.

Perintah .NET CLI berikut membuat dan menjalankan aplikasi web bernama EnvironmentsSample:

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

Saat aplikasi berjalan, aplikasi menampilkan output yang mirip dengan yang berikut ini:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Mengatur lingkungan pada baris perintah

--environment Gunakan bendera untuk mengatur lingkungan. Contohnya:

dotnet run --environment Production

Perintah sebelumnya mengatur lingkungan ke Production dan menampilkan output yang mirip dengan yang berikut ini di jendela perintah:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Pengembangan dan launchSettings.json

Lingkungan pengembangan dapat mengaktifkan fitur yang seharusnya tidak diekspos dalam produksi. Misalnya, templat proyek ASP.NET Core mengaktifkan Halaman Pengecualian Pengembang di lingkungan pengembangan. Karena biaya performa, validasi cakupan dan validasi dependensi hanya terjadi dalam pengembangan.

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

File launchSettings.json:

• Hanya digunakan pada komputer pengembangan lokal.
• Tidak disebarkan.
• Berisi pengaturan profil.

JSON berikut menunjukkan launchSettings.json file untuk proyek web ASP.NET Core bernama EnvironmentsSample yang dibuat dengan Visual Studio atau dotnet new:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

JSON sebelumnya berisi dua profil:

• EnvironmentsSample: Nama profil adalah nama proyek. Sebagai profil pertama yang tercantum, profil ini digunakan secara default. Kunci "commandName" memiliki nilai "Project", oleh karena itu, Kestrel server web diluncurkan.

• IIS Express: Kunci "commandName" memiliki nilai "IISExpress", oleh karena itu, IISExpress adalah server web.

Anda dapat mengatur profil peluncuran ke proyek atau profil lain yang disertakan dalam launchSettings.json. Misalnya, pada gambar di bawah ini, memilih nama proyek meluncurkan Kestrel server web.

Nilai commandName dapat menentukan server web yang akan diluncurkan. commandName dapat berupa salah satu hal berikut:

• IISExpress : Meluncurkan IIS Express.
• IIS : Tidak ada server web yang diluncurkan. IIS diharapkan tersedia.
• Project : Meluncurkan Kestrel.

Tab Debug / Umum properti proyek Visual Studio 2022 menyediakan tautan antarmuka pengguna Buka profil peluncuran debug. Tautan ini membuka dialog Luncurkan Profil yang memungkinkan Anda mengedit pengaturan variabel lingkungan dalam launchSettings.json file. Anda juga dapat membuka dialog Luncurkan Profil dari menu Debug dengan memilih <nama> proyek Properti Debug. 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.

File berikut launchSettings.json berisi beberapa profil:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Profil dapat dipilih:

• Dari UI Visual Studio.

• dotnet run Menggunakan perintah CLI dengan opsi yang --launch-profile diatur ke nama profil. Pendekatan ini hanya mendukung Kestrel profil.

  dotnet run --launch-profile "EnvironmentsSample"
  

Peringatan

launchSettings.json tidak boleh menyimpan rahasia. Alat Secret Manager dapat digunakan untuk menyimpan rahasia untuk pengembangan lokal.

Saat menggunakan Visual Studio Code, variabel lingkungan dapat diatur dalam .vscode/launch.json file. Contoh berikut menetapkan beberapa variabel lingkungan untuk nilai konfigurasi Host:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            // Configuration ommitted for brevity.
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "https://localhost:5001",
                "ASPNETCORE_DETAILEDERRORS": "1",
                "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
            },
            // Configuration ommitted for brevity.

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

Produksi

Lingkungan produksi harus dikonfigurasi untuk memaksimalkan keamanan, performa, dan ketahanan aplikasi. Beberapa pengaturan umum yang berbeda dari pengembangan meliputi:

• Penembolokan.
• Sumber daya sisi klien dibundel, dikurangi, dan berpotensi dilayani dari CDN.
• Halaman kesalahan diagnostik dinonaktifkan.
• Halaman kesalahan yang mudah diingat diaktifkan.
• Pengelogan dan pemantauan produksi diaktifkan. Misalnya, menggunakan Application Insights.

Mengatur lingkungan dengan mengatur variabel lingkungan

Seringkali berguna untuk mengatur lingkungan tertentu untuk pengujian dengan variabel lingkungan atau pengaturan platform. Jika lingkungan tidak diatur, lingkungan akan default ke Production, yang menonaktifkan sebagian besar fitur penelusuran kesalahan. Metode untuk mengatur lingkungan tergantung pada sistem operasi.

Saat host dibuat, pengaturan lingkungan terakhir yang dibaca oleh aplikasi menentukan lingkungan aplikasi. Lingkungan aplikasi tidak dapat diubah saat aplikasi sedang berjalan.

Halaman Tentang dari kode sampel menampilkan nilai IWebHostEnvironment.EnvironmentName.

Azure App Service

Production adalah nilai default jika DOTNET_ENVIRONMENT dan ASPNETCORE_ENVIRONMENT belum ditetapkan. Aplikasi yang disebarkan ke Azure secara Production default.

Untuk mengatur lingkungan di aplikasi Azure App Service dengan menggunakan portal:

1. Pilih aplikasi dari halaman App Services .
2. Di grup Pengaturan, pilih Variabel lingkungan.
3. Di tab Pengaturan aplikasi, pilih + Tambahkan.
4. Di jendela Pengaturan aplikasi Tambahkan/Edit, sediakan ASPNETCORE_ENVIRONMENT Nama. Untuk Nilai, berikan lingkungan (misalnya, Staging).
5. Pilih kotak centang Pengaturan slot penyebaran jika Anda ingin pengaturan lingkungan tetap dengan slot saat ini saat slot penyebaran ditukar. Untuk informasi selengkapnya, lihat Menyiapkan lingkungan penahapan di Azure App Service dalam dokumentasi Azure.
6. Pilih OK untuk menutup dialog Tambahkan/Edit pengaturan aplikasi.
7. Pilih Simpan di bagian atas halaman Konfigurasi .

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

Windows - Mengatur variabel lingkungan untuk proses

Nilai lingkungan dalam launchSettings.json mengambil alih nilai yang ditetapkan di lingkungan sistem.

Untuk mengatur ASPNETCORE_ENVIRONMENT sesi saat ini saat aplikasi mulai menggunakan dotnet run, gunakan perintah berikut pada prompt perintah atau di PowerShell:

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

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

Windows - Mengatur variabel lingkungan secara global

Perintah sebelumnya diatur ASPNETCORE_ENVIRONMENT hanya untuk proses yang diluncurkan dari jendela perintah tersebut.

Untuk mengatur nilai secara global di Windows, gunakan salah satu pendekatan berikut:

• Buka pengaturan sistem Tingkat Lanjut Panel Kontrol> System>dan tambahkan atau edit nilainyaASPNETCORE_ENVIRONMENT:

  

  

• Buka perintah administratif dan gunakan setx perintah atau buka prompt perintah PowerShell administratif dan gunakan [Environment]::SetEnvironmentVariable:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    Sakelar /M mengatur variabel lingkungan di tingkat sistem. Jika sakelar /M tidak digunakan, variabel lingkungan diatur untuk akun pengguna.

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    Opsi Machine mengatur variabel lingkungan di tingkat sistem. Jika nilai opsi diubah menjadi User, variabel lingkungan diatur untuk akun pengguna.

ASPNETCORE_ENVIRONMENT Ketika variabel lingkungan diatur secara global, itu berlaku untuk dotnet run di jendela perintah apa pun yang dibuka setelah nilai diatur. Nilai lingkungan dalam launchSettings.json mengambil alih nilai yang ditetapkan di lingkungan sistem.

Windows - Menggunakan web.config

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

Windows - Penyebaran IIS

Sertakan <EnvironmentName> properti dalam profil penerbitan (.pubxml) atau file proyek. Pendekatan ini mengatur lingkungan di web.config saat proyek diterbitkan:

<PropertyGroup>
  <EnvironmentName>Development</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 bagian perintah AppCmd.exe lingkungan Variabel <LingkunganVariables>. ASPNETCORE_ENVIRONMENT Saat 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 untuk mendapatkan nilai baru yang diambil oleh aplikasi:

• Jalankan net stop was /y diikuti oleh net start w3svc dari prompt perintah.
• Mulai ulang server.

macOS

Mengatur lingkungan saat ini untuk macOS dapat dilakukan secara sejalan saat menjalankan aplikasi:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Atau, atur lingkungan sebelum export menjalankan aplikasi:

export ASPNETCORE_ENVIRONMENT=Staging

Variabel lingkungan tingkat mesin diatur dalam file .bashrc atau .bash_profile . Edit file menggunakan editor teks apa pun. Tambahkan pernyataan berikut:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Untuk distribusi Linux, gunakan export perintah pada perintah untuk pengaturan variabel berbasis sesi dan file bash_profile untuk pengaturan lingkungan tingkat komputer.

Mengatur lingkungan dalam kode

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
}); 

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Konfigurasi menurut lingkungan

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

Mengonfigurasi layanan dan middleware berdasarkan lingkungan

Gunakan WebApplicationBuilder.Environment atau WebApplication.Environment untuk menambahkan layanan atau middleware secara kondisional tergantung pada lingkungan saat ini. Templat proyek menyertakan contoh kode yang menambahkan middleware hanya ketika lingkungan saat ini bukan Pengembangan:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Kode yang disorot memeriksa lingkungan saat ini saat membangun alur permintaan. Untuk memeriksa lingkungan saat ini saat mengonfigurasi layanan, gunakan builder.Environment alih-alih app.Environment.

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