ASP.NET Core’de Yapılandırma

Yayımlayanlar Rick Anderson ve Kirk Larkin

ASP.NET Core'daki uygulama yapılandırması, bir veya daha fazla yapılandırma sağlayıcı 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
• Ortam değişkenleri
• Azure Key Vault
• Azure Uygulama Yapılandırması
• Komut satırı bağımsız değişkenleri
• Yüklenen veya oluşturulan özel sağlayıcılar
• Dizin dosyaları
• Bellek içi .NET nesneleri

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

Blazor Bu düğümdeki yönergeleri ekleyen veya yerine geçen yapılandırma kılavuzu için bkz. ASP.NET Çekirdek Blazor yapılandırması.

Uygulama ve Ana Bilgisayar Yapılandırma

ASP.NET Core uygulamaları bir ana bilgisayar yapılandırır ve başlatır. Ana bilgisayar, uygulamanın başlatılmasından ve ömür boyu yönetiminden sorumludur. ASP.NET Core şablonları, konağı içeren bir WebApplicationBuilder oluşturur. Hem ana bilgisayar hem de uygulama yapılandırma sağlayıcılarında bazı yapılandırmalar yapılabilirken,ana bilgisayar yapılandırmasında genellikle yalnızca ana bilgisayar için gerekli olan yapılandırma yapılmalıdır.

Uygulama yapılandırması en yüksek önceliktir ve sonraki bölümde detaylandırılmıştır. Ana bilgisayar yapılandırma uygulama yapılandırmasını izler ve bu makalede açıklanmıştır.

Varsayılan uygulama yapılandırma kaynakları

dotnet new veya Visual Studio ile oluşturulan ASP.NET Core web uygulamaları aşağıdaki kodu oluşturur:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder önceden yapılandırılmış varsayılanlarla WebApplicationBuilder sınıfının yeni bir örneğini başlatır. Başlatılan WebApplicationBuilder (builder) uygulama için en yüksekten en düşük önceliğe doğru aşağıdaki sırayla varsayılan yapılandırma sağlar:

1. Komut satırı yapılandırma sağlayıcısını kullanan komut satırı bağımsız değişkenleri.
2. Ön eki olmayan ortam değişkenleri yapılandırma sağlayıcısını kullanan ön eki olmayan ortam değişkenleri.
3. Uygulama Development ortamında çalıştığında kullanıcı gizli dizileri.
4. appsettings.{Environment}.jsonJSON yapılandırma sağlayıcısını kullanarak. Örneğin, appsettings.Production.json ve appsettings.Development.json.
5. JSON yapılandırma sağlayıcısını kullanarak appsettings.json.
6. Bir sonraki bölümde açıklanan ana bilgisayar yapılandırmasına geri dönüş.

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

Aşağıdaki liste için WebApplicationBuilderen yüksekten en düşük önceliğe kadar varsayılan konak yapılandırma kaynaklarını içerir:

1. Komut satırı yapılandırma sağlayıcısını kullanan komut satırı bağımsız değişkenleri
2. DOTNET_-ön eki olan, Ortamı değişkenleri yapılandırma sağlayıcısını kullanan ortam değişkenleri.
3. ASPNETCORE_-ön eki olan, Ortamı değişkenleri yapılandırma sağlayıcısını kullanan ortam değişkenleri.

.NET Genel Konağı ve Web Konağı için, en yüksekten en düşük önceliğe kadar varsayılan konak yapılandırma kaynakları:

1. ASPNETCORE_-ön eki olan, Ortamı değişkenleri yapılandırma sağlayıcısını kullanan ortam değişkenleri.
2. Komut satırı yapılandırma sağlayıcısını kullanan komut satırı bağımsız değişkenleri
3. DOTNET_-ön eki olan, Ortamı değişkenleri yapılandırma sağlayıcısını kullanan ortam değişkenleri.

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

Ana bilgisayar değişkenleri

Aşağıdaki değişkenler, ana bilgisayar oluşturucular başlatılırken erken kilitlenir ve uygulama yapılandırmasından etkilenemez:

• Uygulama adı
• Ortam adı, örneğin Development, Productionve Staging
• İçerik kökü
• Web kökü
• Barındırma başlangıç derlemelerinin taranıp taranmayacağı ve hangi derlemelerin taranacağı.
• IHostBuilder.ConfigureAppConfiguration geri çağırmalarında HostBuilderContext.Configuration'dan uygulama ve kitaplık kodu tarafından okunan değişkenler.

Diğer tüm ana bilgisayar ayarları, ana bilgisayar yapılandırması yerine uygulama yapılandırmasından okunur.

