.NET 中的設定

.NET 中的設定是使用一或多個設定提供者來執行的。 設定提供者會使用各種設定來源從機碼值組中讀取設定資料：

• 設定檔案，如 appsettings.json
• 環境變數
• Azure Key Vault
• Azure 應用程式組態
• 命令列引數
• 自訂提供者 (已安裝或已建立)
• 目錄檔案
• 記憶體內部 .NET 物件
• 協力廠商提供者

注意

如需設定 .NET 執行階段的相關資訊，請參閱 .NET 執行階段組態設定。

概念和抽象概念

給定一或多個設定來源，IConfiguration 類型為設定資料提供一個統一的視圖。 設定是唯讀的，而且設定模式的設計無法用程式設計方式寫入。 IConfiguration 介面是所有設定來源的單一表示法，如下圖所示：

設定主控台應用程式

根據預設，使用 dotnet new 命令範本或 Visual Studio 建立的 .NET 主控台應用程式不會公開設定功能。 若要在新的 .NET 主控台應用程式中新增設定，請在 Microsoft.Extensions.Configuration 中新增套件參考。 此套件是 .NET 應用程式中組態的基礎。 它提供 ConfigurationBuilder 和相關的型別。

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

上述 程式碼：

• 建立新的 ConfigurationBuilder 執行個體。
• 將機碼/值組的記憶體內部集合新增至組態建立器。
• 呼叫 Build() 方法來建立 IConfiguration 執行個體。
• 將 SomeKey 機碼的值寫入主控台。

雖然此範例使用記憶體內部組態，但有許多可用的組態提供者，並公開檔案型、環境變數、命令列引數和其他組態來源的功能。 如需詳細資訊，請參閱 .NET 中的組態提供者。

替代裝載方法

通常，您的應用程式不只是讀取組態，還會執行更多作業。 它們可能會使用相依性插入、記錄和其他服務。 針對使用這些服務的應用程式，建議使用 .NET 泛型主機方法。 相反地，請考慮將套件參考新增至 Microsoft.Extensions.Hosting。 修改 Program.cs 檔案以符合下列程式碼：

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

Host.CreateApplicationBuilder(String[]) 方法會以下列順序為應用程式提供預設組態 (從最高到最低優先順序排列)：

1. 使用命令列設定提供者的命令列引數。
2. 使用環境變數設定提供者的環境變數。
3. 當應用程式在 Development 環境中執行時的應用程式祕密
4. 使用 JSON 設定提供者的 appsettings.json。
5. 使用 JSON 設定提供者的 appsettings.Environmentjson。 例如，appsettings.Production.json 和 appsettings.Development.json。
6. ChainedConfigurationProvider：將現有 IConfiguration 新增為來源。

新增設定提供者會覆寫先前的設定值。 例如，因為命令列設定提供者是最後新增的項目，所以它會覆寫所有來自其他提供者的值。 如果 SomeKey 在 appsettings.json 和環境中皆有設定，則會使用環境值，因為它是在 appsettings.json 之後新增的。

繫結

使用 .NET 設定抽象概念的主要優點之一，是它能夠將設定值繫結至 .NET 物件的執行個體。 例如，JSON 設定提供者可用來將 appsettings.json 檔案對應至 .NET 物件，並搭配相依性插入使用。 這會啟用選項模式，該模式會使用類別來提供相關設定群組的強型別存取。 .NET 設定提供各種抽象概念。 請考量下列介面：

• IConfiguration：表示一組索引鍵/數值應用程式設定屬性。
• IConfigurationRoot：表示 IConfiguration 階層的根。
• IConfigurationSection：表示應用程式設定值的區段。

這些抽象概念與其基礎設定提供者無關 (IConfigurationProvider)。 換句話說，您可以使用 IConfiguration 執行個體來存取多個提供者的任何設定值。

繫結器可以用不同的方法來處理設定值：

• 基本類型的直接還原序列化 (使用內建轉換器)。
• 針對複雜類型的 TypeConverter (如果類型中有複雜類型)。
• 具有屬性之複雜類型的反映。

注意

繫結器有一些限制：

• 如果屬性有私人 setter 或無法轉換類型，則該屬性會被忽略。
• 沒有對應設定索引鍵的屬性會被忽略。

繫結階層

設定值可以包含階層式資料。 階層式物件會用設定索引鍵中的分隔符號 : 來表示。 若要存取設定值，請用 : 字元來分隔階層。 例如，請考慮下列設定值：

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

