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.

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 ASPNETCORE_ENVIRONMENT mengambil DOTNET_ENVIRONMENTalih .

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 dalam Environment properti dari 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>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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 tidak boleh diekspos dalam produksi. Misalnya, templat proyek ASP.NET Core memungkinkan Halaman Pengecualian Pengembang di lingkungan pengembangan.

Lingkungan untuk pengembangan komputer lokal dapat diatur dalam file Properties\launchSettings.json proyek. Nilai lingkungan yang ditetapkan 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.

ON berikut menunjukkan JSlaunchSettings.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"
      }
    }
  }
}

ON sebelumnya JSberisi 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 dari berikut ini:

• 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 Profil peluncuran debug terbuka . 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 "SampleApp"
  

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 Konfigurasi.
3. Di tab Pengaturan aplikasi , pilih Pengaturan aplikasi baru.
4. Di jendela Tambahkan/Edit pengaturan aplikasi , berikan ASPNETCORE_ENVIRONMENTNama. 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 untuk 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:

• Bukapengaturan sistemtingkat lanjut Panel Kontrol>System> dan tambahkan atau edit nilainyaASPNETCORE_ENVIRONMENT:

  

  

• Buka prompt 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 pada 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 - Gunakan web.config

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

Windows - Penyebaran IIS

Sertakan <EnvironmentName> properti dalam profil penerbitan (.pubxml) atau file proyek. Pendekatan ini menetapkan lingkungan dalam 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 perintahAppCmd.exelingkungan Variabel <LingkunganVariables>. ASPNETCORE_ENVIRONMENT Saat variabel lingkungan diatur untuk kumpulan aplikasi, nilainya akan 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 dengan net start w3svc dari prompt perintah.
• Mulai ulang server.

macOS

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

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Atau, atur lingkungan sebelum export menjalankan aplikasi:

export ASPNETCORE_ENVIRONMENT=Staging

Variabel lingkungan tingkat komputer 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();

Untuk informasi selengkapnya, lihat Host Generik .NET di ASP.NET Core.

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 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)
• Pengaktifan aplikasi di ASP.NET Core
• Konfigurasi di ASP.NET Core
• lingkungan ASP.NET Core Blazor

Oleh Rick Anderson dan Kirk Larkin

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

Lingkungan

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

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT ketika ConfigureWebHostDefaults dipanggil. Templat aplikasi web ASP.NET Core default memanggil ConfigureWebHostDefaults. Nilai ASPNETCORE_ENVIRONMENT mengambil DOTNET_ENVIRONMENTalih .

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:

• UseDeveloperExceptionPage Panggilan saat ASPNETCORE_ENVIRONMENT diatur ke Development.
• UseExceptionHandler Memanggil saat nilai ASPNETCORE_ENVIRONMENT diatur ke Staging, , Productionatau Staging_2.
• Menyuntikkan IWebHostEnvironment ke dalam Startup.Configure. Pendekatan ini berguna ketika aplikasi hanya memerlukan penyesuaian Startup.Configure untuk beberapa lingkungan dengan perbedaan kode minimal per lingkungan.
• Mirip dengan kode yang dihasilkan oleh templat ASP.NET Core.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))
    {
        app.UseExceptionHandler("/Error");
    }

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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

<environment include="Development">
    <div>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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 dokumen ini didasarkan pada Razor proyek Pages bernama EnvironmentsSample.

Kode berikut membuat dan menjalankan aplikasi web bernama EnvironmentsSample:

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

Saat aplikasi berjalan, aplikasi akan menampilkan beberapa output berikut:

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\EnvironmentsSample

Pengembangan dan launchSettings.json

Lingkungan pengembangan dapat mengaktifkan fitur yang tidak boleh diekspos dalam produksi. Misalnya, templat ASP.NET Core mengaktifkan Halaman Pengecualian Pengembang di lingkungan pengembangan.

Lingkungan untuk pengembangan komputer lokal dapat diatur dalam file Properties\launchSettings.json proyek. Nilai lingkungan yang ditetapkan 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.

ON berikut menunjukkan JSlaunchSettings.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:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Markup sebelumnya berisi dua profil:

• IIS Express: Profil default yang digunakan saat meluncurkan aplikasi dari Visual Studio. Kunci "commandName" memiliki nilai "IISExpress", oleh karena itu, IISExpress adalah server web. Anda dapat mengatur profil peluncuran ke proyek atau profil lain yang disertakan. Misalnya, pada gambar di bawah ini, memilih nama proyek meluncurkan Kestrel server web.

  

• EnvironmentsSample: Nama profil adalah nama proyek. Profil ini digunakan secara default saat meluncurkan aplikasi dengan dotnet run. Kunci "commandName" memiliki nilai "Project", oleh karena itu, Kestrel server web diluncurkan.

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

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