URLS, önyükleme ayarı olmayan birçok yaygın ana bilgisayar ayarlarından biridir. Önceki listede olmayan diğer tüm ana bilgisayar ayarları gibi, URLS daha sonra uygulama yapılandırmasından okunur. Ana bilgisayar yapılandırması, uygulama yapılandırması için bir geri dönüş olduğundan, ana bilgisayar yapılandırması URLS ayarlamak için kullanılabilir, ancak uygulama yapılandırmasında appsettings.json gibi herhangi bir yapılandırma kaynağı tarafından geçersiz kılınır.

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

Bu makalenin geri kalan bölümleri uygulama yapılandırmasına ilişkindir.

Uygulama yapılandırması sağlayıcıları

Aşağıdaki kod, etkinleştirilen yapılandırma sağlayıcılarını eklendikleri sırayla görüntüler:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

Yukarıdaki en yüksekten en düşüğe öncelikli varsayılan yapılandırma kaynaklarının listesi, sağlayıcıları şablonla oluşturulan uygulamaya eklendikleri tersi sırada gösterir. Örneğin, JSON yapılandırma sağlayıcısı Komut satırı yapılandırma sağlayıcısından önce eklenir.

Daha sonra eklenen yapılandırma sağlayıcıları daha yüksek önceliğe sahiptir ve önceki temel ayarları geçersiz kılar. Örneğin, MyKey hem appsettings.json içinde hem de ortamda ayarlandıysa, ortam değeri kullanılır. Komut satırı yapılandırma sağlayıcı, varsayılan yapılandırma sağlayıcılarını kullanarak diğer tüm sağlayıcıları geçersiz kılar.

CreateBuilder hakkında daha fazla bilgi için, bkz. Varsayılan oluşturucu ayarları.

appsettings.json

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

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Örnek indirmedeki aşağıdaki kod, önceki yapılandırma ayarlarından birkaçını görüntüler:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

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

1. appsettings.json
2. appsettings.{Environment}.json : Örneğin, appsettings.Production.json ve appsettings.Development.json dosyaları. Dosyanın ortam sürümü IHostingEnvironment.EnvironmentName ortamına göre yüklenir. Daha fazla bilgi için, bkz. ASP.NET Core'da birden çok ortam kullanma.

appsettings.{Environment}.json değerleri appsettings.json içindeki anahtarları geçersiz kılar. Örneğin, varsayılan olarak:

• Geliştirme aşamasında appsettings.Development.json yapılandırması appsettings.jsoniçinde bulunan değerlerin üzerine yazar.
• Üretim aşamasında appsettings.Production.json yapılandırması appsettings.jsoniçinde bulunan değerlerin üzerine yazar. Örneğin, uygulamayı Azure'a dağıtırken.

Bir yapılandırma değerinin garanti edilmesi gerekiyorsa, bkz. GetValue. Önceki örnek yalnızca dizeleri okur ve varsayılan bir değeri desteklemez.

Varsayılan yapılandırma kullanılırken, appsettings.json ve appsettings.{Environment}.json dosyaları reloadOnChange: true ile etkinleştirilir. Uygulama başlatıldıktan sonra ve appsettings.{Environment}.json dosyasında yapılan appsettings.json değişiklikler JSON yapılandırma sağlayıcısı tarafından okunur.

appsettings.json açıklamaları

ve dosyalarındaki appsettings.json açıklamalar JavaScript veya C# stili açıklamalar kullanılarak appsettings.{Environment}.json desteklenir.

Seçenekler desenini kullanarak hiyerarşik yapılandırma verilerini bağlayın

İlgili yapılandırma değerlerini okumanın tercih edilen yolu seçenekler desenini kullanmaktır. Örneğin, aşağıdaki yapılandırma değerlerini okumak için:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Aşağıdaki PositionOptions sınıflarını oluşturun:

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; } = String.Empty;
    public string Name { get; set; } = String.Empty;
}

Bir seçenekler sınıfı:

• Genel bir parametresiz oluşturucu ile soyut olmamalıdır.
• Türün tüm genel okuma-yazma özellikleri bağlıdır.
• Alanlar bağlı değildir. Önceki örnekte, Position bağlı değildir. Position alanı kullanıldığından, "Position" öğesinin, sınıfı bir yapılandırma sağlayıcısına bağlarken uygulamada sabit kodlanmış olması gerekmez.

Aşağıdaki kod:

• PositionOptions sınıfını, Position bölümüne bağlamak için ConfigurationBinder.Bind çağırır.
• Position yapılandırma verisini görüntüler.

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

    public Test22Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Yukarıdaki kodda varsayılan olarak, uygulama başlatıldıktan sonra JSON yapılandırma dosyasında yapılan değişiklikler okunur.

