如何将日志消息输出到控制台上

一、ConsoleLogger

如下所示的代码片段展示了由
ConsoleLoggerProvider提供的这个ConsoleLogger类型的定义。ConsoleLogger具有四个属性，代表
Logger名称的Name属性最初由ConsoleLoggerProvider提供，实际上就是LoggerFactory在创建Logger时指定
的日志类型。出于对跨平台的支持，ConsoleLogger对不同平台下控制台进行了抽象并使用接口IConsole来表示，所示代码当前控制台的
Console属性的类型为IConsole。Funcbool>类型的Filter属性提供了一个针对日志类型与等级的过滤条件，是否真正需要将提供的日志消息输出到控制台就由这个过滤条件来决定。最
后一个属性IncludeScopes与上面提到的关联多次日志记录的上下文范围有关，我们后续内容中对此进行单独介绍。

1: public class ConsoleLogger : ILogger
2: {
3: public string Name { get; }
4: public IConsole Console { get; set; }
5: public Func Filter { get; set; }
6: public bool IncludeScopes { get; set; }
7:
8: public ConsoleLogger(string name, Func filter, bool includeScopes);public IDisposable BeginScope(TState state);
9:
10: public bool IsEnabled(LogLevel logLevel);
11: public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func formatter);
12: public virtual void WriteMessage(LogLevel logLevel, string logName, int eventId, string message);
13: }

对于ConsoleLogger的这四个属性，除了表示当前控制台的Console属性，其余三个均可以在创建它的时候通过构造函数的相应参数来指
定。接下来我们来了解一下用于抽象不同平台控制台的IConsole接口，如下面的代码片段所示，IConsole接口具有如下三个方法。在调用
Write和WriteLine方法写入日志的时候，我们除了指定写入的消息文本之外，还可以控制消息在控制台上的背景和前景颜色。Flush方法与数据
输出缓冲机制有关，如果采用缓冲机制，通过Write或者WriteLine方法写入的消息并不会立即输出到控制台，而是先被保存到缓冲区，Flush方
法被执行的时候会将缓冲区的所有日志消息批量输出到控制台上。

1: public interface IConsole
2: {
3: void Write(string message, ConsoleColor? background, ConsoleColor? foreground);
4: void WriteLine(string message, ConsoleColor? background, ConsoleColor? foreground);
5: void Flush();
6: }

微软默认提供了两种类型的Console类型，一种是基于Windows平台的WindowsLogConsole，非Windows平台的控制台
则通过AnsiLogConsole来表示。它们之间的不同之处在于对日志消息在控制台上显示颜色（前景色和背景色）的控制。对于Windows平台来
说，消息显示在控制台颜色是通过显式设置System.Console的静态属性ForegroundColor和BackgroundColor来实现
的，但是对于非Windows平台来说，颜色信息会直接以基于ASNI标准的转意字符序列（ANSI Esacpe
Sequences）的形式内嵌在消息文本之中）。
ConsoleLogger的IsEnabled方法最终决定了是否需要真正完成对提供日志的写入操作，这方法是由Filter属性返回的
委托对象的执行结果。当Log方法执行的时候，它会先调用IsEnabled方法，如果这个方法返回True，它调用另一个WriteMessage方法
将提供的日志消息输出到由Console属性表示的控制台上。WriteMessage方法是一个虚方法，如果它输出的消息格式和样式不满足我们的要求，
我们可以定义ConsoleLogger的子类，并通过重写这个方法按照我们希望的方式输出日志消息。

1: {LogLevel} : {Category}[{EventId}]
2: {Message}

在默认情况下，被ConsoleLogger输出到控制台上的日志消息会采用上面的格式，这也可以通过我们在上面演示的实例来印证。对于输出到控制
台表示日志等级的部分，输出的文字与对应的日志等级具有如表1所示的映射关系，可以看出日志等级在控制台上均会显示为仅包含四个字母的简写形式。日志等级
也同时决定了改部分内容在控制台上显示的前景色。

二、ConsoleLogScope

在默认情况下针对Log方法的每次调用都是一次独立的日志记录行为，但是在很多情况下多次相关的日志记录需要在同一个上下文范围中进行，我们可以通
过调用Logger的BeginScope方法来创建这个上下文范围。对于ConsoleLogger来说，它的BeginScope方法创建的上下文范
围与一个具有如下定义的ConsoleLogScope类有关。

1: public class ConsoleLogScope
2: {
3: internal ConsoleLogScope(string name, object state);
4: public static IDisposable Push(string name, object state);
5: public override string ToString();
6:
7: public static ConsoleLogScope Current { get; set; }
8: public ConsoleLogScope Parent { get; set; }
9: }

