應用程式設定

發行項
06/08/2023

提示

本內容節錄自《Blazor for ASP NET Web Forms Developers for Azure》電子書，可以從 .NET Docs 取得，也可以免費下載 PDF 離線閱讀。

在 Web Forms 中載入應用程式組態的主要方式是使用 web.config 檔案中的項目，不論是在伺服器上，還是 web.config 所參考的相關組態檔。您可以使用靜態 ConfigurationManager 物件來與應用程式設定、資料存放庫連接字串，以及其他新增至應用程式的擴充組態提供者進行互動。通常會看到與應用程式設定的互動，如下列程式碼所示：

var configurationValue = ConfigurationManager.AppSettings["ConfigurationSettingName"];
var connectionString = ConfigurationManager.ConnectionStrings["MyDatabaseConnectionName"].ConnectionString;

使用 ASP.NET Core 和伺服器端Blazor時，如果您的應用程式裝載於 Windows IIS 伺服器上，可能會有 web.config 檔案。不過，此設定沒有任何ConfigurationManager互動，而且您可以從其他來源接收更多結構化應用程式設定。讓我們看看如何收集設定，以及如何從 web.config 檔案存取組態資訊。

組態來源

ASP.NET Core 可辨識許多您可能想要用於應用程式的設定來源。根據預設，本架構會嘗試提供您這些最佳的功能。設定會依 ASP.NET Core 從這些各種來源讀取和彙總。稍後針對相同設定索引鍵載入的值優先於先前的值。

ASP.NET Core 設計成雲端感知，並讓操作員和開發人員更容易設定應用程式。 ASP.NET Core 是環境感知，並知道這是否在Production或Development環境中執行。環境指標是在ASPNETCORE_ENVIRONMENT系統環境變數中設定。如果未設定任何值，應用程式預設會在Production環境中執行。

您的應用程式可以根據環境的名稱，從數個來源觸發和新增設定。根據預設，本設定會依列出的順序從下列資源載入：

appsettings.json 檔案 (如果有的話)
appsettings.{ENVIRONMENT_NAME}.json 檔案 (如果有的話)
磁碟上的使用者祕密檔案 (如果有的話)
環境變數
命令列引數

appsettings.json 格式和存取

appsettings.json 檔案可以是階層式檔案，其中的結構類似下列 JSON：

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

呈現上述 JSON 時，設定系統會扁平化子值，並參考其中的完整階層式路徑。冒號 (:) 字元會分隔階層中的每個屬性。例如，設定索引鍵section1:key0會存取section1物件常值的key0值。

使用者祕密

使用者祕密如下：

儲存在開發人員工作站上的 JSON 檔案中的設定值，位於應用程式開發資料夾之外。
只有在Development環境中執行時才會載入。
與特定應用程式相關聯。
使用 .NET CLI 的user-secrets命令進行管理。

執行user-secrets命令來設定您的應用程式以儲存祕密：

dotnet user-secrets init

上述命令會將UserSecretsId元素新增至專案檔。元素包含 GUID，用來將祕密與應用程式產生關聯。接著，您可以使用set命令來定義祕密。例如：

dotnet user-secrets set "Parent:ApiKey" "12345"

上述命令會讓Parent:ApiKey設定金鑰可在開發人員的工作站上使用，其值為12345。

如需建立、儲存和管理使用者祕密的詳細資訊，請參閱在開發環境中安全地在 ASP.NET Core 中儲存應用程式祕密文件。

環境變數

載入應用程式設定的下一組值是系統的環境變數。您所有的系統內容變數設定現在都可透過設定 API 存取。在應用程式內讀取時，會將階層式值壓平合併並以冒號字元分隔。不過，某些作業系統不允許冒號字元環境變數名稱。 ASP.NET Core 會將有雙底線的值 (__) 轉換成冒號，以解決這項限制。上述使用者祕密區段的Parent:ApiKey值可以使用環境變數Parent__ApiKey覆寫。

命令列引數

您的應用程式啟動時，也能夠以命令列引數的形式提供設定。使用雙虛線 (--) 或正斜線 (/) 標記法來表示要設定的設定值名稱和要設定的值。語法類似下列命令：

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890

web.config 的傳回

如果您已將應用程式部署至 IIS 上的 Windows，web.config 檔案仍會將 IIS 設定為管理您的應用程式。根據預設，IIS 會將參考新增至 ASP.NET Core Module (ANCM)。 ANCM 是原生 IIS 模組，可裝載您的應用程式來取代 Kestrel 網頁伺服器。此 web.config 區段類似下列 XML 標記：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

應用程式特定的設定可以藉由將aspNetCore元素中的environmentVariables元素進行巢狀處理來加以定義。本節中定義的值會以環境變數的形式呈現在 ASP.NET Core 應用程式。環境變數會在應用程式啟動的該區段期間適當載入。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="Parent:ApiKey" value="67890" />
  </environmentVariables>
</aspNetCore>

讀取應用程式中的設定

ASP.NET Core 透過IConfiguration介面提供應用程式設定。您的Blazor元件、Blazor頁面以及需要存取設定的其他任何 ASP.NET Core 管理類別都應該要求此設定介面。 ASP.NET Core 架構會自動將此介面填入稍早設定的已解析設定。在Blazor頁面或元件的 Razor 標記上，您可以將IConfiguration物件與@inject指示詞插入 .razor 檔案頂端，如下所示：

@inject IConfiguration Configuration

上述陳述式可讓IConfiguration物件在整個 Razor 範本的其餘部分以Configuration變數的形式提供。

您可以藉由指定搜尋，為索引子參數的組態設定階層讀取個別組態設定：

var mySetting = Configuration["section1:key0"];

您可以使用GetSection方法來擷取特定位置的索引鍵集合，其語法類似於GetSection("section1")從先前範例擷取 section1 的設定，以擷取整個設定區段。

強型別設定

透過 Web Form，可以建立繼承自ConfigurationSection型別和相關聯型別的強型別設定型別。 ConfigurationSection可讓您為這些設定值設定一些商務規則和處理。

在 ASP.NET Core 中，您可以指定將接收設定值的類別階層。這些類別：

不需要從父代類別繼承。
應該包含與您想要擷取設定結構所用屬性和型別參考相符的public屬性。

針對先前的 appsettings.json 範例，您可以定義下列類別來擷取值：

public class MyConfig
{
    public MyConfigSection section0 { get; set;}

    public MyConfigSection section1 { get; set;}
}

public class MyConfigSection
{
    public string key0 { get; set; }

    public string key1 { get; set; }
}

可以將下列這一行新增至Startup.ConfigureServices方法 (或 Program.cs 中的適當位置，使用builder.Services屬性而非services) 以填入此類別階層：

services.Configure<MyConfig>(Configuration);

在應用程式的其餘部分，您可以將輸入參數新增至型別IOptions<MyConfig>的類別或 Razor 範本中的@inject指示詞，以接收強型別組態設定。 IOptions<MyConfig>.Value屬性會暫止從組態設定填入的MyConfig值。

@inject IOptions<MyConfig> options
@code {
    var MyConfiguration = options.Value;
    var theSetting = MyConfiguration.section1.key0;
}

如需選項功能的詳細資訊，請參閱ASP.NET Core 中的選項模式文件。

上一個下一個

共用方式為