ConfigurationBinder.Get<T> belirtilen türü bağlar ve döndürür. ConfigurationBinder.Get<T>, ConfigurationBinder.Bind kullanmaktan daha uygun olabilir. Aşağıdaki kod ConfigurationBinder.Get<T> öğesinin, PositionOptions sınıfıyla nasıl kullanılacağını göstermektedir:

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions? positionOptions { get; private set; }

    public Test21Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Yukarıdaki kodda varsayılan olarak, uygulama başlatıldıktan sonra JSON yapılandırma dosyasında yapılan değişiklikler okunur.

Seçenekler desenini kullanırken alternatif bir yaklaşım, Position bölümünü bağlamak ve bunu bağımlılık ekleme hizmet kapsayıcısına eklemektir. Aşağıdaki kodda PositionOptions, Configure ile hizmet kapsayıcıya eklenmiş ve yapılandırmaya bağlanmıştır:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));

var app = builder.Build();

Aşağıdaki kod, önceki kodu kullanarak, konum seçeneklerini okur:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

Yukarıdaki kodda, uygulama başlatıldıktan sonra JSON yapılandırma dosyasında yapılan değişiklikler okunmuyor . Uygulama başladıktan sonra değişiklikleri okumak için IOptionsSnapshot kullanın.

Varsayılan yapılandırma kullanılırken, appsettings.json ve appsettings.{Environment}.json dosyaları reloadOnChange: true ile etkinleştirilir. Uygulama başlatıldıktan sonra ve appsettings.{Environment}.json dosyasında yapılan appsettings.json değişiklikler JSON yapılandırma sağlayıcısı tarafından okunur.

Ek JSON yapılandırma dosyaları ekleme hakkında bilgi için bu belgedeki JSON yapılandırma sağlayıcısına bakın.

Hizmet koleksiyonunu birleştirme

Hizmetleri kaydeden ve seçenekleri yapılandıran aşağıdakileri göz önünde bulundurun:

using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
    builder.Configuration.GetSection(ColorOptions.Color));

builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();

var app = builder.Build();

İlgili kayıt grupları, hizmetleri kaydetmek için bir uzantı yöntemine taşınabilir. Örneğin, yapılandırma hizmetleri aşağıdaki sınıfa eklenir:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }

        public static IServiceCollection AddMyDependencyGroup(
             this IServiceCollection services)
        {
            services.AddScoped<IMyDependency, MyDependency>();
            services.AddScoped<IMyDependency2, MyDependency2>();

            return services;
        }
    }
}

Kalan hizmetler benzer bir sınıfta kayıtlıdır. Aşağıdaki kod, hizmetleri kaydetmek için yeni genişletme yöntemlerini kullanır:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddConfig(builder.Configuration)
    .AddMyDependencyGroup();

builder.Services.AddRazorPages();

var app = builder.Build();

Not: Her services.Add{GROUP_NAME} genişletme yöntemi hizmetleri ekler ve potansiyel olarak yapılandırır. Örneğin, AddControllersWithViews görünümleri olan MVC denetleyicilerinin gerektirdiği hizmetleri ekler ve AddRazorPages, Razor Sayfalarının gerektirdiği hizmetleri ekler.

Güvenlik ve kullanıcı gizli dizileri

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 Dizi Yöneticisi aracı geliştirmede gizli dizilerini depolamak için kullanılabilir.
• Üretim gizli dizilerini 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ı.

Varsayılan olarak, kullanıcı gizli dizileri yapılandırma kaynağı 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'da birden çok ortam kullanma
• 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ı.

Ön eki olmayan ortam değişkenleri

Ön ekli olmayan ortam değişkenleri, ASPNETCORE_ veya DOTNET_ ile ön ekli olanlar dışındaki ortam değişkenleridir. Ön ekli olmayan ortam değişkenleri, "ASPNETCORE_ENVIRONMENT": "Development" veya launchSettings.json ile ön ekli olanlar dışındaki ortam değişkenleridir. ASPNETCORE_ ve DOTNET_ ortam değişkenleri hakkında daha fazla bilgi için, bkz.:

• Ön eki olmayan, ASPNETCORE_ ön ekli ve DOTNETCORE_ ön ekli ortam değişkenlerini içeren en yüksekten en düşüğe öncelikli varsayılan yapılandırma kaynaklarının listesi.
• Microsoft.Extensions.Hosting dışında kullanılanDOTNET_ ortamı değişkenleri.

Varsayılan yapılandırmayı kullanarak EnvironmentVariablesConfigurationProvider, appsettings.json, appsettings.{Environment}.json ve kullanıcı gizli dizilerini okuduktan sonra ortam değişkeni anahtar-değer çiftlerinden konfigürasyonu 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 olan , __şöyledir:

• Tüm platformlar tarafından desteklenir.
• otomatik olarak iki nokta üst üste ile :değiştirilir.

Aşağıdaki komutlar:

• Windows'ta önceki örneğin ortam anahtarlarını ve değerlerini ayarlayın.
• Örnek indirmeyi kullanırken ayarları test edin. dotnet run komutu proje dizininde çalıştırılmalıdır.

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Önceki ortam ayarları:

