訓練
ASP.NET 的設定產生器 (機器翻譯)
組態產生器提供現代化且敏捷的機制,讓 ASP.NET 應用程式從外部來源取得組態值。
組態產生器:
- 適用於 .NET Framework 4.7.1 和更新版本。
- 提供彈性的機制來讀取組態值。
- 解決應用程式移至容器和雲端焦點環境時的某些基本需求。
- 可用來改善 .NET 組態系統中先前無法使用的來源(例如 Azure 金鑰保存庫 和環境變數)保護組態數據。
組態產生器可以處理的常見案例是針對遵循索引鍵/值模式的組態區段提供基本索引鍵/值取代機制。 ConfigurationBuilders 的 .NET Framework 概念不限於特定的組態區段或模式。 不過,(github、NuGet)中的Microsoft.Configuration.ConfigurationBuilders
許多組態產生器可在索引鍵/值模式內運作。
下列設定適用於 中的所有 Microsoft.Configuration.ConfigurationBuilders
索引鍵/值組態產生器。
組態產生器會使用索引鍵/值資訊的外部來源,填入組態系統的選取索引鍵/值元素。 具體來說, <appSettings/>
和 <connectionStrings/>
區段會從組態產生器收到特殊處理。 建置者會以三種模式運作:
Strict
- 預設模式。 在此模式中,組態產生器只會在已知的索引鍵/值中心組態區段上運作。Strict
mode 會列舉 區段中的每個索引鍵。 如果在外部來源中找到相符的索引鍵:- 組態產生器會將產生的組態區段中的值取代為來自外部來源的值。
Greedy
- 此模式與模式密切相關Strict
。 不限於原始組態中已存在的金鑰:- 組態產生器會將來自外部來源的所有索引鍵/值組新增至產生的組態區段。
Expand
- 在剖析成組態區段物件之前,先在原始 XML 上操作。 它可以視為字串中標記的擴充。 符合模式${token}
的原始 XML 字串的任何部分,都是令牌擴充的候選專案。 如果在外部來源中找不到對應的值,則令牌不會變更。 此模式中的產生器不限於<appSettings/>
和<connectionStrings/>
區段。
下列來自 web.config 的標記會在模式中Strict
啟用 EnvironmentConfigBuilder:
<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="MyEnvironment"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
</builders>
</configBuilders>
<appSettings configBuilders="MyEnvironment">
<add key="ServiceID" value="ServiceID value from web.config" />
<add key="ServiceKey" value="ServiceKey value from web.config" />
</appSettings>
<connectionStrings configBuilders="MyEnvironment">
<add name="default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
下列程式代碼會 <appSettings/>
讀取 ,並 <connectionStrings/>
顯示在上述 web.config 檔案中:
using System;
using System.Configuration;
using System.Web.UI;
namespace MyConfigBuilders
{
public partial class About : Page
{
public string ServiceID { get; set; }
public string ServiceKey { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["ServiceID"];
ServiceKey = ConfigurationManager.AppSettings["ServiceKey"];
ConString = ConfigurationManager.ConnectionStrings["default"]
?.ConnectionString;
}
}
}
此程式代碼會將 屬性值設定為:
- 如果未在環境變數中設定索引鍵,則為 web.config 檔案中的值。
- 如果已設定,則為環境變數的值。
例如, ServiceID
將包含:
- 如果未設定環境變數
ServiceID
,則為 “serviceID value from web.config”。 - 如果已設定,
ServiceID
則為環境變數的值。
下圖顯示 <appSettings/>
環境編輯器中先前 web.config 檔案中設定的索引鍵/值:
注意:您可能需要結束並重新啟動Visual Studio,才能查看環境變數的變更。
索引鍵前置詞可以簡化設定索引鍵,因為:
- .NET Framework 組態很複雜且巢狀。
- 外部索引鍵/值來源通常是基本和一般性質。 例如,環境變數不是巢狀的。
使用下列任一方法,透過環境變數將 和 <connectionStrings/>
插入<appSettings/>
組態:
EnvironmentConfigBuilder
使用預設Strict
模式中的 ,以及組態檔中適當的索引鍵名稱。 上述程式代碼和標記會採用此方法。 使用此方法時,您無法在 和<connectionStrings/>
中<appSettings/>
擁有完全相同的具名索引鍵。- 在 模式中使用
Greedy
兩EnvironmentConfigBuilder
個 ,具有相異前置詞和stripPrefix
。 使用這種方法,應用程式可以讀取<appSettings/>
,而<connectionStrings/>
不需要更新組態檔。 下一節 stripPrefix 會示範如何執行這項操作。 - 在模式中使用
Greedy
兩EnvironmentConfigBuilder
個 具有不同前置詞的 。 使用此方法時,您無法有重複的索引鍵名稱,因為索引鍵名稱的前置詞必須不同。 例如:
<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
<add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
</builders>
</configBuilders>
<appSettings configBuilders="AS_Environment">
<add key="AppSetting_ServiceID" value="ServiceID value from web.config" />
<add key="AppSetting_default" value="AppSetting_default value from web.config" />
</appSettings>
<connectionStrings configBuilders="CS_Environment">
<add name="ConnStr_default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
使用上述標記時,相同的一般索引鍵/值來源可用來填入兩個不同的區段的組態。
下圖顯示<appSettings/>
環境編輯器中先前 web.config 檔案所設定的 和 <connectionStrings/>
索引鍵/值:
下列程式代碼會<appSettings/>
讀取上述 web.config 檔案中包含的 和 <connectionStrings/>
索引鍵/值:
public partial class Contact : Page
{
public string ServiceID { get; set; }
public string AppSetting_default { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["AppSetting_ServiceID"];
AppSetting_default = ConfigurationManager.AppSettings["AppSetting_default"];
ConString = ConfigurationManager.ConnectionStrings["ConnStr_default"]
?.ConnectionString;
}
}
此程式代碼會將 屬性值設定為:
- 如果未在環境變數中設定索引鍵,則為 web.config 檔案中的值。
- 如果已設定,則為環境變數的值。
例如,使用先前 的web.config 檔案、上一個環境編輯器映像中的索引鍵/值,以及先前的程式代碼,會設定下列值:
機碼 | 值 |
---|---|
AppSetting_ServiceID | env 變數AppSetting_ServiceID |
AppSetting_default | AppSetting_default env 的值 |
ConnStr_default | env ConnStr_default val |
stripPrefix
:布爾值,預設為 false
。
上述 XML 標記會分隔應用程式設定與 連接字串,但需要 web.config 檔案中的所有索引鍵才能使用指定的前置詞。 例如,前置詞 AppSetting
必須新增至 ServiceID
機碼 (“AppSetting_ServiceID” 使用 stripPrefix
時,不會在 web.config 檔案中使用前置詞。 組態產生器來源需要前置詞(例如,在環境中。我們預期大部分開發人員都會使用 stripPrefix
。
應用程式通常會去除前置詞。 下列 web.config 會移除前置詞:
<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
stripPrefix="true"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
<add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
stripPrefix="true"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
</builders>
</configBuilders>
<appSettings configBuilders="AS_Environment">
<add key="ServiceID" value="ServiceID value from web.config" />
<add key="default" value="AppSetting_default value from web.config" />
</appSettings>
<connectionStrings configBuilders="CS_Environment">
<add name="default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
在上述 web.config 檔案中,金鑰default
同時位於和 <connectionStrings/>
中<appSettings/>
。
下圖顯示<appSettings/>
環境編輯器中先前 web.config 檔案所設定的 和 <connectionStrings/>
索引鍵/值:
下列程式代碼會<appSettings/>
讀取上述 web.config 檔案中包含的 和 <connectionStrings/>
索引鍵/值:
public partial class About2 : Page
{
public string ServiceID { get; set; }
public string AppSetting_default { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["ServiceID"];
AppSetting_default = ConfigurationManager.AppSettings["default"];
ConString = ConfigurationManager.ConnectionStrings["default"]
?.ConnectionString;
}
}
此程式代碼會將 屬性值設定為:
- 如果未在環境變數中設定索引鍵,則為 web.config 檔案中的值。
- 如果已設定,則為環境變數的值。
例如,使用先前 的web.config 檔案、上一個環境編輯器映像中的索引鍵/值,以及先前的程式代碼,會設定下列值:
機碼 | 值 |
---|---|
ServiceID | env 變數AppSetting_ServiceID |
預設值 | AppSetting_default env 的值 |
預設值 | env ConnStr_default val |
tokenPattern
:字串,預設值為 @"\$\{(\w+)\}"
產生 Expand
器的行為會搜尋原始 XML,以尋找看起來像 的 ${token}
令牌。 搜尋是使用預設正則表達式 @"\$\{(\w+)\}"
來完成。 符合 \w
的字元集比 XML 更嚴格,而且許多組態來源允許。 tokenPattern
當令牌名稱中所需的字元多@"\$\{(\w+)\}"
時使用。
tokenPattern
:字串:
- 可讓開發人員變更用於令牌比對的 regex。
- 不會進行任何驗證,以確保它是格式正確的非危險 regex。
- 它必須包含擷取群組。 整個 regex 必須符合整個令牌。 第一個擷取必須是令牌名稱,才能在組態來源中查閱。
<add name="Environment"
[mode|prefix|stripPrefix|tokenPattern]
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
- 這是最簡單的組態產生器。
- 從環境讀取值。
- 沒有任何額外的組態選項。
name
屬性值是任意的。
注意: 在 Windows 容器環境中,在運行時間設定的變數只會插入 EntryPoint 進程環境。 除非透過容器中的機制插入這些變數,否則以服務或非 EntryPoint 進程執行的應用程式不會挑選這些變數。 針對 IIS/ASP.NET 型容器,目前版本的 ServiceMonitor.exe只會在 DefaultAppPool 中處理此作業。 其他以 Windows 為基礎的容器變體可能需要針對非 EntryPoint 進程開發自己的插入機制。
警告
請勿將密碼、敏感性 連接字串 或其他敏感數據儲存在原始程式碼中。 生產秘密不應該用於開發或測試。
<add name="UserSecrets"
[mode|prefix|stripPrefix|tokenPattern]
(userSecretsId="{secret string, typically a GUID}" | userSecretsFile="~\secrets.file")
[optional="true"]
type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />
在上述 XML 中 userSecretsFile
,路徑可以使用 ~/
或 ~\
。 例如,路徑可以寫入為 userSecretsFile="~/secrets.file
。 如需詳細資訊, 請參閱 ConfigurationBuilders Utils 類別。
此組態產生器提供類似 ASP.NET Core Secret Manager 的功能。
UserSecretsConfigBuilder 可用於 .NET Framework 專案中,但必須指定秘密檔案。 或者,您可以在項目檔中定義 UserSecretsId
屬性,並在正確的讀取位置中建立原始秘密檔案。 若要讓外部相依性遠離您的專案,秘密檔案會格式化為 XML。 XML 格式是實作詳細數據,不應依賴格式。 如果您需要與 .NET Core 專案共用 secrets.json 檔案,請考慮使用 SimpleJsonConfigBuilder。 SimpleJsonConfigBuilder
.NET Core 的格式也應該被視為可能變更的實作詳細數據。
的 UserSecretsConfigBuilder
組態屬性:
userSecretsId
- 這是識別 XML 秘密檔案的慣用方法。 其運作方式類似於 .NET Core,它會使用UserSecretsId
專案屬性來儲存此標識符。 字串必須是唯一的,它不需要是 GUID。 使用這個屬性,尋找UserSecretsConfigBuilder
屬於此標識符的秘密檔案的已知本機位置 (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml
)。userSecretsFile
- 選擇性屬性,指定包含秘密的檔案。~
字元可以在開頭用來參考應用程式根目錄。 需要這個屬性或userSecretsId
屬性。 如果同時指定兩者,userSecretsFile
則優先使用 。optional
:布爾值,預設值true
- 如果找不到秘密檔案,則防止例外狀況。name
屬性值是任意的。
秘密檔案的格式如下:
<?xml version="1.0" encoding="utf-8" ?>
<root>
<secrets ver="1.0">
<secret name="secret key name" value="secret value" />
</secrets>
</root>
<add name="AzureKeyVault"
[mode|prefix|stripPrefix|tokenPattern]
(vaultName="MyVaultName" |
uri="https:/MyVaultName.vault.azure.net")
[version="secrets version"]
[preloadSecretNames="true"]
type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Azure" />
AzureKeyVaultConfigBuilder 會讀取儲存在 Azure 金鑰保存庫 中的值。
vaultName
為必要專案(保存庫的名稱或保存庫的 URI)。 其他屬性允許控制要連線到哪一個保存庫,但只有在應用程式未在使用 Microsoft.Azure.Services.AppAuthentication
的環境中執行時才需要。 Azure 服務驗證連結庫可用來盡可能從執行環境自動挑選連線資訊。 您可以藉由提供 連接字串 來覆寫自動挑選連線資訊。
vaultName
- 如果未uri
提供 ,則為必要項。 指定要從中讀取金鑰/值組的 Azure 訂用帳戶中保存庫的名稱。uri
- 連接到具有指定uri
值的其他 金鑰保存庫 提供者。 如果未指定,Azure (vaultName
) 是保存庫提供者。version
- Azure 金鑰保存庫 提供秘密的版本設定功能。 如果version
指定 ,則產生器只會擷取符合此版本的秘密。preloadSecretNames
- 根據預設,此產生器會在初始化金鑰保存庫時查詢 金鑰保存庫中的所有 金鑰名稱。 若要防止讀取所有索引鍵值,請將此屬性設定為false
。 將此設定為false
一次讀取一個秘密。 如果保存庫允許「取得」存取,但不允許「列出」存取,則一次讀取秘密會很有用。 注意: 使用Greedy
模式時,preloadSecretNames
必須是true
(預設值)。
<add name="KeyPerFile"
[mode|prefix|stripPrefix|tokenPattern]
(directoryPath="PathToSourceDirectory")
[ignorePrefix="ignore."]
[keyDelimiter=":"]
[optional="false"]
type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />
KeyPerFileConfigBuilder 是使用目錄檔案作為值來源的基本組態產生器。 檔名是索引鍵,而內容則是 值。 此組態產生器在協調的容器環境中執行時很有用。 Docker Swarm 和 Kubernetes 等系統會以每個檔案密鑰的方式提供給 secrets
其協調的 Windows 容器。
屬性詳細資料:
directoryPath
- 必要。 指定要尋找值的路徑。 Windows 秘密的 Docker 預設會儲存在 C:\ProgramData\Docker\secrets 目錄中。ignorePrefix
- 排除以這個前置詞開頭的檔案。 預設為 "ignore."。keyDelimiter
- 預設值為null
。 如果指定,組態產生器會周游目錄的多個層級,並使用這個分隔符來建置索引鍵名稱。 如果此值為null
,組態產生器只會查看目錄的最上層。optional
- 預設值為false
。 指定如果來源目錄不存在,組態產生器是否應該造成錯誤。
警告
請勿將密碼、敏感性 連接字串 或其他敏感數據儲存在原始程式碼中。 生產秘密不應該用於開發或測試。
<add name="SimpleJson"
[mode|prefix|stripPrefix|tokenPattern]
jsonFile="~\config.json"
[optional="true"]
[jsonMode="(Flat|Sectional)"]
type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Json" />
.NET Core 項目經常使用 JSON 檔案進行設定。 SimpleJsonConfigBuilder 建立器可讓 .NET Core JSON 檔案用於 .NET Framework。 此組態產生器提供基本對應,從一般索引鍵/值來源到 .NET Framework 組態的特定索引鍵/值區域。 此組態產生器不提供階層式組態。 JSON 備份檔案類似於字典,而不是複雜的階層式物件。 您可以使用多層級階層式檔案。 這個提供者 flatten
會藉由在每個層級附加屬性名稱,以 :
做為分隔符,藉此為深度。
屬性詳細資料:
jsonFile
- 必要。 指定要從中讀取的 JSON 檔案。~
字元可以在開頭用來參考應用程式根目錄。optional
- 布林值,預設值為true
。 如果找不到 JSON 檔案,則防止擲回例外狀況。jsonMode
-[Flat|Sectional]
.Flat
是預設值。 當 是Flat
時jsonMode
,JSON 檔案是單一一般索引鍵/值來源。EnvironmentConfigBuilder
和AzureKeyVaultConfigBuilder
也是單一一索引鍵/值來源。SimpleJsonConfigBuilder
在模式中Sectional
設定 時:- JSON 檔案在概念上只是在最上層分割成多個字典。
- 每個字典只會套用至符合附加至最上層屬性名稱的組態區段。 例如:
{
"appSettings" : {
"setting1" : "value1",
"setting2" : "value2",
"complex" : {
"setting1" : "complex:value1",
"setting2" : "complex:value2",
}
}
}
請參閱 aspnet/MicrosoftConfigurationBuilders GitHub 存放庫中的 ConfigurationBuilders 執行順序。
如果設定產生器不符合您的需求,您可以撰寫自定義的。 KeyValueConfigBuilder
基類會處理替代模式和大部分前置詞考慮。 實作專案只需要:
- 繼承自基類,並透過
GetValue
和GetAllValues
實作索引鍵/值組的基本來源: - 將 Microsoft.Configuration.ConfigurationBuilders.Base 新增至專案。
using Microsoft.Configuration.ConfigurationBuilders;
using System.Collections.Generic;
public class MyCustomConfigBuilder : KeyValueConfigBuilder
{
public override string GetValue(string key)
{
// Key lookup should be case-insensitive, because most key/value collections in
// .NET Framework config sections are case-insensitive.
return "Value for given key, or null.";
}
public override ICollection<KeyValuePair<string, string>> GetAllValues(string prefix)
{
// Populate the return collection.
return new Dictionary<string, string>() { { "one", "1" }, { "two", "2" } };
}
}
基 KeyValueConfigBuilder
類可在索引鍵/值組態產生器之間提供許多工作和一致的行為。