Bagikan melalui


Gunakan beberapa lingkungan di ASP.NET Core

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

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 ASPNETCORE_ENVIRONMENT mengesampingkan DOTNET_ENVIRONMENT.

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:

Kode berikut:

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.

Peluncuran IIS Express pada menu

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.

Variabel Lingkungan Pengaturan Properti Proyek

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:

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:

    Properti Tingkat Lanjut Sistem

    Variabel Lingkungan Inti ASPNET

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

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 mengesampingkan DOTNET_ENVIRONMENT.

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

Kode berikut:

  • UseDeveloperExceptionPage Memanggil 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 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 seharusnya tidak diekspos dalam produksi. Misalnya, templat 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 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: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.

    Peluncuran IIS Express pada menu

  • 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 hal berikut:

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

Variabel Lingkungan Pengaturan Properti Proyek

File berikut launchSettings.json berisi 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 diatur --launch-profile 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:

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

Prompt perintah

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

PowerShell

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

Perintah sebelumnya hanya ditetapkan ASPNETCORE_ENVIRONMENT 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:

    Properti Tingkat Lanjut Sistem

    Variabel Lingkungan Inti ASPNET

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

    Prompt perintah

    setx ASPNETCORE_ENVIRONMENT Staging /M
    

    Sakelar /M menunjukkan untuk mengatur variabel lingkungan di 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 file web.config.

Proyek file atau menerbitkan profil

Untuk penyebaran Windows 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>

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 perintah AppCmd.exe dari topik Environment Variables <environmentVariables> . 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

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

Konfigurasi menurut lingkungan

Untuk memuat konfigurasi menurut 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.

Dalam 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 pada 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: