Aracılığıyla paylaş

.NET'te yapılandırma

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

  • appsettings.json gibi ayarlar dosyaları
  • Ortam değişkenleri
  • Azure Key Vault
  • Azure Uygulama Yapılandırması
  • Komut satırı argümanları
  • Kurulmuş veya oluşturulmuş özel sağlayıcılar
  • Dizin dosyaları
  • Bellek içi .NET nesneleri
  • Üçüncü taraf sağlayıcılar

Not

.NET çalışma zamanını yapılandırma hakkında bilgi için bkz. .NET Çalışma Zamanı yapılandırma ayarlarını.

Kavramlar ve soyutlamalar

Bir veya daha fazla yapılandırma kaynağı göz önüne alındığında, IConfiguration türü yapılandırma verilerinin birleşik bir görünümünü sağlar. Yapılandırma salt okunurdur ve yapılandırma düzeni program aracılığıyla yazılabilir olacak şekilde tasarlanmamıştır. IConfiguration arabirimi, aşağıdaki diyagramda gösterildiği gibi tüm yapılandırma kaynaklarının tek bir gösterimidir:

'IConfiguration' arabirimi tüm yapılandırma kaynaklarının tek bir gösterimidir.

Konsol uygulamalarını yapılandırma

varsayılan olarak dotnet yeni komut şablonu veya Visual Studio kullanılarak oluşturulan .NET konsol uygulamaları yapılandırma özelliklerini kullanıma sunmaz. Yeni bir .NET konsol uygulamasına yapılandırma eklemek için Microsoft.Extensions.Configuration öğesine bir paket referansı ekleyin. Bu paket, .NET uygulamalarında yapılandırmanın temelini oluşturur. ConfigurationBuilder ve ilgili türleri sunar.

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

Önceki kod:

  • Yeni bir ConfigurationBuilder örneği oluşturur.
  • Yapılandırma oluşturucusunun bellek içi anahtar-değer çiftleri koleksiyonunu ekler.
  • Build() örneği oluşturmak için IConfiguration yöntemini çağırır.
  • konsola SomeKey anahtarının değerini yazar.

Bu örnekte bellek içi yapılandırma kullanılıyor olsa da, dosya tabanlı, ortam değişkenleri, komut satırı bağımsız değişkenleri ve diğer yapılandırma kaynakları için işlevselliği ortaya çıkaran birçok yapılandırma sağlayıcısı vardır. Daha fazla bilgi için bkz. .NET Yapılandırma sağlayıcıları.

Alternatif barındırma yaklaşımı

Genellikle, uygulamalarınız yalnızca okuma yapılandırmasından fazlasını yapar. Büyük olasılıkla bağımlılık enjeksiyonu, loglama ve diğer hizmetleri kullanırlar. Bu hizmetleri kullanan uygulamalar için .NET Genel Ana Bilgisayar yaklaşımı önerilir. Bunun yerine, Microsoft.Extensions.Hosting'ne paket referansı eklemeyi düşünün. Program.cs dosyasını aşağıdaki kodla eşleşecek şekilde değiştirin:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Host.CreateApplicationBuilder(String[]) yöntemi, uygulama için en yüksekten en düşük önceliğe kadar 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. Ortam Değişkenleri yapılandırma sağlayıcısınıkullanan ortam değişkenleri.
  3. Uygulama, ortamında çalıştırıldığında Development.
  4. JSON yapılandırma sağlayıcısınıkullanarak appsettings.json.
  5. Environment .json. Örneğin, appsettings. Üretim.JSON ve appsettings. Geliştirme. JSON.
  6. ChainedConfigurationProvider: Mevcut bir IConfiguration'yi kaynak olarak ekler.

Yapılandırma sağlayıcısı eklemek önceki yapılandırma değerlerini geçersiz kılar. Örneğin, Komut satırı yapılandırma sağlayıcısı en son eklendiğinden diğer sağlayıcılardan gelen tüm değerleri geçersiz kılar. SomeKey hem appsettings.json'te hem de ortamda ayarlandıysa, ortam değeri appsettings.json'dan sonra eklendiği için kullanılır.

Bağlayıcı

.NET yapılandırma soyutlamalarını kullanmanın temel avantajlarından biri, yapılandırma değerlerini .NET nesnelerinin örneklerine bağlama özelliğidir. Örneğin, JSON yapılandırma sağlayıcısı appsettings.json dosyaları .NET nesnelerine eşlemek için kullanılabilir ve bağımlılık eklemeile kullanılır. Bu, seçenekleri desenini etkinleştirir ve ilgili ayar gruplarına kesin olarak belirlenmiş erişim sağlamak için sınıfları kullanır. Varsayılan bağlayıcı yansıma tabanlıdır, ancak etkinleştirmesi kolay bir kaynak oluşturucu alternatif vardır.

.NET yapılandırması çeşitli soyutlamalar sağlar. Aşağıdaki arabirimleri göz önünde bulundurun:

Bu soyutlamalar, temel yapılandırma sağlayıcılarına (IConfigurationProvider) göre belirsizdir. Başka bir deyişle, birden çok sağlayıcıdan herhangi bir yapılandırma değerine erişmek için bir IConfiguration örneği kullanabilirsiniz.

Bağlayıcı, yapılandırma değerlerini işlemek için farklı yaklaşımlar kullanabilir:

  • İlkel türler için yerleşik dönüştürücüler kullanılarak doğrudan seri durumdan çıkarma.
  • Bir tür karmaşık bir türe sahip olduğunda TypeConverter.
  • Özellikleri bulunan karmaşık bir tür için yansıma.

Not

