使用.NET 6開發TodoList應用(3)——引入第三方日誌庫

2021 年 12 月 20 日
筆記
.NET 6, .NET基礎系列, WebApi

需求

在我們項目開發的過程中，使用.NET 6自帶的日誌系統有時是不能滿足實際需求的，比如有的時候我們需要將日誌輸出到第三方平台上，最典型的應用就是在各種雲平台上，為了集中管理日誌和查詢日誌，通常會選擇對應平台的日誌SDK進行集成。比如微軟Azure提供的Azure App Service Logging，基礎的用法可以參考這篇文章：ASP.NET Core Logging with Azure App Service and Serilog。同時在這篇文章中也提到了使用Serilog提供的多種Sink，可以實現將日誌寫入不同雲平台或者是非雲平台的日誌存儲中去，這是我們這篇文章講要研究的內容。

目標

我們將為TodoList添加一個方便替換和擴展的日誌策略，簡單來說就是在與具體第三方打交道的Infrastructure項目中實際設置使用的日誌服務，並在Api項目中進行依賴注入，方便在整個應用程式中無具體日誌配置感知地使用日誌服務。

原理和思路

查閱Serilog的官方文檔和一些示例後確定，我們要做的事情有三件：

引入Serilog.AspNetCore包（很多文章或者教程里都讓你根據需要使用的Sink去繼續引入類似Serilog.Sink.File之類的包，但是實際上Serilog.AspNetCore包的依賴項里已經包含了File這個Sink，所以實際上沒有必要再去添加一次）；
二是需要為Serilog的Logger對象提供一個LoggerConfiguration，可以以程式碼的方式進行配置，也可以通過載入.json文件的方式進行配置，看自己的需求和對配置熱更新的有沒有獨特的要求決定；
在程式啟動構造WebApplicationBuilder對象的時候聲明UseSerilog()；
在需要使用日誌的地方注入ILogger<T>對象即可，我們一般是在構造函數里進行注入，當然也可以選擇其他兩種注入方式。

好了，了解了原理，接下來一步就是想一下我們要在哪裡做這幾件事。

在第二篇文章中，我提到了Clean Architecture，裡面有一條原則可以理解為：如果系統需要與外部（第三方）系統進行集成或交互，那麼具體的集成工作應該放入Infrastructure層進行處理，而程式的其他部分只對外部服務進行抽象的使用。好處是今後如果需要替換第三方系統，比如原本日誌是寫到本地文件里，後來有了上雲和日誌集中化處理的需求，需要將日誌服務對接到諸如Azure App Service Logging或者AWS CloudWatch，那麼我們只需要去修改（擴展）Infrastructure中進行日誌具體配置的邏輯就可以了。雖然日誌服務本身相對比較簡單，還不能很好地體現這個優點，我們姑且遵循這個原則，將配置工作放到Infrastructure裡面去。

實現

日誌配置實現

我們在TodoList.Infrastructure項目中新增一個文件夾，取名Log，在其中新建文件ConfigureLogProvider.cs，實現一個針對WebApplicationBuilder的擴展方法，為了演示在這裡配置的擴展性，我多用了一個appsettings.json中的欄位來控制配置過程，缺失的包需要安裝一下。

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Serilog;

namespace TodoList.Infrastructure.Log;

public static class ConfigureLogProvider
{
    public static void ConfigureLog(this WebApplicationBuilder builder)
    {
        if (builder.Configuration.GetValue<bool>("UseFileToLog"))
        {
            // 配置同時輸出到控制台和文件，並且指定文件名和文件轉儲方式（形如log-20211219.txt格式），轉儲文件保留的天數為15天，以及日誌格式
            // 配置Enrich.FromLogContext()的目的是為了從日誌上下文中獲取一些關鍵資訊諸如用戶ID或請求ID，我們的應用中暫時不使用這些。
            Serilog.Log.Logger = new LoggerConfiguration()
                .Enrich.FromLogContext()
                .WriteTo.Console()
                .WriteTo.File(
                    "logs/log-.txt",
                    outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}",
                    rollingInterval: RollingInterval.Day,
                    retainedFileCountLimit: 15)
                .CreateLogger();
        }
        else
        {
            // 僅配置控制台日誌
            Serilog.Log.Logger = new LoggerConfiguration()
                .Enrich.FromLogContext()
                .WriteTo.Console()
                .CreateLogger();
        }

