ASP.NET Core'da Configuration Okuma Sırası

8 dk okuma · Emre Ulutabak

Katmanlı okuma mantığı

Sabah evden çıkarken üst üste giyinirsin. İç kazak, dış kazak, ceket. Dışarıdan bakan ne görür? Ceketi. İç kazak ceketin altında kalır, görünmez.

ASP.NET Core'da configuration sistemi tam böyle çalışır. Birden fazla kaynak üst üste okunur ve son okunan kazanır — önceki değeri ezer.

Okuma sırası şöyledir:

appsettings.json — her zaman okunur, temel değerler
appsettings.{Environment}.json — ortama göre okunur (Production, Development...)
Environment Variables — son okunur, öncekini ezer
Command Line Arguments — en son, sadece özel durumlarda

💡

Son okunan kazanır. Environment Variables, appsettings.json'daki aynı key'i her zaman ezer.

appsettings ve ortam dosyaları

ASPNETCORE_ENVIRONMENT değişkeni hangi ortam dosyasının okunacağını belirler. Bu değişken Production ise appsettings.Production.json okunur; Development ise appsettings.Development.json okunur.

Shared hosting'de bu değişken genellikle web.config içinde ayarlanır ya da hosting panelinden tanımlanır.

xml

<!-- web.config — ASPNETCORE_ENVIRONMENT ayarı -->
<aspNetCore processPath="dotnet" arguments=".\MyApp.dll"
            hostingModel="outofprocess">
  <environmentVariables>
    <!-- Bu değer appsettings.Production.json'ın okunmasını sağlar -->
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
  </environmentVariables>
</aspNetCore>

__ (çift alt çizgi) kuralı

JSON dosyalarında iç içe yapılar nokta ile temsil edilir: ConnectionStrings.DefaultConnection. Ama environment variable isimleri nokta içeremez — işletim sistemi buna izin vermez.

Bu yüzden ASP.NET Core, JSON hiyerarşisini env var'da çift alt çizgi (__) ile temsil eder.

csharp

// appsettings.json'daki JSON yapısı:
// {
//   "ConnectionStrings": { "DefaultConnection": "..." },
//   "EmailSettings": { "SmtpServer": "smtp.brevo.com" },
//   "Jwt": { "PrivateKeyPath": "private.key" }
// }

// Karşılık gelen environment variable key'leri:
// ConnectionStrings__DefaultConnection
// EmailSettings__SmtpServer
// Jwt__PrivateKeyPath

// Program.cs'te okuma:
var connStr = builder.Configuration.GetConnectionString("DefaultConnection");
var smtp    = builder.Configuration.GetSection("EmailSettings")["SmtpServer"];
var keyPath = builder.Configuration["Jwt:PrivateKeyPath"];

💡

Kural: JSON'da iç içe yapı → env var'da __ (çift alt çizgi). Nokta değil, çift alt çizgi.

GetConnectionString kuralı

En sık yapılan hatalardan biri budur: GetConnectionString("X") yazmak ama env var'a yanlış key koymak.

GetConnectionString("DefaultConnection") aslında Configuration["ConnectionStrings:DefaultConnection"] kısayoludur. Yani env var key'i ConnectionStrings__DefaultConnection olmalı — X ne ise key'in sonu da o olmalı.

csharp

// Program.cs
var connStr = builder.Configuration.GetConnectionString("DefaultConnection");
// Doğru env var key: ConnectionStrings__DefaultConnection

var connStr2 = builder.Configuration.GetConnectionString("database");
// Doğru env var key: ConnectionStrings__database
// YANLIS: ConnectionStrings__DefaultConnection — eşleşmez, null döner!

💡

GetConnectionString("X") → env var key = ConnectionStrings__X. Birebir aynı olmalı.

Altın kurallar

💡

appsettings.json'a şifre koyma. Bu dosya Git'e gider, tüm ekip görür.

💡

Sırları environment variables'a koy. Son okunur, kazanır — ve Git'e gitmez.

💡

Key eşleşmezse null döner, hata fırlatmaz. Bağlantı hatalarında ilk kontrol ettiğin yer burası olsun.

Mini quiz

MİNİ QUIZ

appsettings.json'da `EmailSettings:SmtpServer` değeri varsa, bunu ezmek için hangi environment variable key'i kullanılır?

EmailSettings.SmtpServer

EmailSettings-SmtpServer

EmailSettings__SmtpServer

SmtpServer__EmailSettings