• Yalnızca ayarlandıkları komut penceresinden başlatılan işlemlerde ayarlanırlar.
• Visual Studio ile başlatılan tarayıcılar tarafından okunmaz.

Windows'ta ortam anahtarlarını ve değerlerini ayarlamak için aşağıdaki setx komutları kullanılabilir. set öğesinin aksine setx ayarları kalıcıdır. /M değişkeni sistem ortamında ayarlar. /M anahtarı kullanılmazsa, bir kullanıcı ortamı değişkeni ayarlanır.

setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M

Önceki komutların appsettings.json ve appsettings.{Environment}.json öğelerini geçersiz kıldığını test etmek için:

• Visual Studio ile: Çıkın ve Visual Studio'yu yeniden başlatın.
• CLI ile: Yeni bir komut penceresi başlatın ve dotnet run girin.

Ortam değişkenleri için bir önek belirtmek için AddEnvironmentVariables öğesini bir dizeyle çağırın:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Önceki kodda:

• builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_"), varsayılan yapılandırma sağlayıcılarından sonra eklenir. Yapılandırma sağlayıcılarını sıralama örneği için bkz . JSON yapılandırma sağlayıcısı.
• MyCustomPrefix_ Ön eki ile ayarlanan ortam değişkenleri, varsayılan yapılandırma sağlayıcılarını geçersiz kılar. Bu, ön eki olmayan ortam değişkenlerini içerir.

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

Aşağıdaki komutlar özel ön eki test eder:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

Varsayılan yapılandırma, DOTNET_ ve ASPNETCORE_ ile ön eki olan ortam değişkenlerini ve komut satırı bağımsız değişkenlerini yükler. DOTNET_ ve ASPNETCORE_ ön ekleri, ASP.NET Core tarafından ana bilgisayar ve uygulama yapılandırması için kullanılır, ancak kullanıcı yapılandırması için kullanılmaz. Ana bilgisayar ve uygulama yapılandırması hakkında daha fazla bilgi için, bkz. .NET Genel Ana Bilgisayarı.

Azure App Service üzerinde Ayarlar >Yapılandırması sayfasında Yeni uygulama ayarını seçin. Azure App Service uygulama ayarları şunlardır:

• Şifrelenmiş bir kanalda rest şifrelenir ve bu kanal üzerinden iletilir.
• Ortam değişkenleri olarak kullanıma sunulur.

Daha fazla bilgi için, bkz. Azure Apps: Azure Portal'ı kullanarak uygulama yapılandırmasını geçersiz kılma.

Azure veritabanı bağlantı dizeleri hakkında bilgi için Bağlantı dizesi ön eklerine bakın.

Ortam değişkenlerinin adlandırılması

Ortam değişkeni adları, bir appsettings.json dosyasının yapısını yansıtır. Hiyerarşideki her öğe, çift alt çizgi (tercih edilir) veya iki nokta üst üste ile ayrılır. Öğe yapısı bir dizi içerdiğinde, dizi dizini bu yolda ek bir öğe adı olarak ele alınmalıdır. Aşağıdaki appsettings.json dosyasını ve ortam değişkenleri olarak temsil edilen eşdeğer değerlerini göz önünde bulundurun.

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

ortam değişkenleri

setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information

Oluşturulan launchSettings.json'da ayarlanan ortam değişkenleri

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. http:--localhost:5001 öğesini askıya alan systemd-escape linux aracını kullanma

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

Ortam değişkenlerini görüntüleme

Aşağıdaki kod, uygulama başlangıcında ortam değişkenlerini ile değerlerini görüntüler ve bu, ortam ayarlarında hata ayıklarken yardımcı olabilir:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

foreach (var c in builder.Configuration.AsEnumerable())
{
    Console.WriteLine(c.Key + " = " + c.Value);
}

Komut Satırı

Varsayılan yapılandırmayı kullanarak CommandLineConfigurationProvider, yapılandırmayı aşağıdaki yapılandırma kaynaklarından sonra komut satırı bağımsız değişkeni anahtar-değer çiftlerinden yükler:

• appsettings.json ve appsettings.{Environment}.json dosyaları.
• Geliştirme ortamında uygulama gizli dizileri.
• 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ıyla ayarlanan yapılandırma değerlerini geçersiz kılar.

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

Aşağıdaki komut, = kullanarak anahtarları ve değerleri ayarlar:

dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick

Aşağıdaki komut, / kullanarak anahtarları ve değerleri ayarlar:

dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick

Aşağıdaki komut, -- kullanarak anahtarları ve değerleri ayarlar:

dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick

Anahtar değer:

• = öğesini izlemeli veya değer bir boşluktan sonra geldiğinde anahtarın ön eki -- veya / olmalıdır.
• = kullanılırsa gerekli değildir. Örneğin, MySetting=.

