ASP.NET Core’de Yapılandırma

ASP.NET Core'daki uygulama yapılandırması bir veya daha fazla yapılandırma sağlayıcısı kullanılarak gerçekleştirilir. Yapılandırma sağlayıcıları, çeşitli yapılandırma kaynakları kullanarak anahtar-değer çiftlerinden yapılandırma verilerini okur:

• appsettings.json gibi dosyaları ayarlama
• Azure Uygulama yapılandırması dahil olmak üzere ortam değişkenleri
• Azure Key Vault
• Komut satırı bağımsız değişkenleri
• Yüklenen veya oluşturulan özel sağlayıcılar
• Bellek içi .NET nesneleri

Bu makale, ASP.NET Core'da yapılandırma hakkında bilgi sağlar. non-ASP.NET Core uygulamalarında yapılandırma kullanma hakkında bilgi için bkz. .NET Yapılandırması.

Buradaki yönergeleri ekleyen veya yerine geçen ek Blazor yapılandırma yönergeleri için bkz. ASP.NET Temel Blazor yapılandırma.

Bu makale öncelikli olarak uygulama yapılandırmasıyla ilgili. Başlatma ayarları dosyaları ve web.config dosya gibi diğer yapılandırma türleri burada belirtilmiştir, ancak birincil belgeleri başka bir yerdedir:

• Başlatma ayar dosyaları (launch.json, /, launchSettings.json), Development ortamı için araç yapılandırma dosyalarıdır. Daha fazla bilgi için bkz. ASP.NET Core çalışma zamanı ortamları. Başlatma ayarlarıyla ilgili bazı ayrıntılar, Başlatma ayarları geçersiz kılma ortam değişkeni ayarları bölümündeki bu makalede ele alınmıştır.
• web.config, Internet Information Services (IIS) için bir sunucu yapılandırma dosyasıdır. Daha fazla bilgi için bkz. ASP.NET Core'u Windows'ta IIS ile Barındırma ve IIS için ASP.NET Core Modülü (ANCM).

Uygulama yapılandırmasını önceki ASP.NET sürümlerinden geçirme hakkında daha fazla bilgi için bkz. Yapılandırmayı ASP.NET Core'a geçirme.

Warning

Bu makalede bağlantı dizesi kullanımı gösterilmektedir. Geliştirme ve test için yerel bir veritabanı kullanırken, bağlantı dizesi aracılığıyla veritabanı kullanıcı kimlik doğrulaması gerekmez. Üretim ortamlarında, bağlantı dizeleri bazen veritabanı erişiminin veya veritabanı işlemlerinin kimliğini doğrulamak için bir parola içerir. Bir bağlantı dizesindeki kaynak sahibi parola kimlik bilgileri (ROPC), üretim uygulamalarında kaçınılması gereken bir güvenlik riskidir. Üretim uygulamaları kullanılabilir en güvenli kimlik doğrulama akışını kullanmalıdır. Test veya üretim ortamlarına dağıtılan uygulamalar için kimlik doğrulaması hakkında daha fazla bilgi için ASP.NET Temel güvenlik konularına bakın.

Bu makaledeki örneklerde C# 12 (.NET 8) veya sonraki sürümlerde kullanılabilen birincil oluşturucular kullanılır. Daha fazla bilgi için bkz. Sınıflar ve yapılar için birincil oluşturucuları bildirme (C# belgeleri öğreticisi) ve Birincil oluşturucular (C# Kılavuzu).

Yapılandırma değerlerini okuma

Yapılandırma, genellikle IConfiguration hizmetini (Microsoft.Extensions.Configuration ad alanı) çözümleyerek ve yapılandırma anahtar-değer çiftlerinin anahtarını kullanarak bir yapılandırma değeri elde edilmesi suretiyle okunur.

Aşağıdaki Razor bileşen kodu, teknik iletişim e-posta adresi olan bir yapılandırma ayarının, TechnicalContactEmail anahtarı kullanılarak yapılandırmadan nasıl elde edildiğini gösterir.

@inject IConfiguration Config

Technical Contact: @Config["TechnicalContactEmail"]

Uygulama ve konak yapılandırması

ASP.NET Core uygulamaları bir ana bilgisayar yapılandırır ve başlatır. Sunucu, uygulamanın başlatılmasından ve ömür yönetiminden sorumludur. Sunucu yapılandırma anahtar-değer çiftleri, uygulamanın yapılandırmasına dahil edilir. Host yapılandırma sağlayıcılarıyla bazı uygulama yapılandırmaları gerçekleştirebilmenize rağmen, yalnızca host için gerekli olanı yapılandırmanızı öneririz.

Uygulama yapılandırması en yüksek önceliktir. Ana bilgisayar oluşturulduğunda yapılandırma sağlayıcılarının nasıl kullanıldığı ve yapılandırma kaynaklarının ana bilgisayar yapılandırmasını nasıl etkilediği hakkında daha fazla bilgi için, bkz. ASP.NET Core temel bilgilerine genel bakış.

Varsayılan uygulama yapılandırma kaynakları

ASP.NET Core web uygulamaları, sınıfın WebApplication.CreateBuilder yeni bir örneğini önceden yapılandırılmış varsayılanlarla başlatmak için çağırırWebApplicationBuilder:

var builder = WebApplication.CreateBuilder(args);

Daha fazla bilgi için, bkz. ASP.NET Core'da .NET Genel Ana Bilgisayarı.

Varsayılan uygulama yapılandırması en yüksekten en düşük önceliğe kadar aşağıdaki sırayla yüklenir:

1. Komut Satırı Yapılandırma Sağlayıcısı'nı kullanan komut satırı bağımsız değişkenleri.
2. Ortam Değişkenleri Yapılandırma Sağlayıcısı kullanılarak veya ASPNETCORE_ ile ön eklenmemiş ortam DOTNET_.
3. Uygulama ortamında çalıştırıldığında kullanıcı Development, Dosya Yapılandırma Sağlayıcısı kullanılarak yönetilir.
4. Çevresel uygulama ayarları dosya yapılandırması, appsettings.{ENVIRONMENT}.json aracılığıyla yapılır; burada {ENVIRONMENT} yer tutucu, JSON Yapılandırma Sağlayıcısı kullanılarak uygulamanın ortamıdır. Örneğin, appsettings.Production.json üretimde kullanılır ve appsettings.Development.json geliştirme sırasında kullanılır.
5. JSON Yapılandırma Sağlayıcısı'nı kullanarak appsettings.json.
6. Geri dönüş ana bilgisayar yapılandırması.

Note

Yalnızca çalışma zamanında yapılandırma değerlerini almak amacıyla birden fazla çağrı yapmanızı önermeyiz CreateBuilder . Örneğin bir ConfigurationManager veya builder.Configuration kullanmanızı ya da uygun yapılandırma kaynağından bir WebApplicationBuilder.Configuration kullanmanızı öneririz.

Komut satırı bağımsız değişkenlerinin yüklenecek ortam tabanlı uygulama ayarları dosyasını belirlemek için önemli olan ortam adı gibi ayarları denetlemesine izin vermek için, Komut Satırı Yapılandırma Sağlayıcısı yapılandırmanın başında ve sonunda iki kez yapılandırma kaynağı olarak kullanılır. Sağlayıcı en son kullanıldığından en yüksek önceliğe sahiptir.

Uygulama ve konak yapılandırmasında bir yapılandırma değeri ayarlandığında, uygulama yapılandırması kullanılır.

Varsayılan ana bilgisayar yapılandırma kaynakları

