ASP.NET Core'da birden çok ortam kullanma

Yayımlayanlar Rick Anderson ve Kirk Larkin

ASP.NET Core, bir ortam değişkeni kullanarak çalışma zamanı ortamına göre uygulama davranışını yapılandırmaktadır.

Bu Blazor makaledeki yönergeleri ekleyen veya yerine geçen ortamlar kılavuzu için bkz . ASP.NET Çekirdek Blazor ortamlar.

Ortamlar

Çalışma zamanı ortamını belirlemek için ASP.NET Core aşağıdaki ortam değişkenlerinden okur:

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENTWebApplication.CreateBuilder yöntemi çağrıldığında. Varsayılan ASP.NET Core web uygulaması şablonları öğesini çağırır WebApplication.CreateBuilder. DOTNET_ENVIRONMENT Kullanıldığında değer geçersiz kılar ASPNETCORE_ENVIRONMENT WebApplicationBuilder. ve WebHost.CreateDefaultBuilderASPNETCORE_ENVIRONMENT gibi ConfigureWebHostDefaults diğer konaklar için daha yüksek önceliğe sahiptir.

IHostEnvironment.EnvironmentName herhangi bir değere ayarlanabilir, ancak aşağıdaki değerler çerçeve tarafından sağlanır:

• Development: launchSettings.json dosyası yerel makinede olarak Development ayarlırASPNETCORE_ENVIRONMENT.
• Staging
• Production: Ve ayarlanmamışsa DOTNET_ENVIRONMENT ASPNETCORE_ENVIRONMENT varsayılan değerdir.

Aşağıdaki kod:

• ASP.NET Core şablonları tarafından oluşturulan koda benzer.
• olarak ayarlandığında DevelopmentGeliştirici Özel Durum Sayfası'nı ASPNETCORE_ENVIRONMENT etkinleştirir. Bu, yöntemi tarafından WebApplication.CreateBuilder otomatik olarak gerçekleştirilir.
• değeri ASPNETCORE_ENVIRONMENT dışında Developmentbir değer olduğunda çağırırUseExceptionHandler.
• özelliğinde Environment WebApplicationbir IWebHostEnvironment örnek sağlar.

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

Ortam Etiketi Yardımcısı, öğeye işaretleme eklemek veya hariç tutmak için IHostEnvironment.EnvironmentName değerini kullanır:

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

Örnek koddaki Hakkında sayfası önceki işaretlemeyi içerir ve değerini IWebHostEnvironment.EnvironmentNamegörüntüler.

Windows ve macOS'ta ortam değişkenleri ve değerleri büyük/küçük harfe duyarlı değildir. Linux ortam değişkenleri ve değerleri varsayılan olarak büyük/küçük harfe duyarlıdır.

Ortam OluşturmaÖrnek Oluşturma

Bu makalede kullanılan örnek kod, EnvironmentsSample adlı bir Razor Pages projesini temel alır.

Aşağıdaki .NET CLI komutları EnvironmentsSample adlı bir web uygulaması oluşturur ve çalıştırır:

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

Uygulama çalıştırıldığında aşağıdakine benzer bir çıkış görüntüler:

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

Komut satırında ortam ayarlama

--environment Ortamı ayarlamak için bayrağını kullanın. Örneğin:

dotnet run --environment Production

Yukarıdaki komut, ortamı olarak Production ayarlar ve çıktıyı komut penceresinde aşağıdakine benzer şekilde görüntüler:

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

Geliştirme ve launchSettings.json

Geliştirme ortamı, üretim ortamında kullanıma sunulmaması gereken özellikleri etkinleştirebilir. Örneğin, ASP.NET Core proje şablonları geliştirme ortamında Geliştirici Özel Durum Sayfası'nı etkinleştirir. Performans maliyeti nedeniyle kapsam doğrulaması ve bağımlılık doğrulaması yalnızca geliştirme aşamasında gerçekleşir.

Yerel makine geliştirme ortamı projenin Properties\launchSettings.json dosyasında ayarlanabilir. Sistem ortamında ayarlanan launchSettings.json geçersiz kılma değerlerinde ayarlanan ortam değerleri.

launchSettings.json dosyası:

• Yalnızca yerel geliştirme makinesinde kullanılır.
• Dağıtılmaz.
• Profil ayarlarını içerir.

Aşağıdaki JSON, Visual Studio veya dotnet newile oluşturulan EnvironmentsSample adlı ASP.NET Core web projesinin dosyasını gösterirlaunchSettings.json:

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

Yukarıdaki JSON iki profil içerir:

• EnvironmentsSample: Profil adı proje adıdır. Listelenen ilk profil olarak, bu profil varsayılan olarak kullanılır. "commandName" Anahtarın değeri "Project"vardır,Kestrel bu nedenle web sunucusu başlatılır.

• IIS Express"commandName": Anahtarın değeri "IISExpress"vardır, bu nedenle IISExpress web sunucusudur.

Başlatma profilini projeye veya içinde bulunan diğer profillere launchSettings.jsonayarlayabilirsiniz. Örneğin, aşağıdaki resimde proje adı seçildiğinde web sunucusu başlatılırKestrel.