Aynı komut içinde, = kullanan komut satırı bağımsız değişkeni anahtar-değer çiftlerini boşluk kullanan anahtar-değer çiftleriyle karıştırmayın.

Anahtar eşlemeleri

Anahtar eşlemeleri anahtar adı değiştirme mantığına izin verir. AddCommandLine yöntemine bir anahtar değiştirme sözlüğü sağlayın.

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 tire (-) ile ön eki olan herhangi bir komut satırı anahtarı için bir anahtar eşlemesi gereklidir.

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

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

Bir anahtar eşleme sözlüğü kullanmak için, onu XAddCommandLine öğesine yapılan çağrıya iletin:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

builder.Configuration.AddCommandLine(args, switchMappings);

var app = builder.Build();

Anahtar değiştirmeyi test etmek için aşağıdaki komutu çalıştırın:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Aşağıdaki kod, değiştirilen anahtarların anahtar değerlerini gösterir:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

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ı bağımsız değişkenlerini ayarlama

Ortam ve komut satırı bağımsız değişkenleri, Visual Studio'da başlatma profilleri iletişim kutusundan ayarlanabilir:

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

Hiyerarşik yapılandırma verileri

Yapılandırma API'si, yapılandırma anahtarlarında bir sınırlayıcı kullanarak hiyerarşik verileri düzleştirerek hiyerarşik yapılandırma verilerini okur.

Örnek indirme, aşağıdaki appsettings.json dosyasını içerir:

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Örnek indirmedeki aşağıdaki kod, yapılandırma ayarlarından birkaçını görüntüler:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Hiyerarşik yapılandırma verilerini okumanın tercih edilen yolu, seçenekler desenini kullanmaktır. Daha fazla bilgi için, bu belgedeki Hiyerarşik yapılandırma verilerini bağlama bölümüne bakın.

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 daha sonra GetSection, GetChildren ve Exists bölümlerinde açıklanmıştır.

Yapılandırma anahtarları ve değerleri

Uyarı

Bu makalede bağlantı dizesi kullanımı gösterilmektedir. Yerel bir veritabanıyla kullanıcının kimliğinin doğrulanması gerekmez, ancak üretimde bağlantı dizesi bazen kimlik doğrulaması için bir parola içerir. Kaynak sahibi parola kimlik bilgileri (ROPC), üretim veritabanları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 bkz . Güvenli kimlik doğrulama akışları.

Yapılandırma anahtarları:

• Büyük/küçük harfe duyarlıdır. Ö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ında 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, tüm platformlarda iki nokta üst üste ayırıcı (:) çalışır.
  • Ortam değişkenlerinde iki nokta üst üste ayırıcısı tüm platformlarda çalışmayabilir. Çift alt çizgi, __, tüm platformlar tarafından desteklenir ve otomatik olarak iki nokta üst üste : öğesine dönüştürülür.
  • Azure Key Vault'ta hiyerarşik anahtarlar, ayırıcı olarak -- öğesini kullanır. Azure Key Vault yapılandırma sağlayıcı, gizli diziler uygulamanın yapılandırmasına yüklendiğinde -- öğesini otomatik olarak : ile değiştirir.
• ConfigurationBinder, yapılandırma anahtarlarında dizi dizinlerini kullanarak dizileri nesnelere bağlamayı destekler. Dizi bağlama, Bir diziyi bir sınıfa 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.

Konfigürasyon 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	Şuradan yapılandırma sağlar
Azure Key Vault yapılandırma sağlayıcısı	Azure Key Vault
Azure Uygulama yapılandırması sağlayıcı	Azure Uygulama Yapılandırması
Komut satırı yapılandırması sağlayıcı	Komut satırı parametreleri
Özel yapılandırma sağlayıcı	Özel kaynak
Ortam Değişkenleri yapılandırma sağlayıcı	Ortam değişkenleri
Dosya yapılandırma sağlayıcı	INI, JSON ve XML dosyaları
Dosya başına anahtar yapılandırma sağlayıcı	Dizin dosyaları
Bellek yapılandırma sağlayıcı	Bellek için koleksiyonlar
Kullanıcı gizli dizileri	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
2. appsettings.{Environment}.json
3. Kullanıcı gizli dizileri
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 ayarlanan yapılandırmayı geçersiz kılmasına izin vermek için Komut satırı yapılandırma sağlayıcısını bir dizi sağlayıcısının sonuna eklemektir.

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

Bağlantı dizesi ön ekleri

Uyarı