我们说ConsoleLogger的BeginScope方法返回的日志上下文范围与ConsoleLogScope有关，但并没有说该方法返回的
是一个ConsoleLogScope对象，关于这一点从上面给出的ConsoleLogScope类型定义也可以看出来，BeginScope方法返回
类型为IDisposable接口，但是ConsoleLogScope并未实现该接口。如上面的代码片段所示，ConsoleLogScope只定义了
一个内部构造函数，所以我们不可以直接调用构造函数创建一个ConsoleLogScope对象，ConsoleLogScope的创建实现在它的静态方
法Push中，ConsoleLogger的BeginScope方法的返回值其实就是针对这方法的调用结果。
要了解实现在Push方法中针对ConsoleLogScope的创建逻辑，需要先来了解一下ConsoleLogScope的嵌套层次结
构。一个ConsoleLogScope可以内嵌于另一个ConsoleLogScope之中，后者被称为前者的“父亲”，它的Parent属性返回的就
是这么一个对象。ConsoleLogScope的静态属性Current表示当前的ConsoleLogScope，当我们通过指定name和
state这两个参数调用静态方法Push时，该方法实际上会调用静态构造函数创建一个新的ConsoleLogScope对象并将其作为当前
ConsoleLogScope的“儿子”。于此同时，当前ConsoleLogScope被切换成这个新创建的ConsoleLogScope。
ConsoleLogScope的Push方法最终返回的是一个DisposableScope对象。如下面的代码片段所
示，DisposableScope仅仅是内嵌于ConsoleLogScope的一个私有类型。当它的Dispose方法执行的时候，它仅仅是获取当前
ConsoleLogScope的“父亲”，并将后者作为当前ConsoleLogScope。

1: public class ConsoleLogScope
2: {
3: public static IDisposable Push(string name, object state)
4: {
5: ConsoleLogScope current = Current;
6: Current = new ConsoleLogScope(name, state);
7: Current.Parent = current;
8: return new DisposableScope();
9: }
10:
11: private class DisposableScope : IDisposable
12: {
13: public void Dispose()
14: {
15: ConsoleLogScope.Current = ConsoleLogScope.Current.Parent;
16: }
17: }
18: }

简单地说，我们调用ConsoleLogScope的Push方法创建当前日志上下文范围并返回一个DisposableScope对象，后者的
Dispose方法的调用意味着这个上下文范围的终结。与此同时，原来的ConsoleLogScope从新成为当前的上下文范围。下面的代码片段体现了
基于ConsoleLogScope的作用域控制方法，这段代码来体现另一个细节，那就是ConsoleLogScope的ToString方法被重写，
它返回的是ConsoleLogScope对象被创建时指定的State对象（state参数）的字符串形式（调用ToString方法的返回值）。

1: using (ConsoleLogScope.Push("App", "Scope1"))
2: {
3: Debug.Assert("Scope1" == ConsoleLogScope.Current.ToString());
4: using (ConsoleLogScope.Push("App", "Scope1"))
5: {
6: Debug.Assert("Scope2" == ConsoleLogScope.Current.ToString());
7: }
8: Debug.Assert("Scope1" == ConsoleLogScope.Current.ToString());
9: }

当ConsoleLogger的BeginScope方法被执行的时候，它会将自己的名称（Name属性）和指定的State对象作为参数调用
ConsoleLogScope的静态方法Push。只要我们没有调用返回对象的Dispose方法，就可以表示当前日志上下文范围的
ConsoleLogScope对象，这个对象和我们指定的State对象的ToString方法返回相同的字符串。

1: public class ConsoleLogger : ILogger
2: {
3: public IDisposable BeginScope(TState state)
4: {
5: return ConsoleLogScope.Push(this.Name, state);
6: }
7: }

如果一个ConsoleLogger对象的IncludeScopes属性返回True，意味着我们希望针对它的日志记录会在一个预先创建的日志上
下文范围中执行执行，输出到控制台的日志消息会包含当前上下文范围的信息。在次情况下，ConsoleLogger会采用如下的格式呈现输出在控制台上的
日志消息，其中{State}表示调用BeginScope方法传入的State对象。

1: {LogLevel} : {Category}[{EventId}]
2: =>{State}
3: {Message}

比如在一个处理订购订单的应用场景中，需要将针对同一笔订单的多条日志消息关联在一起，我们就可以针对订单的ID创建一个日志上下文范围，并在此上下文范围内调用Logger对象的Log方法进行日志记录，那么订单ID将会包含在每条写入的日志消息中。

1: ILogger logger = new ServiceCollection()
2: .AddLogging()
3: .BuildServiceProvider()
4: .GetService()
5: .AddConsole(true)
6: .CreateLogger("App");
7:
8: using (logger.BeginScope("订单: {ID}", "20160520001"))
9: {
10: logger.LogWarning("商品库存不足(商品ID: {0}, 当前库存:{1}, 订购数量:{2})", "9787121237812",20, 50);
11: logger.LogError("商品ID录入错误(商品ID: {0})","9787121235368");
12: }

如上面的代码片段所示，我们按照依赖注入的方式创建了一个注册有ConsoleLoggerProvider的LoggerFactory，并利用
创建了一个Logger对象。在调用注册ConsoleLoggerProvider的AddConsole方法时，我们传入True作为参数，意味着提
供的ConsoleLogger会在当前的日志上下文范围中进行日志记录（它
的IncludeScope属性被设置为True）。我们通过Logger对象记录了两条针对同一笔订单的日志，两次日志记录所在的上下文范围是调用
BeginScope方法根据指定 的订单ID创建的。这段程序执行之后会在控制台上输出如下所示的两条日志消息。