değeri commandName , başlatılacak web sunucusunu belirtebilir. commandName aşağıdakilerden herhangi biri olabilir:

• IISExpress : IIS Express'i başlatır.
• IIS : Hiçbir web sunucusu başlatılmadı. IIS'nin kullanılabilir olması beklenir.
• Project : başlatılır Kestrel.

Visual Studio 2022 proje özellikleri Hata Ayıkla / Genel sekmesi hata ayıklama başlatma profillerini aç kullanıcı arabirimi bağlantısı sağlar. Bu bağlantı, dosyadaki launchSettings.json ortam değişkeni ayarlarını düzenlemenizi sağlayan Bir Başlatma Profilleri iletişim kutusu açar. Proje adı> Hata Ayıklama Özellikleri'ni seçerek <Hata Ayıklama menüsünden Profilleri Başlat iletişim kutusunu da açabilirsiniz. Web sunucusu yeniden başlatılana kadar proje profillerinde yapılan değişiklikler geçerli olmayabilir. Kestrel ortamında yapılan değişiklikleri algılamadan önce yeniden başlatılmalıdır.

Aşağıdaki launchSettings.json dosya birden çok profil içerir:

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

Profiller seçilebilir:

• Visual Studio kullanıcı arabiriminden.

• dotnet run CLI komutunu, seçeneği profilin --launch-profile adına ayarlanmış şekilde kullanma. Bu yaklaşım yalnızca profilleri destekler Kestrel .

  dotnet run --launch-profile "EnvironmentsSample"
  

Uyarı

launchSettings.json gizli dizileri depolamamalıdır. Gizli Dizi Yöneticisi aracı , yerel geliştirme için gizli dizileri depolamak için kullanılabilir.

Visual Studio Code kullanılırken, dosyada .vscode/launch.json ortam değişkenleri ayarlanabilir. Aşağıdaki örnek, Konak yapılandırma değerleri için çeşitli ortam değişkenlerini ayarlar:

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

Dosya .vscode/launch.json yalnızca Visual Studio Code tarafından kullanılır.

Üretim

Üretim ortamı güvenliği, performansı ve uygulama sağlamlığını en üst düzeye çıkarmak için yapılandırılmalıdır. Geliştirmeden farklı bazı yaygın ayarlar şunlardır:

• Önbelleğe alma.
• İstemci tarafı kaynakları bir CDN'den paketlenir, küçültülür ve potansiyel olarak sunulur.
• Tanılama hata sayfaları devre dışı bırakıldı.
• Kolay hata sayfaları etkinleştirildi.
• Üretim günlüğü ve izleme etkinleştirildi. Örneğin, Application Insights'ı kullanma.

Ortam değişkeni ayarlayarak ortamı ayarlama

Bir ortam değişkeni veya platform ayarıyla test için belirli bir ortam ayarlamak genellikle yararlıdır. Ortam ayarlanmadıysa, varsayılan olarak Productionolarak ayarlanır ve bu da hata ayıklama özelliklerinin çoğunu devre dışı bırakır. Ortamı ayarlama yöntemi işletim sistemine bağlıdır.

Konak oluşturulduğunda, uygulama tarafından okunan son ortam ayarı uygulamanın ortamını belirler. Uygulama çalışırken uygulamanın ortamı değiştirilemez.

Örnek koddaki Hakkında sayfası değerini IWebHostEnvironment.EnvironmentNamegörüntüler.

Azure App Service

Production, ayarlanmamışsa ve ASPNETCORE_ENVIRONMENT ayarlanmamışsa DOTNET_ENVIRONMENT varsayılan değerdir. Azure'a dağıtılan uygulamalar varsayılan olarak vardır Production .

Portalı kullanarak bir Azure Uygulaması Hizmeti uygulamasında ortamı ayarlamak için:

1. Uygulama Hizmetleri sayfasından uygulamayı seçin.
2. Ayarlar grubunda Ortam değişkenleri'ni seçin.
3. Uygulama ayarları sekmesinde + Ekle'yi seçin.
4. Uygulama ayarı ekle/düzenle penceresinde Ad'ı belirtinASPNETCORE_ENVIRONMENT. Değer için ortamı sağlayın (örneğin, Staging).
5. Dağıtım yuvaları değiştirildiğinde ortam ayarının geçerli yuvada kalmasını istiyorsanız Dağıtım yuvası ayarı onay kutusunu seçin. Daha fazla bilgi için Azure belgelerindeki Azure Uygulaması Hizmetinde hazırlama ortamlarını ayarlama bölümüne bakın.
6. Uygulama ayarı ekle/düzenle iletişim kutusunu kapatmak için Tamam'ı seçin.
7. Yapılandırma sayfasının üst kısmındaki Kaydet'i seçin.

Azure Uygulaması Hizmeti, Azure portalında bir uygulama ayarı eklendikten, değiştirildikten veya silindikten sonra uygulamayı otomatik olarak yeniden başlatır.