Bu makalede bağlantı dizesi kullanımı gösterilmektedir. Yerel bir veritabanıyla kullanıcının kimliğinin doğrulanması gerekmez, ancak üretimde bağlantı dizesi bazen kimlik doğrulaması için bir parola içerir. Kaynak sahibi parola kimlik bilgileri (ROPC), üretim veritabanları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 bkz . Güvenli kimlik doğrulama akışları.

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. Tabloda gösterilen ön eklere sahip ortam değişkenleri, varsayılan yapılandırmayla veya AddEnvironmentVariables öğesine herhangi bir ön ek sağlanmadığında 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 keşfedildiğinde ve tabloda gösterilen dört ön ekten herhangi biriyle konfigürasyona 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.
• Veritabanı bağlantı sağlayıcısını temsil eden yeni bir yapılandırma anahtar-değer çifti oluşturulur (belirtilen bir sağlayıcısı olmayan CUSTOMCONNSTR_ hariç).

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

Dosya yapılandırma sağlayıcı

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ı
• JSON yapılandırma sağlayıcısı
• XML yapılandırma sağlayıcı

INI yapılandırma sağlayıcı

IniConfigurationProvider, çalışma zamanında INI dosyası anahtar-değer çiftlerinden yapılandırmayı yükler.

Aşağıdaki kod birkaç yapılandırma sağlayıcısı ekler:

var builder = WebApplication.CreateBuilder(args);

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

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Önceki kodda, MyIniConfig.ini ve MyIniConfig.{Environment}.ini dosyalarındaki ayarlar aşağıdakiler içindeki ayarlar tarafından geçersiz kılınır:

• Ortam değişkenleri yapılandırma sağlayıcı
• Komut satırı yapılandırması sağlayıcı.

Örnek indirme, aşağıdaki MyIniConfig.ini dosyasını içerir:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Örnek indirmedeki aşağıdaki kod, önceki yapılandırma ayarlarından birkaçını görüntüler:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JSON yapılandırma sağlayıcısı

JSON JsonConfigurationProvider dosya anahtar-değer çiftlerinden yapılandırmayı yükler.

Aşırı yüklemeler şunları belirtebilir:

• Dosya normal mi değil mi.
• Dosya değişirse yapılandırmanın yeniden yüklenip yüklenmeyeceği.

Aşağıdaki kodu inceleyin:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Yukarıdaki kod:

• JSON yapılandırma sağlayıcısını dosyayı yüklemek için MyConfig.json aşağıdaki seçeneklerle yapılandırılır:
  • optional: true: Dosya isteğe bağlıdır.
  • reloadOnChange: true : Değişiklikler kaydedildiğinde dosya yeniden yüklenir.
• Varsayılan yapılandırma sağlayıcılarını, MyConfig.json dosyasından önce okur. MyConfig.json dosyasındaki ayarlar, Ortam değişkenleri yapılandırma sağlayıcı ve Komut satırı yapılandırma sağlayıcı dahil olmak üzere varsayılan yapılandırma sağlayıcılarındaki ayarı geçersiz kılar.

Genellikle Ortam değişkenleri yapılandırma sağlayıcısında ve Komut satırı yapılandırma sağlayıcısında değerleri geçersiz kılmaya yönelik özel bir JSON dosyasının ayarlanmasını istemezsiniz.

XML yapılandırma sağlayıcı

XmlConfigurationProvider, çalışma zamanında XML dosyası anahtar-değer çiftlerinden yapılandırmayı yükler.

Aşağıdaki kod birkaç yapılandırma sağlayıcısı ekler:

var builder = WebApplication.CreateBuilder(args);

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

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Önceki kodda, MyXMLFile.xml ve MyXMLFile.{Environment}.xml dosyalarındaki ayarlar aşağıdakiler içindeki ayarlar tarafından geçersiz kılınır:

• Ortam değişkenleri yapılandırma sağlayıcı
• Komut satırı yapılandırması sağlayıcı.

Örnek indirme, aşağıdaki MyXMLFile.xml dosyasını içerir:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Örnek indirmedeki aşağıdaki kod, önceki yapılandırma ayarlarından birkaçını görüntüler:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

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

Aşağıdaki kod, önceki yapılandırma dosyasını okur, anahtarları ve değerleri görüntüler:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

    public IndexModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

Nitelikler değerleri sağlamak için kullanılabilir:

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

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

• anahtar:öznitelik
• bölüm:anahtar:öznitelik

Dosya başına anahtar yapılandırma sağlayıcı

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. Dosya başına anahtar yapılandırma sağlayıcı, Docker barındırma senaryolarında kullanılır.

Dosya başına anahtar yapılandırmasını etkinleştirmek için bir ConfigurationBuilder örneğinde AddKeyPerFile 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> temsilcisi.
• Dizinin isteğe bağlı olup olmadığı ve dizinin 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.

Uygulamanın yapılandırmasını belirtmek için ana bilgisayarı oluştururken ConfigureAppConfiguration çağırın:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

Bellek yapılandırma sağlayıcı

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 builder = WebApplication.CreateBuilder(args);