Web uygulamasının yapılandırmasına uygulandığında en yüksekten en düşük önceliğe kadar varsayılan konak yapılandırma kaynakları (WebApplicationBuilder):

1. Komut Satırı Yapılandırma Sağlayıcısı'nı kullanan komut satırı bağımsız değişkenleri.
2. DOTNET_Öneki bulunan ortam değişkenleri, Ortam Değişkenleri Yapılandırma Sağlayıcısı kullanılarak yapılandırılır.
3. ASPNETCORE_Öneki bulunan ortam değişkenleri, Ortam Değişkenleri Yapılandırma Sağlayıcısı kullanılarak yapılandırılır.

Genel Ana Bilgisayara veya Web Konağına uygulanan en yüksekten en düşük önceliğe kadar varsayılan konak yapılandırma kaynakları:

1. ASPNETCORE_Öneki bulunan ortam değişkenleri, Ortam Değişkenleri Yapılandırma Sağlayıcısı kullanılarak yapılandırılır.
2. Komut Satırı Yapılandırma Sağlayıcısı'nı kullanan komut satırı bağımsız değişkenleri.
3. DOTNET_Öneki bulunan ortam değişkenleri, Ortam Değişkenleri Yapılandırma Sağlayıcısı kullanılarak yapılandırılır.

Konak yapılandırması hakkında daha fazla bilgi için aşağıdaki kaynaklara bakın:

• Generic Host: .NET 6 veya daha üstü bir hedefleyen, minimal hosting model'i benimseyen ASP.NET Core uygulamaları için önerilir.
• Web Sunucusu: .NET 6'dan önceki sürümleri hedefleyen ve yalnızca .NET 6 veya sonrası sürümlerle geriye dönük uyumluluk sağlamak amacıyla çerçeve tarafından korunmaya devam eden ASP.NET Core uygulamaları için gereklidir.

Konak değişkenleri

Aşağıdaki değişkenler konak oluşturucusu başlatma işleminin başlarında ayarlanır ve uygulama yapılandırmasından etkilenmez:

• Uygulama adı.
• Ortam adı.
• İçerik kökü.
• Web kök dizini.
• Barındırma başlangıç derlemelerinin taranıp taranmayacağı ve hangi derlemelerin taranacağı.
• HostBuilderContext.Configuration geri aramalarında IHostBuilder.ConfigureAppConfiguration uygulaması ve kitaplık kodu tarafından okunan değişkenler.

Diğer konak ayarları, konak yapılandırması yerine uygulama yapılandırmasından okunur.

URLS , konak yapılandırması tarafından önyüklenmeyen birçok yaygın konak ayarından biridir. URLS daha sonra uygulama ayarlarından okunur. Konak yapılandırması, uygulama yapılandırmasına alternatif olarak hizmet eder, bu nedenle konak yapılandırması URLS ayarlamak için kullanılabilir, ancak değer, uygulama ayarları dosyalarında (URLS veya ortam adı appsettings.{ENVIRONMENT}.json olan yerler) uygulama yapılandırmasında {ENVIRONMENT} ayarlanan herhangi bir yapılandırma kaynağı tarafından geçersiz kılınabilir.

Daha fazla bilgi için bkz. İçerik kökünü, uygulama adını ve ortamı değiştirme veİçerik kökünü, uygulama adını ve ortamı ortam değişkenlerine veya komut satırına göre değiştirme.

Güvenlik ve kullanıcı gizli bilgileri

Yapılandırma verisi kılavuzları:

• Parolaları veya diğer hassas verileri asla yapılandırma sağlayıcı kodunda veya düz metin yapılandırma dosyalarında saklamayın. Gizli Yönetici aracı geliştirmede gizli bilgileri depolamak için kullanılabilir.
• Üretimle ilgili gizli bilgileri geliştirme veya test ortamlarında kullanmayın.
• Yanlışlıkla bir kaynak kod havuzuna bağlanmamaları için projenin dışındaki sırları belirtin.
• Üretim uygulamaları kullanılabilir en güvenli kimlik doğrulama akışını kullanmalıdır. Daha fazla bilgi için bkz . Güvenli kimlik doğrulama akışları.

Kullanıcı Gizli Dizileri dosya yapılandırma kaynağı, varsayılan yapılandırma kaynakları arasında yer alır ve uygulama ayarları dosyaları için JSON yapılandırma kaynaklarından sonra kaydedilir. Bu nedenle, kullanıcı gizli dizi anahtarları, appsettings.json ve appsettings.{ENVIRONMENT}.json içindeki anahtarlara göre önceliklidir.

Parolaları veya diğer hassas verileri depolama hakkında daha fazla bilgi için:

• ASP.NET Core çalışma zamanı ortamları
• ASP.NET Core'da geliştirme aşamasında uygulama gizli dizi anahtarlarının güvenli depolanması: Hassas verileri depolamak için ortam değişkenlerini kullanma konusunda tavsiyeler içerir. Gizli Dizi Yöneticisi aracı, kullanıcı gizli dizilerini yerel sistemdeki bir JSON dosyasında depolamak için Dosya Yapılandırma Sağlayıcısı'nı kullanır.
• Azure Key Vault ASP.NET Core uygulamaları için uygulama gizli dizilerini güvenle saklar. Daha fazla bilgi için, bkz. ASP.NET Core'da Azure Key Vault yapılandırma sağlayıcı.

Bağımlılık Enjeksiyonu (DI) ile erişim yapılandırması

Hizmet, Bağımlılık Enjeksiyonu (DI) kullanılarak ve IConfiguration hizmeti çözümlenerek yapılandırılabilir. Aşağıdaki örnekte, {KEY} yer tutucusuyla temsil edilen yapılandırma anahtarının değeri value'ye atanır. Anahtar bulunamazsa, null öğesine valueatanır:

public class CustomService(IConfiguration config)
{
    public void CustomMethod()
    {
        var value = config["{KEY}"];
    }
}

Dosyadaki Program erişim yapılandırması

Aşağıdaki kod, Program dosyasındaki WebApplicationBuilder.Configuration yapılandırmaya builder.Configuration kullanarak erişir:

var defaultConnectionString = 
   builder.Configuration.GetValue<string>("ConnectionStrings:DefaultConnection");

Uygulama oluşturulduktan sonra (satırından var app = builder.Build();sonra), kullanın WebApplication.Configuration (app.Configuration):

var defaultLogLevel = app.Configuration.GetValue<string>("Logging:LogLevel:Default");

Startup sınıfında erişim yapılandırması

Bu bölüm genellikle .NET 6'nın yayımlanmasından önceki ASP.NET Core uygulamaları için geçerlidir.

Aşağıdaki kod, yapılandırma verilerini bir Startup yöntemlerinde görüntüler:

public class Startup
{
    public Startup(IConfiguration config)
    {
        Config = config;
    }

    public IConfiguration Config { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = Config["ConnectionStrings.DefaultConnection"];

        ...
    }

    public void Configure(...)
    {
        var defaultLogLevel = Config["Logging:LogLevel:Default"];

        ...
    }
}

Hata ayıklama için başlangıçta yapılandırma ayarlarını görüntüleme

Aşağıdaki kod, uygulama başlangıcında uygulamanın yapılandırma anahtar-değer çiftlerini görüntüler.

Uygulama Program dosyasında belirli bir satırın var app = builder.Build(); ardından, DEBUG yapılandırması için bir derleyici yönergesi içeren aşağıdaki kodu yerleştirin:

