《ASP.ENT Core 與 RESTful API 開發實戰》（第3章）-- 讀書筆記（下）
2021-10-22 16:47:09

第 3 章 ASP.NET Core 核心特性

3.5 配置

要訪問配置，需要使用 ConfigurationBinder 類，它實現了 IConfigurationBuilder 接口，該接口包括兩個重要的方法：

public interface IConfigurationBuilder
{
    // 添加不同形式的配置源
    IConfigurationBuilder Add(IConfigurationSource source);
    // 把所有添加的配置源中的配置信息構建（或生成）為程序可訪問的配置項
    IConfigurationRoot Build();
}

訪問 JSON 配置文件

{
  "FontFamily": "Arial",
  "FontSize": 16,
  "Editor": {
    "Background": "#F4F4F4",
    "Foreground": "Black" 
  } 
}

在 Main 函數中訪問

var builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("UISetting.json");

var config = builder.Build();
foreach (var item in config.AsEnumerable())
{
    Console.WriteLine($"Key: {item.Key}, Value: {item.Value}");
}

// 通過指定 Key 來訪問其配置項值
Console.WriteLine("FontFamily: " + config["FontFamily"]);
Console.WriteLine("FontSize: " + config.GetValue<int>("FontSize"));
Console.WriteLine("Editor Foreground: " + config["Editor:Foreground"]);

// 對于層級結構，使用 GetSession
var editorSection = config.GetSection("Editor");
Console.WriteLine("Editor Background: " + editorSection["Background"]);

Console.Read();

添加其他類型的配置文件：

• AddXmlFile
• AddIniFile
• AddInMemoryCollection
• AddEnvironmentVariables

另外需要注意的是：

• 配置項鍵名不區分大小寫
• 同一類型的配置源可以添加多個
• 可以通過雙下劃線代替冒號

如果希望改變上述添加配置的方式，可以創建 ConfigurationBuilder 實例并調用 IWebHostBuilder 接口的 UseConfiguration 方法

除了使用 UseConfiguration 方法之外，還可以使用 IWebHostBuilder 接口的 ConfigureAppConfiguration 方法，通過該方法，可以獲取當前的運行環境，并加載與環境相關的配置文件

自定義配置源，需要用到兩個接口，即 IConfigurationSource 和 IConfigurationProvider

由于 ASP.NET Core 提供的配置源中并不支持對 web.config 或 app.config 等這種傳統類型的配置文件的訪問，因此需要創建自定義配置源來訪問，當配置源基于文件時，可以使用 FileConfigurationSource 和 FileConfigurationProvider

重新加載配置可以調用 IConfiguration 或 IConfigurationRoot 的 Reload 方法，即 config.Reload()，或者在添加配置源時指定 reloadOnChange 屬性

強類型對象，我們希望將多個配置映射為具有同名屬性的 .NET 對象，需要使用 Options 模式，在 ConfigureServices 方法內添加

services.Configure<UISetting>(Configuration);

這樣不僅將配置信息映射到 UISetting 類，而且也會將 IOptions 對象放入當前應用程序的依賴注入容器中，因此，可以在 Controller 中注入該對象，并通過它的 Value 屬性獲取 IOptions 所包含的對象

最后，需要說明一點的是，要映射的類必須具有一個默認的構造函數，即公共且無參數的構造函數，否則無法編譯通過

要將配置添加到容器，還可以使用 IServiceCollection.Configure 方法的另一個重載形式，它接受一個 Action 類型的參數

除了 Configure 方法外，還可以使用 PostConfigure 方法對 TOptions 進行后續的修改操作，此方法會在所有的 Configure 方法后執行

3.6 日志

日志包括兩種類型：

• 系統日志：系統在運行時向外輸出的記錄日志
• 用戶記錄日志：由開發人員在程序適當的位置調用與日志功能相關的 API 輸出的日志

ASP.NET Core 框架內部集成了日志的功能，主要由以下幾個接口組成：

• Ilogger
• IloggerProvider
• IloggerFactory

public interface ILogger
{
    void Log<TState>(
      LogLevel logLevel,
      EventId eventId,
      TState state,
      Exception exception,
      Func<TState, Exception, string> formatter);
    bool IsEnabled(LogLevel logLevel);
    IDisposable BeginScope<TState>(TState state);
}

Log 方法的第一個參數指明了這條信息的級別，ASP.NET Core 日志系統定義了6個級別：

• Trace
• Debug
• Information
• Warning
• Error
• Critical

當 ASP.NET Core 應用程序運行起來，日志組件就會被添加到其依賴注入容器中，因此只要在合適的位置將 ILogger 對象注入進來，即可使用它來記錄日志

在創建 WebHost 時，調用了 CreateDefaultBuilder 方法，在這里可以使用 ILoggingBuilder 接口的擴展方法 AddConsole、AddDebug、AddEnventSourceLogger 分別添加3個日志提供程序，它們提供了不同的輸出位置和形式

ASP.NET Core 默認提供了以下6種日志提供程序：

• Console
• Debug
• EventSource
• EventLog
• TraceSource
• Azure App Service

如果不需要 CreateDefaultBuilder 默認添加的3個日志提供程序，可以調用 ILoggerProvider 接口的 ClearProviders 方法，然后再添加所需要的日志提供程序

ILoggerFacotry 接口用于創建 ILogger 類型的對象

public interface ILoggerFactory : IDisposable
{
    ILogger CreateLogger(string categoryName);
    void AddProvider(ILoggerProvider provider);
}

ILoggerFacotry 與 ILogger 一樣，可以在程序任何位置注入使用

將日志信息進行分組，需要使用 Scope 來實現，ILogger 接口有一個方法，BeginScope(TState state) 用于創建 Scope

要在 scope 中輸出日志，除了創建 scope 外，還要在 ILoggerProvider 對象中啟用這一功能，在添加日志提供程序時可以指定該 ILoggerProvider 的一些選項，例如 ControllerProvidre，只要設置 ConsoleLoggerOptions 的 IncludeScopes 屬性為 true 即可

要設置最低日志級別，同樣需要在 ConfigureLogging 方法中進行設置，此時只要調用 ILoggingBuilder 接口的 SetMinimumLevel 方法即可

值得注意的是，在 LogLevel 的枚舉定義中，還有一個值是 None，該值高于其他所有值，如果指定這個值為最低級別，則所有日志都不會輸出

ILoggerBuilder 接口還提供了 AddFilter 方法，顯示滿足條件的日志

默認情況下，在 appsettings.json 文件中包含了對日志的配置信息，可以調用 AddConfiguration 方法將日志配置加載應用到程序的日志系統中

3.7 錯誤處理

異常處理，ASP.NET Core 中有兩個中間件用來處理異常：

• DeveloperExceptionPageMiddleware
• ExceptionHandlerMiddleware

它們可以通過 Configure 方法中的 IApplicationBuilder 提供的 UseDeveloperExceptionPage 和 UseExceptionHandler 添加

需要強調的是，這兩個中間件都應該在 Configure 方法一開始就添加進來，否則任何在它們之前的代碼所產生的錯誤都不會被它們處理

另外，由這些中間件所輸出的響應的 HTTP 狀態碼均為 500 Internal Server Error

默認情況下，ASP.NET Core 對于狀態碼沒有提供具體的細節，使用 StatusCodePagesMiddleware 則能夠自定義關于這些錯誤狀態碼的細節

如果要自定義顯示結果，則可以調用 UseStatusCodePages 的另一個重載形式