var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

builder.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Örnek indirmedeki aşağıdaki kod, önceki yapılandırma ayarlarını görüntüler:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Önceki kodda config.AddInMemoryCollection(Dict), varsayılan yapılandırma sağlayıcılarından sonra eklenir. Yapılandırma sağlayıcılarını sıralama örneği için bkz . JSON yapılandırma sağlayıcısı.

MemoryConfigurationProvider kullanmanın başka bir örneği için Dizi bağlama bölümüne bakın.

Kestrel uç nokta yapılandırması

Kestrel belirli 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:

• UseUrl’leri
• Komut satırında --urls
• Ortam değişkeni ASPNETCORE_URLS

Bir ASP.NET Core web uygulamasında kullanılan aşağıdaki appsettings.json dosyasını göz önünde bulundurun:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
} 

Bir ASP.NET Core web uygulamasında önceki vurgulanan işaretleme kullanıldığında ve uygulama, aşağıdaki sunucular arası uç nokta yapılandırmasıyla komut satırında başlatıldığında:

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

Kestrel, appsettings.json dosyasında (https://localhost:9999), https://localhost:7777 öğesine değil, özel olarak Kestrel için yapılandırılan uç noktaya bağlanır.

Bir ortam değişkeni olarak yapılandırılmış Kestrel öğesine özgü uç noktayı göz önünde bulundurun:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Önceki ortam değişkeninde Https, Kestrel öğesine özgü bitiş noktasının adıdır. Önceki appsettings.json dosyası ayrıca Https adlı Kestrel öğesine özgü bir bitiş noktası tanımlar. Varsayılan olarak, Ortam Değişkenleri yapılandırma sağlayıcısını kullanan ortam değişkenleri appsettings.{Environment}.json öğesinden sonra okunur, bu nedenle Https uç noktası için önceki ortam değişkeni kullanılır.

GetValue

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

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

    public TestNumModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Önceki kodda, yapılandırmada NumberKey bulunamazsa, 99 öğesinin varsayılan değeri kullanılır.

GetSection, GetChildren ve Exists

Aşağıdaki örnekler için aşağıdaki MySubsection.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"
    }
  }
}

Aşağıdaki kod, yapılandırma sağlayıcılara MySubsection.json ekler:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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 için değerleri döndürür:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

Aşağıdaki kod section2:subsection0 için değerleri döndürür:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["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 IConfiguration.GetChildren çağırır ve section2:subsection0 için değerleri döndürür:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = "";
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Önceki kod, bölümün var olduğunu doğrulamak için ConfigurationExtensions.Exists öğesini çağırır:

Bir dizi 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.

Örnek indirmeden MyArray.json öğesini göz önünde bulundurun:

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

Aşağıdaki kod, yapılandırma sağlayıcılara MyArray.json ekler:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Aşağıdaki kod yapılandırmayı okur ve değerleri görüntüler:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample? _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
       _array = Config.GetSection("array").Get<ArrayExample>();
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }
        string s = String.Empty;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

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

Önceki kod aşağıdaki çıktıyı döndürür:

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, MyArray.json içindeki "4": "value40", öğesine karşılık gelen value40 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ı, boş değerler bağlayamaz veya bağlı nesnelerde boş girişler oluşturamaz.

Ö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 okur. Sağlayıcı, veritabanını anahtar başına bazında sorgulamaz.
• Değişiklikte yeniden yükle uygulanmaz, bu nedenle uygulama başladıktan sonra veritabanını güncelleştirmesi uygulamanın yapılandırması üzerinde hiçbir etkisi yoktur.

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ı ile (StringComparer.OrdinalIgnoreCase) oluşturulur.

EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    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 IDictionary<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, Program.cs içinde EFConfigurationProvider öğesinin nasıl kullanılacağını göstermektedir:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Bağımlılık Ekleme (DI) ile erişim yapılandırma

Yapılandırma, IConfiguration hizmeti çözülerek Bağımlılık Ekleme (DI) kullanılarak hizmetlere eklenebilir:

public class Service
{
    private readonly IConfiguration _config;

    public Service(IConfiguration config) =>
        _config = config;

    public void DoSomething()
    {
        var configSettingValue = _config["ConfigSetting"];

        // ...
    }
}

IConfiguration kullanarak değerlere erişme hakkında bilgi için, bu makaledeki GetValue ve GetSection, GetChildren ve Exists bölümlerine bakın.

Razor Sayfalarında yapılandırmaya erişim

Aşağıdaki kod, yapılandırma verilerini bir Razor Sayfasında görüntüler:

@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Aşağıdaki kodda MyOptions, Configure ile hizmet kapsayıcıya eklenmiş ve yapılandırmaya bağlanmıştır:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

var app = builder.Build();