#if DEBUG
foreach (var c in app.Configuration.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

Yapılandırma anahtarları ve değerleri

Yapılandırma anahtarları:

• Büyük/küçük harfe duyarlı değildir. Örneğin, ConnectionString ve connectionstring eşdeğer anahtarlar olarak kabul edilir.
• Bir anahtar ve değer birden fazla yapılandırma sağlayıcısı tarafından ayarlanırsa, eklenen son sağlayıcının değeri kullanılır. Daha fazla bilgi için, bkz. Varsayılan yapılandırma.
• Hiyerarşik anahtarlar
  • Yapılandırma API'sinde, iki nokta üst üste ayırıcı (:) tüm platformlarda çalışır.
  • Çevresel değişkenlerde iki nokta ayırıcı tüm platformlarda çalışmaz. Çift alt çizgi (__) tüm platformlar tarafından desteklenir ve yapılandırma uygulama tarafından okunduğunda otomatik olarak iki nokta üst üste (:) olarak dönüştürülür.
  • Azure Key Vault'ta hiyerarşik anahtarlar ayırıcı olarak çift kısa çizgi (--) kullanır. Azure Key Vault Yapılandırma Sağlayıcısı, gizli bilgiler uygulamanın yapılandırmasına yüklenirken çift tireleri (--) otomatik olarak iki nokta üst üste (:) ile değiştirir.
• ConfigurationBinder, yapılandırma anahtarlarında dizi dizinlerini kullanarak dizileri nesnelere bağlamayı destekler. Dizi bağlama, Dizi bağlama bölümünde açıklanmıştır.

Yapılandırma değerleri dizelerdir. Null değerler yapılandırmada saklanamaz veya nesnelere bağlı olamaz.

Hiyerarşik yapılandırma verilerinin düzeni

Yapılandırma API'si, genellikle iki nokta üst üste (:) olan yapılandırma anahtarlarında bir sınırlayıcı kullanarak hiyerarşik verileri düz bir forma indirger ve böylece hiyerarşik yapılandırma verilerini okur. Çift alt çizgi (__) genellikle platformlar arası destek için ortam değişkeni yapılandırmasıyla birlikte kullanılır.

Note

Karmaşık uygulama yapılandırma senaryolarında, seçenekler desenini kullanarak ilgili hiyerarşik yapılandırma verilerini gruplandırmak ve okumak en iyisidir.

Aşağıdaki hiyerarşik yapılandırma verilerini göz önünde bulundurun:

• ConnectionStrings
  • DefaultConnection (Value = 'Data Source=LocalSqlServer\MSSQLDev;')
• Logging
  • LogLevel
    • Default (Value = 'Information')
    • Microsoft (Value = 'Warning')
    • Microsoft.Hosting.Lifetime (Value = 'Information')
• AllowedHosts (Value = '*')

Aşağıdaki tabloda, önceki yapılandırma verilerindeki değerleri kurtarmak için kullanılan anahtarlar görüntülenir. AllowedHosts için sınırlayıcı gerekli değildir.

Anahtar (iki nokta üst üste sınırlayıcı)	Anahtar (çift alt çizgi sınırlayıcısı)
ConnectionStrings:DefaultConnection	ConnectionStrings__DefaultConnection
Logging:LogLevel:Default	Logging__LogLevel__Default
Logging:LogLevel:Microsoft	Logging__LogLevel__Microsoft
Logging:LogLevel:Microsoft.Hosting.Lifetime	Logging__LogLevel__Microsoft.Hosting.Lifetime
AllowedHosts	AllowedHosts

Note

Karmaşık uygulama yapılandırma senaryolarında Seçenekler desenini kullanarak ilgili hiyerarşik yapılandırma verilerini gruplandırmanızı ve okumanızı öneririz.

GetSection ve GetChildren yöntemleri yapılandırma verilerinde bir bölümün bölümlerini ve alt öğelerini ayırmak için kullanılabilir. Bu yöntemler, GetSectionve GetChildren değerlerinin ele alındığı yerlerdeExists açıklanmıştır.

Öğe yapısı bir dizi içerdiğinde, dizi dizini yolda ek öğe adı olarak ele alınmalıdır. Aşağıdaki hiyerarşik yapılandırma verilerini bir dizi olarak düşünün.

MainObject (bir dizi):

• Dizideki ilk öğe
  • Object0
  • Object1
    • SubObject0
    • SubObject1
• Dizideki ikinci öğe
  • Object0
  • Object1
    • SubObject0
    • SubObject1

İki nokta üst üste ayırıcılı tuşlar:

• MainObject:0:Object0
• MainObject:0:Object1:SubObject0
• MainObject:0:Object1:SubObject1
• MainObject:1:Object0
• MainObject:1:Object1:SubObject0
• MainObject:1:Object1:SubObject1

Alt çizgi ayırıcıları olan anahtarlar; yapılandırma ortam değişkenleri tarafından sağlandığında platformlar arası uyumluluk için önerilir:

• MainObject__0__Object0
• MainObject__0__Object1:SubObject0
• MainObject__0__Object1:SubObject1
• MainObject__1__Object0
• MainObject__1__Object1:SubObject0
• MainObject__1__Object1:SubObject1

Dizilerden gelen yapılandırma, bir uygulamanın kullandığı her yapılandırma kaynağı için sıralı olarak düzleştirilmiş ve numaralandırıldığından, birden çok kaynaktan verileri yapılandırırken ve okurken dikkatli olunmadığında değerlerin üzerine beklenmedik şekilde yazılabilir. Aşağıdaki yapılandırma anahtar-değer çiftlerini göz önünde bulundurun:

Modules değerler (bir dizi):

• Module1
• Module2
• Module3

Dizi düzleştirilmiştir ve yapılandırma anahtar-değer çiftlerini üreten ardışık olarak indekslenir, aşağıdaki tabloda.

Key	Değer
Modules:0	Module1
Modules:1	Module2
Modules:2	Module3

Önceki yapılandırma oluşturulduktan sonra, başka bir yapılandırma kaynağı aşağıdaki yapılandırmayı yükler:

Modules değerler (bir dizi):

• Module4
• Module5

Bu dizi de sırayla düzleştirilip dizine eklenmiştir.

Key	Değer
Modules:0	Module4
Modules:1	Module5

Belirli bir anahtar için son yapılandırma kaynağının bu anahtarın değerini ayarladığını hatırlayarak, yapılandırma anahtar-değer çiftlerinin son kümesi aşağıdaki tabloda gösterilmiştir.

Key	Değer
Modules:0	Module4
Modules:1	Module5
Modules:2	Module3

Çerçeve yazılımının yapılandırma kaynaklarından dizi verilerini nasıl düzleştirdiği ve dizine eklediği göz önüne alındığında bu şaşırtıcı bir sonuç değildir, ancak beklenmeyen ezilmeleri önlemek için dikkate alınmalıdır.

Bu tür üzerine yazma işlemlerinden kaçınmak için, dizi indekslemeyi aynı dizi verilerini sağlayan çeşitli yapılandırma kaynaklarıyla eşleşecek şekilde düzenleyin. Alternatif olarak, geçici bir yaklaşım, tek bir anahtar-değer çiftinin dize değerindeki dizi değerlerini sınırlandırmaktır( örneğin, sınırlayıcı olarak virgül, noktalı virgül veya kanal kullanma). Dizeyi bölmek ve sınırlandırılmış değerleri dizinize atamak için özel kod yazın.

Yapılandırma sağlayıcıları

Aşağıdaki tablo, ASP.NET Core uygulamaları için kullanılabilen yapılandırma sağlayıcılarını gösterir.

Provider	Yapılandırmayı şuradan sağlar...
Azure Key Vault Yapılandırma Sağlayıcısı	Azure Key Vault
Azure Uygulama Yapılandırma Sağlayıcısı	Azure Uygulama Yapılandırması
Komut Satırı Yapılandırma Sağlayıcısı	Komut satırı parametreleri
Özel yapılandırma sağlayıcı	Özel kaynak
Ortam Değişkenleri Yapılandırma Sağlayıcısı	Ortam değişkenleri
Dosya Yapılandırma Sağlayıcısı	INI, JSON ve XML dosyaları
Anahtar Dosya Bazlı Yapılandırma Sağlayıcısı	Dizin dosyaları
Bellek Yapılandırma Sağlayıcısı	Bellek içi koleksiyonlar
Kullanıcı sırları	Kullanıcı profili dizinindeki dosya

Yapılandırma kaynakları, yapılandırma sağlayıcılarının belirtildiği sırayla okunur. Uygulamanın gerektirdiği temeldeki yapılandırma kaynaklarının önceliklerine uyacak şekilde yapılandırma sağlayıcılarını kod halinde düzenleyin.

Tipik bir yapılandırma sağlayıcıları dizisi:

1. appsettings.json aracılığıyla genel uygulama ayarları.
2. Çevresel uygulama ayarları, appsettings.{ENVIRONMENT}.json aracılığıyla yapılır; burada {ENVIRONMENT} yer tutucu, uygulamanın ortamıdır (örnekler: Development, Production).
3. Kullanıcı sırları.
4. Ortam Değişkenleri Yapılandırma Sağlayıcısı'nı kullanan ortam değişkenleri.
5. Komut Satırı Yapılandırma Sağlayıcısı'nı kullanan komut satırı bağımsız değişkenleri.

Yaygın bir uygulama, komut satırı bağımsız değişkenlerinin diğer sağlayıcılar tarafından belirlenen yapılandırmayı geçersiz kılmasına izin vermek için bir sağlayıcı dizisinde en son Komut Satırı Yapılandırma Sağlayıcısını eklemektir.

Varsayılan yapılandırmada önceki sağlayıcı dizisi kullanılır.

Uygulamanın yapılandırma sağlayıcılarını incelemek için enjekte edinIConfiguration, IConfigurationRoot tipine dönüştürün ve Providers özelliğini okuyun.

Aşağıdaki ConfigurationProvidersRazor bileşende, etkin yapılandırma sağlayıcıları uygulamaya eklendikleri sırayla görüntülenir.

Pages/ConfigurationProviders.razor:

@page "/configuration-providers"
@inject IConfiguration Config

<h1>Configuration Providers</h1>

@if (ConfigRoot is not null)
{
    <ul>
        @foreach (var provider in ConfigRoot.Providers)
        {
            <li>@provider</li>
        }
    </ul>
}

@code {
    private IConfigurationRoot? ConfigRoot;

    protected override void OnInitialized()
    {
        ConfigRoot = (IConfigurationRoot)Config;
    }
}

Önceki Razor bileşeni, {APP NAMESPACE} yer tutucusunun uygulamanın ad alanı olduğu aşağıdaki çıktıyı üretir:

MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'ASPNETCORE_'
MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'DOTNET_'
JsonConfigurationProvider for 'appsettings.json' (Optional)
JsonConfigurationProvider for 'appsettings.Development.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.Development.json' (Optional)
EnvironmentVariablesConfigurationProvider
Microsoft.Extensions.Configuration.ChainedConfigurationProvider

Bu makalenin önceki bölümlerindeki Varsayılan uygulama yapılandırma kaynakları bölümünde, yapılandırma kaynakları en yüksekten en düşük önceliğe kadar listelenir. Yukarıdaki ConfigurationProviders bileşen, kaynakları uygulamanın okuma sırasına göre görüntüler. Örneğin, ortam dışı uygulama ayarları dosyasının () JSON Yapılandırma Sağlayıcısı, Geliştirme ortamıappsettings.json uygulama ayarları dosyasının (appsettings.Development.json) sağlayıcısından önce eklendiğinden önceki listede daha önce yer alır. Yapılandırma sağlayıcıları listenin en üstünden listenin en altına doğru yürütülür. İki uygulama ayarı JSON Yapılandırma Sağlayıcısı arasında eşleşen bir yapılandırma anahtarı için, son ayar önceliklidir ve bu, appsettings.Development.json'den alınan değerdir.

Uygulama ayarları dosya yapılandırması (appsettings.json, appsettings.{ENVIRONMENT}.json)

JSON Yapılandırma Sağlayıcısı'nı kullanarak uygulama ayarları dosyalarından yüklenen yapılandırmayı okuyun.

Aşağıdaki appsettings.json dosyasını göz önünde bulundurun:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=LocalSqlServer\\MSSQLDev;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Yapılandırma değerlerini okumak için öğesinin bir örneğini IConfiguration.

Aşağıdaki AppSettingsConfigurationRazor bileşen, varsayılan veritabanı bağlantı dizesini ve varsayılan log seviyesini yapılandırmasını okur. IConfiguration bileşenin en üstüne eklenir ve yapılandırma değerlerini okumak için kullanılır. Dize biçimli yapılandırma anahtarlarında, uygun JSON özelliklerini bulmak için iki nokta üst üste ayırıcı (:) kullanılır. Örneğin, varsayılan bağlantı dizesi (DefaultConnection) nesnesinin JSON yapısı bağlantı dizeleri (ConnectionStrings) nesnesinin altında iç içe yerleştirilmiştir, bu nedenle varsayılan bağlantı dizesine erişmek için dize gösterimi, nesnelerin uygulama ayarları dosyasında görünme sırasına göre iki DefaultConnectionConnectionStrings nokta üst üste kullanır: ConnectionStrings:DefaultConnection.

Pages/AppSettingsConfiguration.razor:

@page "/app-settings-configuration"
@inject IConfiguration Config

<h1>App Settings Configuration</h1>

<ul>
    <li>Default Connection String: @Config["ConnectionStrings:DefaultConnection"]
    <li>Default Log Level: @Config["Logging:LogLevel:Default"]
</ul>

Aynı yaklaşım Sayfalar Razor sayfası modelinde de uygulanır:

using Microsoft.Extensions.Configuration;

...

public class AppSettingsPageModel(IConfiguration config) : PageModel
{
    public ContentResult OnGet()
    {
        var defaultConnectionString = config["ConnectionStrings:DefaultConnection"];
        var defaultLogLevel = config["Logging:LogLevel:Default"];

        return Content(
            $"Default Connection String: {defaultConnectionString}\n" +
            $"Default Log Level: {defaultLogLevel}");
    }
}

Varsayılan JsonConfigurationProvider örnekler yapılandırmayı aşağıdaki sırayla yükler:

1. appsettings.json
2. appsettings.{ENVIRONMENT}.json, burada {ENVIRONMENT} yer tutucu uygulamanın ortamıdır (örnekler: appsettings.Production.json, appsettings.Development.json). Dosyanın ortam sürümü IHostingEnvironment.EnvironmentName ortamına göre yüklenir.

appsettings.{ENVIRONMENT}.json değerleri appsettings.json içindeki anahtarları geçersiz kılar.

Varsayılan olarak:

• Geliştirme ortamında, appsettings.Development.json içinde bulunan değerlerin üzerine appsettings.json yapılandırması yazar.
• Üretim ortamında appsettings.Production.json yapılandırması, appsettings.json içinde bulunan değerlerin üzerine yazar.

Yukarıdaki örnek yalnızca dizeleri okur ve varsayılan değeri desteklemez. Bir yapılandırma değerinin varsayılan değerle garanti edilmesi gerekiyorsa, Tür dönüştürme (GetValue) ile yapılandırmadan tek bir değer ayıklama bölümüne bakın.

Varsayılan uygulama yapılandırma kaynaklarıappsettings.json kullanılarak ve appsettings.{ENVIRONMENT}.json dosyaları reloadOnChange olarak ayarlanırtrue. Bu, uygulama başlatıldıktan hemen sonra veya appsettings.json dosyalarında appsettings.{ENVIRONMENT}.json yapılan değişikliklerin dosya kaydedildikten hemen sonra geçerli olduğu anlamına gelir.

appsettings.json ve appsettings.{ENVIRONMENT}.json dosyalarındaki açıklamalar, JavaScript veya C# tarzı yorumlar kullanılarak desteklenir. Resmi JSON belirtimi (RFC 7159 ) JSON dosyalarındaki açıklamalar için izin almadığından, bazı tümleşik geliştirme ortamları (IDE)açıklamalar içeren bir JSON dosyasını düzenlerken hatalar görüntüler. Yorum hatalarını ve uyarılarını genellikle yoksayabilirsiniz, ancak genellikle IDE'de bir ayarı kullanarak uyarıları veya hataları devre dışı bırakabilirsiniz. Örneğin Visual Studio Code'da hataları devre dışı bırakmak için aşağıdakini dosyaya ekleyin settings.json :

"files.associations": {
  "appsettings*.json": "jsonc"
}

Yukarıdaki ayar, VS Code'a ortam tabanlı dosyalar da dahil olmak üzere uygulama ayarları dosyalarının açıklamaları destekleyen JSONC ("Açıklamalar ile JSON") dosya biçimiyle ilişkilendirildiğini gösterir.

Diğer IDE'ler için, JSON dosyalarındaki yorumlarla ilgili hataları veya uyarıları nasıl susturacaklarını belirlemek için IDE'nin belgelerine ve ürün destek kanallarına bakın.

Ortam Değişkenleri Yapılandırma Sağlayıcısı

Varsayılan Ortam Değişkenleri Yapılandırma Sağlayıcısı (EnvironmentVariablesConfigurationProvider), veya ASPNETCORE_ön eki DOTNET_ olmayan ortam değişkenlerinden yapılandırmayı yükler. ve ortam değişkenleri hakkında ASPNETCORE_ daha fazla bilgi için DOTNET_ bölümüne ve .DOTNET_

Varsayılan Ortam Değişkenleri Yapılandırma Sağlayıcısı'nı kullanarak uygulama, , appsettings.jsonve appsettings.{ENVIRONMENT}.json okuduktan sonra ortam değişkeni anahtar-değer çiftlerinden yapılandırma yükler. Bu nedenle, ortamdan okunan anahtar değerler, appsettings.json, appsettings.{ENVIRONMENT}.json ve kullanıcı gizli dizilerinden okunan değerleri geçersiz kılar.

: ayıracı, tüm platformlarda ortam değişkeni hiyerarşik anahtarlarıyla çalışmaz. Örneğin, : ayırıcı Bash tarafından desteklenmez. Çift alt çizgi, __, tüm platformlar tarafından desteklenir ve otomatik olarak iki nokta, :, ile değiştirilir.

Windows'da bir komut kabuğunda veya platformlar arası PowerShell komut kabuğunda ortam değişkenlerini ayarlama yönergeleri için aşağıdaki kaynaklara bakın:

• set (ortam değişkeni)
• setx
• about_Environment_Variables (PowerShell dokümantasyonu)

Ortam değişkenleri için özel ön ek

Özel ön ekli ortam değişkenleri için bir yapılandırma sağlayıcısı ekleyebilirsiniz. Program dosyasında, AddEnvironmentVariables çağrıldıktan sonra bir ön ek belirtmek için WebApplication.CreateBuilder'i bir dize ile çağırın. Sağlayıcı varsayılan yapılandırma sağlayıcılarından sonra eklenir, bu nedenle eklenen sağlayıcı ön ek olmadan aynı ada sahip ortam değişkenleri de dahil olmak üzere daha yüksek önceliğe sahiptir.

Aşağıdaki örnekte ortam değişkenleri ön ekiyle CustomPrefix_ eklenir:

builder.Configuration.AddEnvironmentVariables(prefix: "CustomPrefix_");

Ön eki, yapılandırma anahtar-değer çiftleri okunduğunda çıkarılır.

Başlatma ayarları ortam değişkeni ayarlarını geçersiz kılar

launchSettings.json içinde ayarlanan ortam değişkenleri, sistem ortamında ayarlanmış olanları geçersiz kılar. Örneğin, ASP.NET Core web şablonları, uç nokta yapılandırmasını şu şekilde ayarlayan bir launchSettings.json dosyası oluşturur:

"applicationUrl": "https://localhost:5001;http://localhost:5000"

applicationUrl öğesinin yapılandırılması, ASPNETCORE_URLS ortam değişkenini ayarlar ve ortamda ayarlanan değerleri geçersiz kılar.

Linux üzerinde çıkış ortam değişkenleri

Linux'ta, systemd öğesinin ayrıştırabilmesi için URL ortam değişkenlerinin değerinden çıkış yapılmalıdır. Aşağıdaki örnekte, Linux aracı systemd-escapehttp:--localhost:5001'den http://localhost:5001 elde etmek için kullanılır.

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Azure App Service uygulama ayarları (ortam değişkenleri)

Azure App Service uygulama ayarları (ortam değişkeni) kılavuzu için aşağıdaki kaynaklara bakın:

• App Service uygulamasını yapılandırma (Azure belgeleri)
• Azure veritabanı bağlantı dizesi ön ekleri

Bağlantı dizesi ön ekleri

Yapılandırma API’si, dört bağlantı dizesi ortam değişkeni için özel işleme kurallarına sahiptir. Bu bağlantı dizeleri, uygulama ortamı için Azure bağlantı dizelerinin yapılandırılmasında yer alır. Aşağıdaki tabloda gösterilen ön eklere sahip ortam değişkenleri, için ön ek sağlanmadığında veya AddEnvironmentVariables uygulamaya yüklenir.

Bağlantı dizesi ön eki	Provider
CUSTOMCONNSTR_	Özel sağlayıcı
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Azure SQL Veritabanı
SQLCONNSTR_	SQL Server

Bir ortam değişkeni bulunduğunda ve yukarıdaki tabloda gösterilen dört ön ekin herhangi biriyle yapılandırmaya yüklendiğinde:

• Yapılandırma anahtarı, ortam değişkeni öneki kaldırılarak ve bir yapılandırma anahtarı bölümü (ConnectionStrings) eklenerek oluşturulur.
• Belirtilen sağlayıcıya sahip olmayan veritabanı CUSTOMCONNSTR_bağlantı sağlayıcısını temsil eden yeni bir yapılandırma anahtar-değer çifti oluşturulur.

Ortam değişkeni anahtarı	Dönüştürülmüş yapılandırma anahtarı	Sağlayıcı yapılandırması girdisi
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	Yapılandırma girdisi oluşturulmadı.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Anahtar: ConnectionStrings:{KEY}_ProviderName: Değer: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Anahtar: ConnectionStrings:{KEY}_ProviderName: Değer: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Anahtar: ConnectionStrings:{KEY}_ProviderName: Değer: System.Data.SqlClient

Command-line

Varsayılan yapılandırma kaynaklarını kullanarak, CommandLineConfigurationProvider yapılandırmayı, aşağıdaki yapılandırma kaynaklarından sonra komut satırı anahtar-değer çiftleri aracılığıyla yükler:

• appsettings.json ve appsettings.{ENVIRONMENT}.json dosyaları.
• Ortamda uygulama sırlarıDevelopment.
• Ortam değişkenleri.

Varsayılan olarak, komut satırında ayarlanan yapılandırma değerleri diğer tüm yapılandırma sağlayıcıları tarafından ayarlanan yapılandırma değerlerini geçersiz kılar.

Komut satırı bağımsız değişkenleri

Aşağıdaki dotnet run komut, eşittir işaretlerini (=) kullanarak anahtarları ve değerleri ayarlar:

dotnet run ConnectionStrings:DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;" Logging:LogLevel:Default=Information

Aşağıdaki komut, eğik çizgi (/) kullanarak anahtarları ve değerleri ayarlar:

dotnet run /ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" /Logging:LogLevel:Default Information

Aşağıdaki komut, anahtarları ve değerleri çift tire (--) kullanarak ayarlar:

dotnet run --ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" --Logging:LogLevel:Default Information

Argüman kullanım kuralları:

• Anahtar değeri eşittir işareti (=) ile takip edilmelidir veya değer bir boşluktan sonra geliyorsa, anahtarın çift tire (--) veya eğik çizgi (/) ön-eklerinden biriyle başlaması gerekir.
• Eşittir işaretinden (=) sonra değer atanmaması, yapılandırma ayarı için boş bir dize atanmasıyla sonuçlanıyor. Örneğin, belirtmek ConnectionStrings:DefaultConnection= geçerlidir ve varsayılan bağlantı dizesine boş bir dize atamayla sonuçlanır.
• Aynı komut içinde, eşittir işaretiyle (=) ayrılmış anahtar-değer çiftlerini boşlukla ayrılmış anahtar-değer çiftleriyle karıştırmayın.

Eşlemeleri değiştirme

Anahtar eşlemeleri, yönteme geçirilen anahtar değiştirmeleri sözlüğü aracılığıyla anahtar adı değiştirme mantığına AddCommandLine izin verir.

Anahtar eşleme sözlüğü kullanıldığında, sözlük, bir komut satırı bağımsız değişkeni tarafından sağlanan anahtarla eşleşen bir anahtar için kontrol edilir. Komut satırı anahtarı sözlükte bulunursa, anahtar-değer çiftini uygulamanın yapılandırmasına ayarlamak için sözlük değeri geri gönderilir. Tek kısa çizgi (-) ile başlayan herhangi bir komut satırı anahtarı için anahtar eşleştirmesi gereklidir.

Anahtar eşlemeleri sözlüğü anahtar kurallarını değiştir:

• Anahtarlar tek tire () veya çift tire (---) ile başlamalıdır.
• Anahtar eşlemeleri sözlüğü, yinelenen anahtarlar içermemelidir.

Aşağıdaki örnekte, bir anahtar eşleme sözlüğü (switchMappings) uygulamanın AddCommandLine dosyasına (Program) aktarılır:

var switchMappings = 
    new Dictionary<string, string>(){ { "-k1", "key1" }, { "-k2", "key2" } };

builder.Configuration.AddCommandLine(args, switchMappings);

Aşağıdaki dotnet run komutlar, anahtar değişimini gösterir (value1'in key1'ye ve value2'ün key2'e).

• dotnet run -k1 value1 -k2 value2
• dotnet run --k1=value1 --k2=value2
• dotnet run --k1 value1 --k2 value2
• dotnet run /k1=value1 /k2=value2
• dotnet run /k1 value1 /k2 value2

Anahtar eşlemelerini kullanan uygulamalar için, CreateDefaultBuilder öğesine yapılan çağrı bağımsız değişkenleri iletmemelidir. CreateDefaultBuilder yönteminin AddCommandLine çağrısı, eşlenmiş anahtarları içermez ve anahtar eşleme sözlüğünü CreateDefaultBuilder öğesine geçirmenin bir yolu yoktur. Çözüm, bağımsız değişkenleri CreateDefaultBuilder öğesine iletmek değil, bunun yerine ConfigurationBuilder yönteminin AddCommandLine yönteminin hem bağımsız değişkenleri hem de anahtar eşleme sözlüğünü işlemesine izin vermektir.

Visual Studio ile ortam ve komut satırı parametrelerini ayarlama

Visual Studio'da ortam ve komut satırı bağımsız değişkenleri, başlatma profilleri penceresinden ayarlanabilir.

• Çözüm Gezgini'nde projeye sağ tıklayın ve Özellikler paneli öğesini seçin.
• Hata Ayıklama > Genel sekmesini seçin ve Hata ayıklama başlatma profilleri kullanıcı arabirimini aç'ı seçin.

Dosya Yapılandırma Sağlayıcısı

FileConfigurationProvider dosya sisteminden yapılandırma yüklemek için temel sınıftır. Aşağıdaki yapılandırma sağlayıcıları FileConfigurationProvider öğesinden türemiştir:

• INI Yapılandırma Sağlayıcısı
• JSON Yapılandırma Sağlayıcısı
• XML Yapılandırma Sağlayıcısı

INI Yapılandırma Sağlayıcısı

INI IniConfigurationProvider dosya anahtarı-değer çiftlerinden yapılandırmayı yükler. Aşağıdaki örnekte sağlayıcının nasıl kullanılacağı gösterilmektedir. Aşırı yüklemeler, dosyanın isteğe bağlı olup olmadığını ve dosya değiştiğinde yapılandırmanın yeniden yüklenip yüklenmediğini belirtebilir.

IniConfig.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;"

[Logging:LogLevel]
Default=Debug
Microsoft=Debug

IniConfig.Production.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLProd;"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

çağırarak AddIniFileyapılandırmayı yükleyin. Aşağıdaki örnek, önceki dosyaların her biri için bir yapılandırma kaynağı oluşturur. Ortam dışı dosya, dosya değiştirilirse yapılandırmayı yeniden yükler (reloadOnChange parametre, varsayılan: false). Dosyanın ortam sürümü, dosyanın isteğe bağlı olduğunu belirtir (optional parametre, varsayılan: false). Dosyanın değiştirildiğinde yeniden yüklenmesini ()reloadOnChange: true belirtmek istiyorsanız, dosyanın isteğe bağlıoptional () olup olmadığını da belirtmeniz gerekir.

builder.Configuration
    .AddIniFile("IniConfig.ini", optional: false, reloadOnChange: true);
    .AddIniFile($"IniConfig.{builder.Environment.EnvironmentName}.ini", optional: true);

JSON Yapılandırma Sağlayıcısı

JSON JsonConfigurationProvider dosya anahtar-değer çiftlerinden yapılandırmayı yükler. Aşağıdaki örnekte sağlayıcının nasıl kullanılacağı gösterilmektedir. Aşırı yüklemeler, dosyanın isteğe bağlı olup olmadığını ve dosya değiştiğinde yapılandırmanın yeniden yüklenip yüklenmediğini belirtebilir.

Dosya yolunu (veya dosya uygulamanın kökündeyse dosya adını) AddJsonFile ile çağırın. Aşağıdaki, dosyayı isteğe bağlı (optional parametre, varsayılan: false) yapar ve dosya değiştirilirse yapılandırmanın yeniden yüklendiğini belirtir (reloadOnChange parametre, varsayılan: false). Dosyanın değiştirildiğinde yeniden yüklenmesini ()reloadOnChange: true belirtmek istiyorsanız, dosyanın isteğe bağlıoptional () olup olmadığını da belirtmeniz gerekir.

builder.Configuration.AddJsonFile("config.json", optional: true, reloadOnChange: true);

XML Yapılandırma Sağlayıcısı

XML XmlConfigurationProvider dosyası anahtar-değer çiftlerinden yapılandırmayı yükler. Aşağıdaki örnekte sağlayıcının nasıl kullanılacağı gösterilmektedir. Aşırı yüklemeler, dosyanın isteğe bağlı olup olmadığını ve dosya değiştiğinde yapılandırmanın yeniden yüklenip yüklenmediğini belirtebilir.

XmlFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnection>Data Source=LocalSqlServer\\MSSQLDev;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Debug</Default>
      <Microsoft>Debug</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

XmlFile.Production.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnectionString>Data Source=LocalSqlServer\\MSSQLProd;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

çağırarak AddXmlFileyapılandırmayı yükleyin. Aşağıdaki örnek, önceki dosyaların her biri için bir yapılandırma kaynağı oluşturur. Ortam dışı dosya, dosya değiştirilirse yapılandırmayı yeniden yükler (reloadOnChange parametre, varsayılan: false). Dosyanın ortam sürümü, dosyanın isteğe bağlı olduğunu belirtir (optional parametre, varsayılan: false). Dosyanın değiştirildiğinde yeniden yüklenmesini ()reloadOnChange: true belirtmek istiyorsanız, dosyanın isteğe bağlıoptional () olup olmadığını da belirtmeniz gerekir.

builder.Configuration
    .AddXmlFile("XmlFile.xml", optional: false, reloadOnChange: true);
    .AddXmlFile($"XmlFile.{builder.Environment.EnvironmentName}.xml", optional: true);

Öğeleri ayırt etmek için name özelliği kullanılıyorsa, aynı öğe adını kullanan yinelenen öğeler işe yarar:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

var value_00 = Config["section:section0:key:key0"];
var value_01 = Config["section:section0:key:key1"];
var value_10 = Config["section:section1:key:key0"];
var value_11 = Config["section:section1:key:key1"];

Değer sağlayan öznitelikler desteklenir:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

Önceki yapılandırma value ile aşağıdaki anahtarları yükler.

• key:attribute
• section:key:attribute

Dosya Bazında Anahtar Yapılandırma Sağlayıcısı

KeyPerFileConfigurationProvider, bir dizinin dosyalarını yapılandırma anahtar-değer çiftleri olarak kullanır. Anahtar, dosya adıdır. Değer, dosyanın içeriğini içerir. Anahtar-Per-File Yapılandırma Sağlayıcısı Docker barındırma senaryolarında kullanılır.

Dosya başına anahtar yapılandırmasını etkinleştirmek için bir AddKeyPerFile örneğinde ConfigurationBuilder genişletme yöntemini çağırın. Dosyalar için directoryPath mutlak bir yol olmalıdır.

Aşırı yükler şunları belirtmeye izin verir:

• Kaynağı yapılandıran bir Action<KeyPerFileConfigurationSource> delege.
• Dizinin isteğe bağlı olup olmadığı ve dizin yolu.

Çift alt çizgi (__), dosya adlarında yapılandırma anahtarı sınırlayıcı olarak kullanılır. Örneğin, Logging__LogLevel__System dosya adı, Logging:LogLevel:System yapılandırma anahtarını üretir.

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
builder.Configuration.AddKeyPerFile(directoryPath: path, optional: true);

Bellek Yapılandırma Sağlayıcısı

MemoryConfigurationProvider, yapılandırma anahtar-değer çiftleri olarak bellek içi bir koleksiyon kullanır.

Aşağıdaki kod, yapılandırma sistemine bir bellek koleksiyonu ekler:

var configSettings = new Dictionary<string, string>
{
    { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
    { "Logging:LogLevel:Default", "Information" }
};

builder.Configuration.AddInMemoryCollection(configSettings);

Kestrel uç nokta yapılandırması

Kestrel-specific uç nokta yapılandırması, tüm sunucular arası uç nokta yapılandırmalarını geçersiz kılar. Sunucular arası uç nokta yapılandırmaları şunları içerir:

• UseUrls.
• --urls komut satırında.
• Ortam ASPNETCORE_URLSdeğişkeni.

Bir Kestrel dosyada aşağıdaki appsettings.json yapılandırma bölümünü göz önünde bulundurun:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://localhost:9999"
    }
  }
},

