.NET'te yapılandırma

  • Makale

.NET'te yapılandırma 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ını kullanarak anahtar-değer çiftlerinden yapılandırma verilerini okur:

  • appsettings.json gibi dosyaları Ayarlar
  • Ortam değişkenleri
  • Azure Key Vault
  • Azure Uygulaması 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
  • Üçü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ı.

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. Arabirim IConfiguration , aşağıdaki diyagramda gösterildiği gibi tüm yapılandırma kaynaklarının tek bir gösterimidir:

The `IConfiguration` interface is a single representation of all the configuration sources.

Konsol uygulamalarını yapılandırma

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

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

Yukarıdaki kod:

  • Yeni bir ConfigurationBuilder örneği oluşturur.
  • Yapılandırma oluşturucusunun bellek içi anahtar-değer çiftleri koleksiyonunu ekler.
  • Build() Bir IConfiguration örnek oluşturmak için yöntemini çağırır.
  • Anahtarın değerini SomeKey konsola 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'te 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 ekleme, günlüğe kaydetme ve diğer hizmetleri kullanırlar. Bu hizmetleri kullanan uygulamalar için .NET Genel Ana Bilgisayar yaklaşımı önerilir. Bunun yerine, Microsoft.Extensions.Hosting'e paket başvurusu eklemeyi göz önünde bulundurun. 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();

yöntemi, Host.CreateApplicationBuilder(String[]) 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 Development ortamında çalıştığında uygulama gizli dizileri.
  4. JSON yapılandırma sağlayıcısını kullanarak appsettings.json.
  5. appsettings.Environment. JSON yapılandırma sağlayıcısını kullanarak json. Örneğin, uygulama ayarları.Üretim.json ve appsettings.Geliştirme.json.
  6. ChainedConfigurationProvider : Mevcut bir IConfiguration öğelerini 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ı son eklendiğinden diğer sağlayıcılardan gelen tüm değerleri geçersiz kılar. Hem appsettings.json hem de ortamda ayarlanırsaSomeKey, ortam değeri appsettings.json sonra eklendiğinden kullanılır.

Bağlama

.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ını .NET nesneleriyle eşlemek için kullanılabilir ve bağımlılık ekleme ile kullanılır. Bu, ilgili ayar gruplarına kesin olarak belirlenmiş erişim sağlamak için sınıfları kullanan seçenekler desenini etkinleştirir. .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ı (IConfigurationProvider) için 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 doğrudan seri durumdan çıkarma (yerleşik dönüştürücüler kullanılarak).
  • Türün TypeConverter bir türü olduğunda karmaşık bir tür için.
  • Özellikleri olan karmaşık bir tür için Düşünceler.

Not

Bağlayıcının birkaç sınırlaması 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 yoksayılır.

Bağlama hiyerarşileri

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 örnek anahtarlar ve önceki örnek JSON için karşılık gelen değerler temsil eder:

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

Temel örnek

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

İpucu

Tür System.Configuration.ConfigurationBuilder , türünden Microsoft.Extensions.Configuration.ConfigurationBuilder farklıdır. Bu içeriğin tümü NuGet paketlerine Microsoft.Extensions.* 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="8.0.1" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
  </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:

  • Bir örneği ConfigurationBuilderoluşturur.
  • "appsettings.json" JSON yapılandırma sağlayıcısı tarafından tanınacak dosyayı ekler.
  • Ortam Değişken yapılandırma sağlayıcısı tarafından tanınıyor olarak ortam değişkenlerini ekler.
  • Örneği kullanarak config gerekli "Settings" bölümü ve ilgili Settings örneği alır.

Settings Nesne 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

Değere IConfiguration erişmek için NuGet paketine Microsoft.Extensions.Hosting 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.Hosting" Version="8.0.0" />
  </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 eklenir.

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 örneği aracılığıyla IConfiguration kullanıma sunma davranışını tanımlar. Örnekten host hizmet sağlayıcısından IConfiguration örneği isteyebilir ve ardından değerler isteyebilirsiniz.

İpucu

Ham IConfiguration örneğin bu şekilde kullanılması 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 olarak seçenekler desenini kullanmanızı öneririz.

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

Önceki örnekteki aynı 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.

Konfigürasyon sağlayıcıları

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

Provider Şuradan yapılandırma sağlar
Azure Uygulama yapılandırması sağlayıcı Azure Uygulama Yapılandırması
Azure Key Vault yapılandırma sağlayıcısı Azure Key Vault
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ı JSON, XML ve INI dosyaları
Dosya başına anahtar yapılandırma sağlayıcı Dizin dosyaları
Bellek yapılandırma sağlayıcı Bellek için koleksiyonlar
Uygulama gizli dizileri (Gizli Dizi Yöneticisi) Kullanıcı profili dizinindeki dosya

İpucu

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'te yapılandırma sağlayıcıları.

Ayrıca bkz.