Aşağıdaki biçimlendirme, seçenekler değerlerini çözümlemek ve görüntülemek için @injectRazor yönergesini kullanır:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Bir MVC görünüm dosyasında yapılandırmaya erişim

Aşağıdaki kod, yapılandırma verilerini bir MVC görüntüsünde görüntüler:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Program.cs içinde erişim yapılandırması

Aşağıdaki kod, Program.cs dosyasındaki yapılandırmaya erişir.

var builder = WebApplication.CreateBuilder(args);

var key1 = builder.Configuration.GetValue<string>("KeyOne");

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

var key2 = app.Configuration.GetValue<int>("KeyTwo");
var key3 = app.Configuration.GetValue<bool>("KeyThree");

app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);

app.Run();

appsettings.json Yukarıdaki örnekte:

{
  ...
  "KeyOne": "Key One Value",
  "KeyTwo": 1999,
  "KeyThree": true
}

Seçenekleri bir temsilci ile yapılandırma

Yapılandırma sağlayıcılarında ayarlanan bir temsilci geçersiz kılma değerlerinde yapılandırılan seçenekler.

Aşağıdaki kodda, bir IConfigureOptions<TOptions> hizmeti hizmet kapsayıcısına eklenir. MyOptions için değerleri yapılandırmak üzere bir temsilci kullanır:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "Value configured in delegate";
    myOptions.Option2 = 500;
});

var app = builder.Build();

Aşağıdaki kod, seçenekler değerlerini görüntüler:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

Önceki örnekte, Option1 ve Option2 değerleri appsettings.json içinde belirtilir ve ardından yapılandırılan temsilci tarafından geçersiz kılınır.

Ana bilgisayar ve uygulama yapılandırması

Uygulama yapılandırılıp başlatılmadan önce bir ana bilgisayar yapılandırılır ve başlatılır. Ana bilgisayar, uygulamanın başlatılmasından ve ömür boyu yönetiminden sorumludur. Hem uygulama hem de ana bilgisayar, bu konuda açıklanan yapılandırma sağlayıcıları kullanılarak yapılandırılır. Ana bilgisayar yapılandırması anahtar-değer çiftleri de uygulamanın yapılandırmasına dahildir. 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 ana bilgisayar yapılandırması

Web Ana Bilgisayarını kullanırken varsayılan yapılandırmayla ilgili ayrıntılar için bu konunun ASP.NET Core 2.2 sürümüne bakın.

• Konak yapılandırması şu kaynaktan sağlanır:
  • Ortam Değişkenleri yapılandırma sağlayıcısı kullanan, DOTNET_ ön eki olan ortam değişkenleri (örneğin, DOTNET_ENVIRONMENT). (DOTNET_) ön eki, yapılandırma anahtar/değer çiftleri yüklendiğinde çıkarılır.
  • Komut satırı yapılandırma sağlayıcısını kullanan komut satırı bağımsız değişkenleri.
• Web Ana Bilgisayarı varsayılan yapılandırması oluşturuldu (ConfigureWebHostDefaults):
  • Kestrel web sunucusu olarak kullanılır ve uygulamanın yapılandırma sağlayıcıları kullanılarak yapılandırılır.
  • Ana Bilgisayar Filtreleme Ara Yazılımı ekleyin.
  • ASPNETCORE_FORWARDEDHEADERS_ENABLED ortam değişkeni true olarak ayarlanmışsa, İletilen Üstbilgiler Ara Yazılımını ekleyin.
  • IIS tümleştirmesini etkinleştirin.

Diğer yapılandırma

Bu konu yalnızca uygulama yapılandırmasıyla ilgilidir. ASP.NET Core uygulamalarını çalıştırmanın ve barındırmanın diğer yönleri, bu konuda ele alınmayan yapılandırma dosyaları kullanılarak yapılandırılır:

• launch.json/launchSettings.json , Geliştirme ortamı için araç yapılandırma dosyalarıdır, aşağıda açıklanmıştır:
  • ASP.NET Core'da birden çok ortam kullanma içinde.
  • Geliştirme senaryoları için ASP.NET Core uygulamalarını yapılandırmak üzere dosyaların kullanıldığı belge kümesi genelinde.
• web.config , aşağıdaki konularda açıklanan bir sunucu yapılandırma dosyasıdır:
  • IIS ile Windows'da ASP.NET Core'u barındırma
  • IIS için ASP.NET Core Modülü (ANCM)

launchSettings.json içinde ayarlanan ortam değişkenleri, sistem ortamında ayarlanmış olanları geçersiz kılar.

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

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ğlama kaynak oluşturucu

Yapılandırma bağlama kaynak oluşturucu, AOT ve kırpma dostu yapılandırma sağlar. Daha fazla bilgi için bkz . Yapılandırma bağlama kaynak oluşturucu.

Ek kaynaklar

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