ASP.NET Core çalışma zamanı ortamları

ASP.NET Core, genellikle uygulamanın çalıştığı yeri yansıtan çalışma zamanı ortamına göre uygulama davranışını yapılandırmaktadır.

Uygulamalar genellikle bir geliştiricinin makinesinde yerel geliştirme ve test sırasında bir dizi yapılandırılmış davranışla Geliştirme ortamında çalışır. Buna karşılık, farklı yapılandırılmış davranış kümesine sahip bir sunucuya dağıtıldığında Üretim ortamında çalışırlar. Canlı dağıtımdan önce bir uygulamayı hazırlama çerçevesi tarafından sağlanan Hazırlama ortamı veya geliştiricilerin oluşturduğu diğer ortamlar gibi herhangi bir sayıda ek ortam kullanılabilir.

Bu makalede uygulama çalışma zamanı ortamları, uygulama davranışını denetlemek için ortamın nasıl kullanılacağı ve ortamın nasıl ayarlanacağı açıklanır.

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

Environments

Ortam herhangi bir dize değeri olsa da, aşağıdaki ortam değerleri çerçeve tarafından sağlanır:

• Development
• Staging
• Production

Üretim ortamı güvenliği, performansı ve uygulama güvenilirliğini en üst düzeye çıkarmak için yapılandırılmıştır. Geliştirme ortamından farklı olan yaygın geliştirici ayarları ve yapılandırmaları şunlardır:

• Önbelleğe almayı etkinleştirme.
• İstemci tarafı kaynaklarını paketleme ve küçültmenin yanı sıra bunları bir CDN'den sunma olasılığı da vardır.
• Tanılama hata sayfalarını devre dışı bırakma ve kullanıcı dostu hata sayfalarını etkinleştirme.
• Üretim günlüğünü kaydetme ve izlemeyi etkinleştirme. Örneğin, Azure Application Insights için günlüğe kaydetme etkinleştirilir.

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

Ağaç kesimi

Başlangıçta çalışan bir uygulamanın komut kabuğundaki çıkış, uygulamanın ortamını gösterir. Aşağıdaki örnekte, uygulama Hazırlama ortamında çalışıyor:

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

Çalışma zamanı ortamını belirleyen ortam değişkenleri

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

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

WebApplication kullanıldığında, DOTNET_ENVIRONMENT değeri ASPNETCORE_ENVIRONMENT değerinden önceliklidir. kullanırken WebHostASPNETCORE_ENVIRONMENT öncelik kazanır.

DOTNET_ENVIRONMENT ve ASPNETCORE_ENVIRONMENT ortam değişkenleri ayarlanmamışsa, Üretim ortamı varsayılan ortamdır.

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

Ortama göre kod yürütmeyi denetleme

Geçerli ortama bağlı olarak koşullu olarak hizmet veya ara yazılım eklemek için veya WebApplicationBuilder.Environment kullanınWebApplication.Environment.

Uygulamanın Program dosyasında aşağıdaki kod:

• Ortamı ayırt etmek için kullanır WebApplication.Environment .
• Çağrılar UseExceptionHandler, özel durumları işlemek için istek işleme işlem hattına Özel Durum İşleyicisi Ara Yazılımı ekler.
• Çağrılar , üst bilgisini uygulamak için HSTS Ara Yazılımı ekler.

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

Yukarıdaki örnek, istek işleme işlem hattı için geçerli ortamı denetler. Hizmetleri yapılandırırken geçerli ortamı denetlemek için yerine builder.Environmentkullanınapp.Environment.

uygulama içinde, IHostEnvironment uygulamanın barındırma ortamı hakkında genel bilgiler sağlar ve IHostEnvironment.EnvironmentName özelliği uygulamanın geçerli ortamını gösterir.

İşlenen içeriği denetleme

IHostEnvironment Sunucu tarafından işlenen bir bileşene ekleyin ve içeriğin işlendiği Razor ortamı belirlemek için hizmetin uzantı yöntemlerini ve EnvironmentName özelliğini kullanın:

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Ortamın Blazor Web Appistemci tarafı işlemeyi denetlemesini gerektiren s için bkz. Prerender ASP.NET Core Razor bileşenleri.

Uygulama çalıştırıldığında komut kabuğunda ortamı ayarlama (dotnet run)

-e|--environment Ortamı ayarlamak için seçeneğini kullanın:

dotnet run -e Staging

Başlatma ayarları dosyasılaunchSettings.json () ile ortamı ayarlama

Yerel geliştirme ortamı projenin dosyasında ayarlanabilir Properties\launchSettings.json . Sistem ortamı tarafından ayarlanan değerleri launchSettings.json ile ayarlanan ortam değerleri üzerine yazar.