Bağlayıcının birkaç sınırlamaları vardır.

  • Özel ayarlayıcıları varsa veya türleri dönüştürülemiyorsa özellikler yoksayılır.
  • Karşılık gelen yapılandırma anahtarları olmayan özellikler dikkate alınmaz.

Bağlayıcı hiyerarşiler

Yapılandırma değerleri hiyerarşik veriler içerebilir. Hiyerarşik nesneler, yapılandırma anahtarlarında : sınırlayıcının kullanımıyla temsil edilir. Bir yapılandırma değerine erişmek için hiyerarşiyi sınırlandırmak için : karakterini kullanın. Örneğin, aşağıdaki yapılandırma değerlerini göz önünde bulundurun:

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

Aşağıdaki tabloda, önceki JSON örneği için örnek anahtarlar ve karşılık gelen değerler gösterilmektedir.

Anahtar Değer
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Temel örnek

Yapılandırma değerlerine temel biçimlerinde erişmek için, genel konak yaklaşımının yardımı olmadan doğrudan ConfigurationBuilder türünü kullanın.

Bahşiş

System.Configuration.ConfigurationBuilder türü, Microsoft.Extensions.Configuration.ConfigurationBuilder türünden farklıdır. Bu içeriğin tümü Microsoft.Extensions.* NuGet paketlerine ve ad alanlarına özgüdür.

Aşağıdaki C# projesini göz önünde bulundurun:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.6" />
  </ItemGroup>

</Project>

Yukarıdaki proje dosyası birkaç yapılandırma NuGet paketine başvurur:

Örnek bir appsettings.json dosyası düşünün:

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

Şimdi, bu JSON dosyası göz önüne alındığında, yapılandırma oluşturucusunu doğrudan kullanan örnek bir tüketim deseni aşağıda verilmiştir:

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings? settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings?.KeyOne}");
Console.WriteLine($"KeyTwo = {settings?.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings?.KeyThree?.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

Yukarıdaki C# kodu:

  • Bu bir ConfigurationBuilderörneği oluşturur.
  • JSON yapılandırma sağlayıcısı tarafından tanınmak üzere "appsettings.json" dosyasını ekler.
  • Ortam değişkenleri, Ortam Değişken yapılandırma sağlayıcısı tarafından tanınacak şekilde eklenir.
  • "Settings" örneğini kullanarak gerekli Settings bölümünü ve ilgili config örneğini alır.

Settings nesnesi aşağıdaki gibi şekillendirilir:

public sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

Barındırma ile ilgili temel örnek

IConfiguration değerine erişmek için Microsoft.Extensions.Hosting NuGet paketine yeniden güvenebilirsiniz. Yeni bir konsol uygulaması oluşturun ve içine aşağıdaki proje dosyası içeriğini yapıştırın:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.6" />
  </ItemGroup>

</Project>

Yukarıdaki proje dosyası aşağıdakileri tanımlar:

  • Uygulama yürütülebilir bir dosyadır.
  • Proje derlendiğinde çıkış dizinine bir appsettings.json dosyası kopyalanır.
  • Microsoft.Extensions.Hosting NuGet paket başvurusu eklendi.

Projenin köküne aşağıdaki içeriklerle appsettings.json dosyasını ekleyin:

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

Program.cs dosyasının içeriğini aşağıdaki C# koduyla değiştirin:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string? keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

Bu uygulamayı çalıştırdığınızda, Host.CreateApplicationBuilder JSON yapılandırmasını bulma ve IConfiguration örneği aracılığıyla kullanıma sunma davranışını tanımlar. host örneğinden hizmet sağlayıcısından IConfiguration örneğini talep edebilir ve ardından ondan değerleri alabilirsiniz.

Tavsiye

Ham IConfiguration örneğini bu şekilde kullanmak kullanışlı olsa da çok iyi ölçeklendirilmiyor. Uygulamaların karmaşıklığı arttığında ve bunlara karşılık gelen yapılandırmalar daha karmaşık hale geldiğinde, alternatif olarakseçenekleri desenini kullanmanızı öneririz.

Dizin oluşturucu API'sini barındırma ve kullanma ile ilgili temel örnek

Önceki örnekteki appsettings.json dosya içeriğini göz önünde bulundurun:

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

Program.cs dosyasının içeriğini aşağıdaki C# koduyla değiştirin:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

Değerlere, her anahtarın bir dize olduğu ve değerin bir dize olduğu dizin oluşturucu API'si kullanılarak erişilir. Yapılandırma özellikleri, nesneleri, dizileri ve sözlükleri destekler.

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

Aşağıdaki tabloda .NET Core uygulamalarında kullanılabilen yapılandırma sağlayıcıları gösterilmektedir.

Sağlayıcı Şu kaynaktan yapılandırma sağlar:
Azure Uygulama yapılandırma sağlayıcısı Azure Uygulama Yapılandırması
Azure Key Vault yapılandırma sağlayıcısı Azure Key Vault
Komut satırı yapılandırma sağlayıcısı Komut satırı parametreleri
Özel yapılandırma sağlayıcısı Ö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ı JSON, XML ve INI dosyaları
dosya başına anahtar yapılandırma sağlayıcısı Dizin dosyaları
Bellek yapılandırma sağlayıcısı Bellek içi koleksiyonlar
Uygulama sırları (Sır Yöneticisi) Kullanıcı profili dizinindeki dosya

Bahşiş

Yapılandırma sağlayıcılarının eklenme sırası önemlidir. Birden çok yapılandırma sağlayıcısı kullanıldığında ve birden fazla sağlayıcı aynı anahtarı belirttiğinde, eklenen son sağlayıcı kullanılır.

Çeşitli yapılandırma sağlayıcıları hakkında daha fazla bilgi için bkz. .NET Yapılandırma sağlayıcıları.

Ayrıca bkz.