Uygulama komut satırında ve aşağıdaki sunucular arası uç nokta yapılandırmasıyla dotnet run başlatılır:

dotnet run --urls="https://localhost:7777"

Kestrel, Kestrel dosyasında appsettings.json için özel olarak yapılandırılmış uç noktaya bağlanır ve komutuna https://localhost:9999 geçirilecek dotnet run sunucular arası uç nokta yapılandırmasına değil (https://localhost:7777).

Ancak, Kestrel-spesifik bir uç noktayı ortam değişkeni olarak yapılandırılmış şekilde dikkate alın.

• Anahtar: Kestrel__Endpoints__Https__Url
• Değer: https://localhost:8888

Önceki ortam değişkeninde "Https", Kestrel-'ye özgü uç noktasının adıdır. Yukarıdaki uygulama ayarları yapılandırması, Kestrel için Https adlı belirli bir uç noktasını da tanımlar. Varsayılan konak yapılandırma sağlayıcılarına göre, sonrasında appsettings.{ENVIRONMENT}.json tarafından ortam değişkenleri okunur. Bu nedenle, önceki ortam değişkeni (Kestrel__Endpoints__Https__Url) uç nokta için Https kullanılır.

Tür dönüştürme (GetValue) ile yapılandırmadan tek bir değer ayıklama