launchSettings.json dosyası:

• Yalnızca yerel geliştirme makinesinde kullanılır.
• Uygulama yayımlandığında dağıtılmaz.
• Her biri farklı bir ortam yapılandıran birden çok profil içerebilir.

Aşağıdaki örnek, ortam değişkenini kullanarak https başlatma profili için ASPNETCORE_ENVIRONMENT Hazırlama ortamını ayarlar:

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

Visual Studio'da başlatma profilleri aracılığıyla ortamı ayarlamak için iki yaklaşım vardır:

• Çözüm Gezgini'nde projeye sağ tıkladıktan sonra +Enter tuşuna basın veya Özellikler'i seçin. Hata Ayıklama>Genel'i seçin, ardından Hata ayıklama başlatma profilleri kullanıcı arabirimini aç bağlantısını seçin.

• Proje Çözüm Gezgini'nde seçili durumdayken, yer tutucunun proje adı olduğu Hata Ayıklama menüsünden {PROJECT NAME} Hata Ayıklama Özellikleri'ni{PROJECT NAME} seçin.

Yukarıdaki yaklaşımlar, dosyadaki ortam değişkeni ayarlarını düzenleyebileceğiniz launchSettings.json iletişim kutusunu açar. 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.

Profiller, Başlangıç düğmesinin (►) yanındaki Visual Studio kullanıcı arabiriminde seçilebilir.

Bir çözüm birden çok proje içerdiğinde, yalnızca başlangıç projesi için ortamı ayarlayın.

Alternatif olarak, dotnet run komutunu, -lp|--launch-profile olarak ayarlanmış şekilde kullanın . Bu yaklaşım yalnızca komutuna Project göre başlatma profillerini destekler.

dotnet run -lp "https"

Visual Studio Codeiçin C# Geliştirme Seti ile Visual Studio Code kullanırken (VS Code'da C# kullanmaya başlama), başlatma profilleri uygulamanın launchSettings.json dosyasından alınır.

C# Geliştirme Seti kullanılmıyorsa, ASPNETCORE_ENVIRONMENT bölümündeki .vscode/launch.json içindeki env ortam değişkenini ve diğer ortam değişkenlerini ayarlayın.

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

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

Ortamı bir ortam değişkeniyle 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 Üretim ortamına 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.

Azure App Service

Azure App Service'e dağıtılan uygulamalar varsayılan olarak Üretim ortamını benimser.

Ortam değişkenini ASPNETCORE_ENVIRONMENT ayarlamak için Azure belgelerinde aşağıdaki kaynaklara bakın:

• App Service uygulamasını yapılandırma
• Azure App Service'te hazırlama ortamlarını ayarlama

Bir uygulama ayarı eklendikten, değiştirildikten veya silindikten sonra Azure App Service uygulamayı otomatik olarak yeniden başlatır.

İşlem için ortam değişkenini ayarlama

ASPNETCORE_ENVIRONMENT kullanılarak uygulama başlatıldığında, geçerli oturum (komut kabuğu) için dotnet run ortam değişkenini ayarlamak amacıyla aşağıdaki komutları kullanın. Ortam değişkeni ayarlandıktan sonra, uygulama --no-launch-profile seçeneği kullanılarak başlatma profili olmadan başlatılır.

1. Komut kabuğunda, işletim sisteminiz için uygun yaklaşımı kullanarak ortam değişkenini ayarlayın.

2. Başlatma profili kullanmadan komutunu yürütebilirsiniz dotnet run :

   dotnet run --no-launch-profile
   

PowerShell kullanırken, yukarıdaki adımlar aşağıdaki iki komutta birleştirilebilir. Aşağıdaki örnek Hazırlama ortamını ayarlar:

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

Ortam değişkenini genel olarak ayarlama

Ortam değişkenini ayarlamak ASPNETCORE_ENVIRONMENT için işletim sisteminiz için uygun kılavuzu kullanın.

ASPNETCORE_ENVIRONMENT Ortam değişkeni genel olarak ayarlandığında, değer ayarlandıktan sonra açılan herhangi bir komut kabuğundaki komut için dotnet run geçerli olur. Başlatma launchSettings.json dosyasındaki profiller tarafından ayarlanan ortam değerleri, sistem ortamı için ayarlanan değerleri geçersiz kılar.

IIS'ye dağıtılan uygulamalar için ortamı ayarlama

Dosyayla ortam değişkenini ASPNETCORE_ENVIRONMENT ayarlamak için bkz. web.config.