Windows - İşlem için ortam değişkeni ayarlama

launchSettings.json Sistem ortamında ayarlanan geçersiz kılma değerlerindeki ortam değerleri.

Uygulama dotnet run kullanılarak başlatıldığında geçerli oturum için öğesini ayarlamak ASPNETCORE_ENVIRONMENT için bir komut isteminde veya PowerShell'de aşağıdaki komutları kullanın:

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

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

Windows - Ortam değişkenini genel olarak ayarlama

Önceki komutlar yalnızca bu komut penceresinden başlatılan işlemler için ayarlanır ASPNETCORE_ENVIRONMENT .

Değeri Windows'ta genel olarak ayarlamak için aşağıdaki yaklaşımlardan birini kullanın:

• Denetim Masası> System>Gelişmiş sistem ayarlarını açın ve değeri ekleyin veya düzenleyin:ASPNETCORE_ENVIRONMENT

  

  

• Bir yönetim komut istemi açın ve komutunu kullanın setx veya bir yönetim PowerShell komut istemi açın ve kullanın [Environment]::SetEnvironmentVariable:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    anahtar, /M ortam değişkenini sistem düzeyinde ayarlar. /M Anahtar kullanılmıyorsa, ortam değişkeni kullanıcı hesabı için ayarlanır.

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

    Machine seçeneği ortam değişkenini sistem düzeyinde ayarlar. Seçenek değeri olarak değiştirilirse User, ortam değişkeni kullanıcı hesabı için ayarlanır.

ASPNETCORE_ENVIRONMENT Ortam değişkeni genel olarak ayarlandığında, değer ayarlandıktan sonra açılan herhangi bir komut penceresinde için geçerli dotnet run olur. launchSettings.json Sistem ortamında ayarlanan geçersiz kılma değerlerindeki ortam değerleri.

Windows - web.config kullanma

ile ortam değişkenini ASPNETCORE_ENVIRONMENT ayarlamak için web.config dosyasının Ortam değişkenlerini ayarlama bölümüne bakın.web.config

Windows - IIS dağıtımları

<EnvironmentName> Özelliğini yayımlama profiline (.pubxml) veya proje dosyasına ekleyin. Bu yaklaşım, proje yayımlandığında web.config içindeki ortamı ayarlar:

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

Yalıtılmış bir Uygulama Havuzunda çalışan bir uygulamanın ortam değişkenini ayarlamak ASPNETCORE_ENVIRONMENT için (IIS 10.0 veya üzeri sürümlerde desteklenir), Ortam Değişkenleri <ortamının AppCmd.exe komut bölümüne bakınVariables>. ASPNETCORE_ENVIRONMENT Ortam değişkeni bir uygulama havuzu için ayarlandığında, değeri sistem düzeyinde bir ayarı geçersiz kılar.

Bir uygulamayı IIS'de barındırırken ve ortam değişkenini ASPNETCORE_ENVIRONMENT eklerken veya değiştirirken, uygulamalar tarafından yeni değerin alınması için aşağıdaki yaklaşımlardan birini kullanın:

• Komut net stop was /y isteminden yürütür net start w3svc .
• Sunucuyu yeniden başlatın.

macOS

MacOS için geçerli ortamın ayarlanması, uygulama çalıştırılırken satır içi olarak gerçekleştirilebilir:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Alternatif olarak, uygulamayı çalıştırmadan önce ortamını ile export ayarlayın:

export ASPNETCORE_ENVIRONMENT=Staging

Makine düzeyinde ortam değişkenleri .bashrc veya .bash_profile dosyasında ayarlanır. Herhangi bir metin düzenleyicisini kullanarak dosyayı düzenleyin. Aşağıdaki deyimi ekleyin:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Linux dağıtımları için, oturum tabanlı değişken ayarları için komut istemindeki komutu ve makine düzeyinde ortam ayarları için bash_profile dosyasını kullanınexport.

Ortamı kodda ayarlama

Kodda ortamı ayarlamak için, aşağıdaki örnekte gösterildiği gibi öğesini oluştururken WebApplicationBuilderkullanınWebApplicationOptions.EnvironmentName:

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

Ortama göre yapılandırma

Ortama göre yapılandırma yüklemek için bkz . ASP.NET Core'da yapılandırma.

Hizmetleri ve ara yazılımı ortama göre yapılandırma

Geçerli ortama bağlı olarak koşullu olarak hizmet veya ara yazılım eklemek için veya WebApplication.Environment kullanınWebApplicationBuilder.Environment. Proje şablonu, yalnızca geçerli ortam Geliştirme olmadığında ara yazılım ekleyen bir kod örneği içerir:

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

Vurgulanan kod, istek işlem hattını oluştururken geçerli ortamı denetler. Hizmetleri yapılandırırken geçerli ortamı denetlemek için yerine app.Environmentkullanınbuilder.Environment.

Ek kaynaklar

• Örnek kodu görüntüleme veya indirme (indirme)
• ASP.NET Core'da uygulama başlatma
• ASP.NET Core'da yapılandırma
• ASP.NET Core Blazor ortamları