ConfigurationBinder.GetValue belirtilen bir anahtarla yapılandırmadan tek bir değer alır ve onu belirtilen türe dönüştürür:

var number = Config.GetValue<int>("NumberKey", 99);

Önceki kodda:

• Config enjekte edilen IConfiguration.
• Yapılandırmada bulunamazsa NumberKey varsayılan değeri 99 kullanılır.

Bölümler ile çalışma, bölümün alt öğelerini alma ve bir bölümün var olup olmadığını belirleme

Aşağıdaki örnekler için aşağıdaki subsection.json dosyasını göz önünde bulundurun:

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

subsection.json için AddJsonFile çağrılarak bir yapılandırma sağlayıcısı eklenir.

GetSection

IConfiguration.GetSection belirtilen alt bölüm anahtarıyla bir yapılandırma alt bölümü döndürür.

Aşağıdaki kod, section1 bir Config olarak eklendiğinde, IConfiguration değerlerini döndürür:

var subsection = Config.GetSection("section1");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

Aşağıdaki kod, section2:subsection0 bir Config olarak eklendiğinde, IConfiguration değerlerini döndürür:

var subsection = Config.GetSection("section2:subsection0");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

GetSection hiçbir zaman null döndürmez. Eşleşen bir bölüm bulunmazsa, boş bir IConfigurationSection döndürülür.