IIS'ye dağıtımda ortam değişkenini ayarlamak için yayımlama profiline <EnvironmentName>(.pubxml) veya proje dosyasına özelliğini ekleyin. Aşağıdaki örnek, proje yayımlandığında içindeki web.config ortamını Hazırlama ortamına ayarlar:

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

Yalıtılmış Bir Uygulama Havuzunda çalışan bir uygulama için ortam değişkenini ayarlamak üzere (IIS 10.0 veya sonraki sürümlerde desteklenir), Ortam Değişkenleri ASPNETCORE_ENVIRONMENT. 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ı çalıştırmak için yeni değerin etkili olması için aşağıdaki yaklaşımlardan birini kullanın:

• Komut kabuğunda önce net stop was /y sonra net start w3svc yürütün.
• Sunucuyu yeniden başlatın.

Docker

Bu bölümdeki yaklaşımlardan herhangi birini kullanarak uygulamanın ortamını ayarlayın.

Dockerfile kullanma

ASPNETCORE_ENVIRONMENT Aşağıdaki yönergeleri kullanarak Dockerfile içindeki ortam değişkenini ENV ayarlayın:

ENV ASPNETCORE_ENVIRONMENT=Staging

Docker Compose kullanma

Docker Compose ile yönetilen çok hizmetli uygulamalar için dosya içinde ASPNETCORE_ENVIRONMENT ortam değişkenlerini tanımlayındocker-compose.yml:

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

Docker Compose ile çalışma zamanında ayarlanan bir ortam, Dockerfile tarafından ayarlanan bir ortamı geçersiz kılar.

docker run komutunu kullanma

Docker kapsayıcısını komutuyladocker run çalıştırırken ortam değişkenini ASPNETCORE_ENVIRONMENT şu seçenekle -e|--env ayarlayın:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Çalışma zamanında docker run ayarlanmış bir ortam, Dockerfile tarafından ayarlanan bir ortamı geçersiz kılar.

Docker ortam dosyası

ASPNETCORE_ENVIRONMENT Bir Docker ortam dosyası (.env) kullanarak ortam değişkenini ayarlayın.

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Komutu yürütürken --env-filedosyasını şu seçenekle docker run yükleyin:

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

Çalışma zamanında docker run ayarlanmış bir ortam, Dockerfile tarafından ayarlanan bir ortamı geçersiz kılar.

Uygulamanın başlangıç kodunda ortamı ayarlama

Kodda ortamı ayarlamak için, aşağıdaki örnekte gösterildiği gibi öğesini oluştururken WebApplicationOptions.EnvironmentNamekullanınWebApplicationBuilder:

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

Ortama göre yapılandırmayı yükleme

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

Startup sınıfından ortama erişim

.NET 6'nın yayımlanmasından önce ve sonrasında Startup sınıfı (Startup.cs) ile Configure ve ConfigureServices yöntemlerinin kullanılması gerekiyordu ve bu desteklenmeye devam ediyor.

Kod yürütmeyi kontrol etmek için IWebHostEnvironment öğesini Startup oluşturucusuna enjekte edin. Uygulama, ortam başına en az kod farkı olan yalnızca birkaç ortam için başlangıç kodunu yapılandırmayı gerektirdiğinde bu yaklaşım kullanışlıdır.

Aşağıdaki örnekte, ortam alanda _env tutulur ve uygulamanın ortamına göre kod yürütmeyi denetler:

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Ortama özgü Startup sınıf

Bir uygulama, farklı ortamlar için, yer tutucunun ortam adı olduğu Startup adlandırma kuralı Startup{EnvironmentName} sınıfıyla birden çok {ENVIRONMENT NAME} sınıf tanımlayabilir.

Ad soneki geçerli ortamla eşleşen sınıf önceliklendirilir. Eşleşen Startup{EnvironmentName} bir sınıf bulunamazsa, Startup sınıfı kullanılır.

Ortam tabanlı Startup sınıflar uygulamak için, gerektiği kadar sınıf Startup{EnvironmentName} ve bir geri dönüş Startup sınıfı oluşturun:

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Konak oluşturucunun oluşturulduğu yerde HostingAbstractionsWebHostBuilderExtensions.UseStartup öğesini çağırarak, doğru Startup sınıfını yüklemek için bir derleme adını kabul edin.

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

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

Ortama özgü Startup sınıf yöntemleri

Configure ve ConfigureServices yöntemleri, formun Configure{ENVIRONMENT NAME} ve Configure{ENVIRONMENT NAME}Servicesortamının ortama özgü sürümlerini destekler; burada {ENVIRONMENT NAME} yer tutucu ortam adıdır. Adlandırılmış yöntemler için eşleşen bir ortam adı bulunamazsa, ConfigureServices sırasıyla veya Configure yöntemi kullanılır.

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

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

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

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

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ı