Tab Debug properti proyek Visual Studio menyediakan GUI untuk mengedit 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.

File berikut berisi launchSettings.json beberapa profil:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

Profil dapat dipilih:

• Dari UI Visual Studio.

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

  dotnet run --launch-profile "SampleApp"
  

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

Seringkali berguna untuk mengatur lingkungan tertentu untuk pengujian dengan variabel lingkungan atau pengaturan platform. Jika lingkungan tidak diatur, lingkungan 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 Azure App Service, lakukan langkah-langkah berikut:

1. Pilih aplikasi dari bilah App Services .
2. Di grup Pengaturan , pilih bilah Konfigurasi .
3. Di tab Pengaturan aplikasi , pilih Pengaturan aplikasi baru.
4. Di jendela pengaturan tambahkan/Edit aplikasi , berikan ASPNETCORE_ENVIRONMENTNama. 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 jendela pengaturan Tambahkan/Edit aplikasi .
7. Pilih Simpan di bagian atas bilah Konfigurasi .

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

Windows

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

Untuk mengatur ASPNETCORE_ENVIRONMENT untuk sesi saat ini saat aplikasi mulai menggunakan dotnet run, perintah berikut digunakan:

Perintah

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

PowerShell

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

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

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

• Bukapengaturan sistemtingkat lanjut Panel Kontrol>System> dan tambahkan atau edit nilainyaASPNETCORE_ENVIRONMENT:

  

  

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

  Perintah

  setx ASPNETCORE_ENVIRONMENT Staging /M
  

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

  PowerShell

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

  Nilai Machine opsi menunjukkan untuk 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.

web.config

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

File proyek atau profil penerbitan

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

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Kumpulan Aplikasi Per IIS

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 perintahAppCmd.exe dari topik Environment Variables <environmentVariables> . ASPNETCORE_ENVIRONMENT Saat variabel lingkungan diatur untuk kumpulan aplikasi, nilainya akan menggantikan pengaturan di tingkat sistem.

Saat menghosting aplikasi di IIS dan menambahkan atau mengubah ASPNETCORE_ENVIRONMENT variabel lingkungan, gunakan salah satu pendekatan berikut untuk memiliki 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 komputer 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

Panggil UseEnvironment saat membangun host. Lihat Host Generik .NET di ASP.NET Core.

Konfigurasi menurut lingkungan

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

Kelas dan metode Startup berbasis lingkungan

Menyuntikkan IWebHostEnvironment ke kelas Startup

IWebHostEnvironment Masukkan ke Startup konstruktor. Pendekatan ini berguna ketika aplikasi memerlukan konfigurasi Startup hanya untuk beberapa lingkungan dengan perbedaan kode minimal per lingkungan.

Lihat contoh berikut:

• Lingkungan diadakan di lapangan _env .
• _env digunakan di ConfigureServices dan Configure untuk menerapkan konfigurasi startup berdasarkan lingkungan aplikasi.

public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Konvensi kelas startup

Saat aplikasi ASP.NET Core dimulai, kelas Startup mem-bootstrap aplikasi. Aplikasi ini dapat menentukan beberapa Startup kelas untuk lingkungan yang berbeda. Kelas yang sesuai Startup dipilih saat runtime. Kelas yang akhiran namanya cocok dengan lingkungan saat ini diprioritaskan. Jika kelas yang Startup{EnvironmentName} cocok tidak ditemukan, Startup kelas akan digunakan. Pendekatan ini berguna ketika aplikasi memerlukan konfigurasi startup untuk beberapa lingkungan dengan banyak perbedaan kode per lingkungan. Aplikasi umum tidak akan memerlukan pendekatan ini.

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

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

UseStartup(IWebHostBuilder, String) Gunakan kelebihan beban yang menerima nama rakitan:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

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

Konvensi metode startup

Mengonfigurasi dan Mengonfigurasi Layanan mendukung versi formulir Configure<EnvironmentName> khusus lingkungan dan Configure<EnvironmentName>Services. Jika pencocokan Configure<EnvironmentName>Services atau Configure<EnvironmentName> metode tidak ditemukan, ConfigureServices metode atau Configure masing-masing digunakan. Pendekatan ini berguna ketika aplikasi memerlukan konfigurasi startup untuk beberapa lingkungan dengan banyak perbedaan kode per lingkungan:

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}

Sumber Daya Tambahan:

• Menampilkan atau mengunduh kode sampel (cara mengunduh)
• Pengaktifan aplikasi di ASP.NET Core
• Konfigurasi di ASP.NET Core
• lingkungan ASP.NET Core Blazor