GetSection eşleşen bir bölüm döndürdüğünde, Value doldurulmaz. Bölüm var olduğunda bir Key ve Path döndürülür.

GetChildren ve Exists

Aşağıdaki kod çağrıları:

• ConfigurationExtensions.Exists öğesinin var olduğunu doğrulamak için section2.
• IConfiguration.GetChildren ve section2 alt bölümleri için değerleri döndürür.

var section = Config.GetSection("section2");

if (!section.Exists())
{
    throw new Exception("section2 doesn't exist!");
}

var children = section.GetChildren();

foreach (var subSection in children)
{
    int i = 0;
    var key1 = subSection.Key + ":key" + i++.ToString();
    var key2 = subSection.Key + ":key" + i.ToString();
    Console.WriteLine($"{key1} value: {section[key1]}");
    Console.WriteLine($"{key2} value: {section[key2]}");
}

Çıktı:

subsection0:key0 value: value200
subsection0:key1 value: value201
subsection1:key0 value: value210
subsection1:key1 value: value211

Diziyi bağlama

ConfigurationBinder.Bind, yapılandırma anahtarlarında dizi dizinlerini kullanarak dizileri nesnelere bağlamayı destekler. Sayısal bir anahtar segmenti ortaya çıkaran herhangi bir dizi formatı, bir POCO sınıfı dizisine dizi bağlama yeteneğine sahiptir.