        // 使用Serilog作為日誌框架，注意這裡和.NET 5及之前的版本寫法是不太一樣的。
        builder.Host.UseSerilog();
    }
}

主程式配置

在TodoList.Api項目的Main.cs中，使用該擴展方法：

using TodoList.Infrastructure.Log;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// 配置日誌
builder.ConfigureLog();

builder.Services.AddControllers();
// ... 省略以下

並向appsettings.Development.json文件中添加用於測試的配置項：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "UseFileToLog": true
}

注入使用

嗯……我把第二篇文章結束時刪除的示例WeatherForecastController.cs和WeatherForecast.cs又加回來了。Controller中已經注入了ILogger<WeatherForecastController>，我們就在示例的介面里試一下：

[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get()
{
    // 記錄日誌
    _logger.LogInformation($"maybe this log is provided by Serilog...");

    return Enumerable.Range(1, 5).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .ToArray();
}

好了，到此為止我們就可以驗證一下了。

驗證

運行TodoList.Api項目，和第二篇文章一樣，我們使用Hoppscotch測試示例介面，觀察控制台和日誌文件的輸出內容和格式：

控制台輸出

文件輸出

總結

在這篇文章中，我向大家展示了如何在.NET 6 Web API項目中添加第三方日誌服務框架，下一篇文章將會引入數據存儲服務。

參考資料

系列導航

使用.NET 6開發TodoList應用(1)——系列背景
使用.NET 6開發TodoList應用(2)——項目結構搭建
使用.NET 6開發TodoList應用(3)——引入第三方日誌
使用.NET 6開發TodoList應用(4)——引入數據存儲
使用.NET 6開發TodoList應用(5.0)——領域實體創建和配置
使用.NET 6開發TodoList應用(5.1)——實現CQRS模式
使用.NET 6開發TodoList應用(5.2)——實現AutoMapper
使用.NET 6開發TodoList應用(6)——實現POST請求
使用.NET 6開發TodoList應用(7)——實現GET請求
使用.NET 6開發TodoList應用(8)——實現全局異常處理
使用.NET 6開發TodoList應用(9)——實現PUT請求
使用.NET 6開發TodoList應用(10)——實現PATCH請求
使用.NET 6開發TodoList應用(11)——HTTP請求冪等性的考慮
使用.NET 6開發TodoList應用(12)——實現介面請求驗證
使用.NET 6開發TodoList應用(13)——實現ActionFilter
使用.NET 6開發TodoList應用(14)——實現查詢分頁
使用.NET 6開發TodoList應用(15)——實現查詢過濾
使用.NET 6開發TodoList應用(16)——實現查詢搜索
使用.NET 6開發TodoList應用(17)——實現查詢排序
使用.NET 6開發TodoList應用(18)——實現數據塑形
使用.NET 6開發TodoList應用(19)——實現HATEAOS支援
使用.NET 6開發TodoList應用(20)——處理OPTION和HEAD請求
使用.NET 6開發TodoList應用(21)——實現Root Document
使用.NET 6開發TodoList應用(22)——實現API版本控制
使用.NET 6開發TodoList應用(23)——實現快取
使用.NET 6開發TodoList應用(24)——實現請求限流和閾值控制
使用.NET 6開發TodoList應用(25)——實現基於JWT的Identity功能
使用.NET 6開發TodoList應用(26)——實現RefreshToken
使用.NET 6開發TodoList應用(27)——實現Configuration和Option的強類型綁定
使用.NET 6開發TodoList應用(28)——實現API的Swagger文檔化
使用.NET 6開發TodoList應用(29)——實現應用程式健康檢查
使用.NET 6開發TodoList應用(30)——實現本地化功能
使用.NET 6開發TodoList應用(31)——實現Docker打包和部署
使用.NET 6開發TodoList應用(32)——實現基於Github Actions和ACI的CI/CD

Tags: .NET 6 .NET基礎系列 WebApi