下表代表上述 JSON 範例的索引鍵範例及其對應的值：

機碼	值
"Parent:FavoriteNumber"	7
"Parent:Child:Name"	"Example"
"Parent:Child:GrandChild:Age"	3

基本範例

若要在不使用泛型主機方法的狀況下存取基本形式的設定值，請直接使用 ConfigurationBuilder 類型。

提示

System.Configuration.ConfigurationBuilder 類型與 Microsoft.Extensions.Configuration.ConfigurationBuilder 類型不同。 所有內容都僅適用於 Microsoft.Extensions.* NuGet 套件和命名空間。

請考慮以下 C# 專案：

<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.2" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
  </ItemGroup>

</Project>

上述專案檔參考了幾個設定 NuGet 套件：

• Microsoft.Extensions.Configuration.Binder：Microsoft.Extensions.Configuration 當中將物件繫結至設定提供者中資料的功能。
• Microsoft.Extensions.Configuration.Json：Microsoft.Extensions.Configuration 的 JSON 設定提供者實作。
• Microsoft.Extensions.Configuration.EnvironmentVariables：Microsoft.Extensions.Configuration 的環境變數設定提供者實作。

請考慮一個 appsettings.json 檔案範例：

{
    "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"
        ]
    }
}

假設使用此 JSON 檔案，以下是直接使用設定產生器的取用模式範例：

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

在上述 C# 程式碼中：

• 具現化 ConfigurationBuilder。
• 新增 JSON 組態提供者所要辨識的 "appsettings.json" 檔案。
• 將環境變數新增為由環境變數設定提供者辨識。
• 使用 config 執行個體取得必要的 "Settings" 區段和對應的 Settings 執行個體。

物件 Settings 的形狀如下：

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!;
}

裝載的基本範例

若要存取 IConfiguration 值，您可以再次使用 Microsoft.Extensions.Hosting NuGet 套件。 建立新的主控台應用程式，並將下列專案檔內容貼入其中：

<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.2" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </ItemGroup>

</Project>

上述專案檔會定義：

• 應用程式是可執行檔。
• 編譯專案時，會複製一個 appsettings.json 檔案到輸出目錄。
• 已新增 Microsoft.Extensions.Hosting NuGet 套件參考。

使用下列內容在專案的根目錄新增 appsettings.json 檔案：

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

使用下列 C# 程式碼取代 Program.cs 檔案中的內容：

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!

當您執行此應用程式時，Host.CreateApplicationBuilder 會定義探索 JSON 設定並透過 IConfiguration 執行個體公開它的行為。 從 host 執行個體中，您可以向服務提供者要求 IConfiguration 執行個體，然後要求它提供值。

提示

用這種方式使用原始 IConfiguration 執行個體雖然方便，但無法妥善調整。 當應用程式複雜度增加，且其對應的設定也變得更複雜時，建議您使用選項模式做為替代方案。

裝載和使用索引子 API 的基本範例

請考慮與上述範例相同的 appsettings.json 檔案內容：

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

使用下列 C# 程式碼取代 Program.cs 檔案中的內容：

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

這些值可用索引子 API 來存取，其中每個索引鍵都是字串且值也是字串。 設定支援屬性、物件、陣列和字典。

設定提供者

下表顯示可供 .NET Core 應用程式使用的設定提供者。

提供者	從提供設定
Azure 應用程式設定提供者	Azure 應用程式組態
Azure Key Vault 組態提供者	Azure Key Vault
命令列設定提供者	命令列參數
自訂設定提供者	自訂來源
環境變數設定提供者	環境變數
檔案設定提供者	JSON、XML 和 INI 檔案
每個檔案機碼設定提供者	目錄檔案
記憶體設定提供者	記憶體內集合
應用程式秘密 (秘密管理員)	使用者設定檔目錄中的檔案

提示

新增設定提供者的順序是很重要的。 使用多個設定提供者，而且其中超過一個提供者指定相同的索引鍵時，會使用最後一個新增的項目。

如需各種設定提供者的詳細資訊，請參閱 .NET 中的設定提供者。

另請參閱

• .NET 中的設定提供者
• 實作自訂組態提供者
• 設定錯誤應建於 github.com/dotnet/runtime/ 存放庫中
• ASP.NET Core 中的組態