array.json:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

array.json için AddJsonFile çağrılarak bir yapılandırma sağlayıcısı eklenir.

Aşağıdaki kod yapılandırma değerlerini okur.

ArrayExample.cs:

public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

var array = Config.GetSection("array").Get<ArrayExample>();

if (array is null)
{
    throw new ArgumentNullException(nameof(array));
}

for (int j = 0; j < array.Entries?.Length; j++)
{
    Console.WriteLine($"Index: {j} Value: {array.Entries[j]}");
}

Çıktı:

Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value40
Index: 4 Value: value50

Önceki çıktıda, Dizin 3, value40 içindeki "4": "value40", öğesine karşılık gelen array.json değerine sahiptir. Bağlı dizi dizinleri süreklidir ve yapılandırma anahtarı dizinine bağlı değildir. Yapılandırma bağlayıcısı, değerleri bağlama null veya ilişkili nesnelerde girdi oluşturma null özelliğine sahip değildir.

Dizin 3 için eksik yapılandırma öğesi, Dizin 3 anahtarı/değer çiftini ArrayExample okuyan herhangi bir yapılandırma sağlayıcısı tarafından örneğe bağlanmadan önce sağlanabilir. Aşağıdaki örnekte, önceki örnekte tarafından array.json sağlanan değerlerin bellek içi bir koleksiyon tarafından sağlandığını varsayalım. Örnekte, koleksiyon bağlanmadan önce JSON Yapılandırma Sağlayıcısı'ndan Dizin 3 değerinin nasıl yüklenecekleri gösterilmektedir.

value3.json:

{
  "array:entries:3": "value30"
}

var configSettings = new Dictionary<string, string>
{
    { "array:entries:0", "value00" },
    { "array:entries:1", "value10" },
    { "array:entries:2", "value20" },
    { "array:entries:4", "value40" },
    { "array:entries:5", "value50" }
};

builder.Configuration.AddInMemoryCollection(configSettings);
builder.Configuration.AddJsonFile("value3.json", optional: false, 
    reloadOnChange: false);

Yukarıdaki kod aşağıdaki ilişkili diziyle sonuç verir:

Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value30
Index: 4 Value: value40
Index: 5 Value: value50

Özel yapılandırma sağlayıcı

Örnek uygulama, Entity Framework (EF) kullanarak bir veritabanından yapılandırma anahtar-değer çiftlerini okuyan temel bir yapılandırma sağlayıcısının nasıl oluşturulacağını gösterir.

Sağlayıcı, aşağıdaki özelliklere sahiptir:

• EF bellek içi veritabanı, gösterim amacıyla kullanılır. Bağlantı dizesi gerektiren bir veritabanı kullanmak için, bağlantı dizesini başka bir yapılandırma sağlayıcısından sağlamak üzere ikincil bir ConfigurationBuilder uygulayın.
• Sağlayıcı, başlangıçta bir veritabanı tablosunu yapılandırmaya yükler. Sağlayıcı, veritabanını anahtar başına bazında sorgulamaz.
• Değişiklikte yeniden yükleme uygulanmaz, bu nedenle uygulama başladıktan sonra veritabanını güncellemek uygulamanın yapılandırması üzerinde etkisi olmaz.

Veritabanında yapılandırma değerlerini depolamak için bir EFConfigurationValue varlığı tanımlayın.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; } = string.Empty;
    public string Value { get; set; } = string.Empty;
}

Yapılandırılan değerleri depolamak ve bunlara erişmek için bir EFConfigurationContext ekleyin.

EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(
        DbContextOptions<EFConfigurationContext> options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}

IConfigurationSource uygulayan bir sınıf oluşturun.

EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => 
        _optionsAction = optionsAction;

    public IConfigurationProvider Build(IConfigurationBuilder builder) => 
        new EFConfigurationProvider(_optionsAction);
}

ConfigurationProvider öğesinden devralarak özel yapılandırma sağlayıcısını oluşturun. Yapılandırma sağlayıcısı, boş olduğunda veritabanını başlatır. Yapılandırma anahtarları büyük/küçük harfe duyarlı olmadığından, veritabanını başlatmak için kullanılan sözlük büyük/küçük harfe duyarlı olmayan karşılaştırıcı StringComparer.OrdinalIgnoreCaseile oluşturulur.

EFConfigurationProvider/EFConfigurationProvider.cs:

using Microsoft.EntityFrameworkCore;

public class EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction) : ConfigurationProvider
{
    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        optionsAction(builder);

        using var dbContext = new EFConfigurationContext(builder.Options);

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Database.EnsureCreated();

        Data = !dbContext.Values.Any()
            ? CreateAndSaveDefaultValues(dbContext)
            : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
    }

    private static Dictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity-2005
        var configValues =
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue
            {
                Id = kvp.Key,
                Value = kvp.Value
            })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Bir AddEFConfiguration genişletme yöntemi, bir ConfigurationBuilder öğesine yapılandırma kaynağı eklemeye izin verir.

Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder,
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Aşağıdaki kod, uygulamanın EFConfigurationProvider dosyasındaki özel Program öğesinin nasıl kullanılacağını gösterir:

builder.Configuration.AddEFConfiguration(
    opt => opt.UseInMemoryDatabase("InMemoryDb"));

Başlangıç kolaylık yöntemlerini kullanarak yapılandırmaya erişmenin bir örneği için, bkz. Uygulama başlatma: Kolaylık yöntemleri.

Bir dış derlemeden yapılandırma ekleme

Bir IHostingStartup uygulaması, uygulamanın Startup sınıfı dışındaki bir dış derlemeden başlangıçta bir uygulamaya geliştirmeler eklemeye izin verir. Daha fazla bilgi için, bkz. ASP.NET Core'da barındırma başlangıç derlemelerini kullanma.

Yapılandırma bağlı kaynak üreteci

Bağlama kaynakları üreten yapılandırma oluşturucu, AOT ve kırpma uyumlu yapılandırma sağlar. Daha fazla bilgi için Yapılandırma bağlama kaynak oluşturucu bölümüne bakın.

Ek kaynaklar

• ASP.NET Core Blazor yapılandırma
• Yapılandırma kaynak kodu
• Örnek kodu görüntüleme veya indirme (indirme)
• ASP.NET Core'da seçenek deseni