ASP.NET Core 2.2 基础知识(八)【日志记录】

骑猪看日落 2021-06-26 16:06 473阅读 0赞

[ASP.NET][] Core 支持适用于各种内置和第三方日志记录提供程序的日志记录 API。 本文介绍了如何将日志记录 API 与内置提供程序一起使用。

## 添加提供程序 ##

日志记录提供程序会显示或存储日志。 例如，控制台提供程序在控制台上显示日志，Azure Application Insights 提供程序会将这些日志存储在 `Azure Application Insights` 中。 可通过添加多个提供程序将日志发送到多个目标。

要添加提供程序，请在 Program.cs 中调用提供程序的 `Add{provider name}` 扩展方法：

public static void Main(string[] args)
    { 
        var webHost = new WebHostBuilder()
            .UseKestrel()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .ConfigureAppConfiguration((hostingContext, config) =>
            { 
                var env = hostingContext.HostingEnvironment;
                config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                          optional: true, reloadOnChange: true);
                config.AddEnvironmentVariables();
            })
            .ConfigureLogging((hostingContext, logging) =>
            { 
                logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
                logging.AddConsole();
                logging.AddDebug();
                logging.AddEventSourceLogger();
            })
            .UseStartup<Startup>()
            .Build();
    
        webHost.Run();
    }

默认项目模板调用 `CreateDefaultBuilder`扩展方法，该操作将添加以下日志记录提供程序：

*  控制台
 *  调试
 *  EventSource（启动位置：[ASP.NET][] Core 2.2）

public static void Main(string[] args)
    { 
        BuildWebHost(args).Run();
    }
    
    public static IWebHost BuildWebHost(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .Build();

如果使用 `CreateDefaultBuilder`，则可自行选择提供程序来替换默认提供程序。 调用 `ClearProviders`，然后添加所需的提供程序。

public static void Main(string[] args)
    { 
        var host = BuildWebHost(args);
    
        var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
        todoRepository.Add(new Core.Model.TodoItem() {  Name = "Feed the dog" });
        todoRepository.Add(new Core.Model.TodoItem() {  Name = "Walk the dog" });
    
        var logger = host.Services.GetRequiredService<ILogger<Program>>();
        logger.LogInformation("Seeded the database.");
    
        host.Run();
    }
    
    public static IWebHost BuildWebHost(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .ConfigureLogging(logging =>
            { 
                logging.ClearProviders();
                logging.AddConsole();
            })
            .Build();

详细了解`内置日志记录提供程序`，以及本文稍后部分介绍的`第三方日志记录提供程序`。

## 创建日志 ##

从 DI 中获取 `ILogger<TCategoryName>` 对象。

以下控制器示例会创建 `Information` 和 `Warning` 日志。 类别为 `TodoApiSample.Controllers.TodoController`（示例应用中 `TodoController` 的完全限定类名）：

public class TodoController : Controller
    { 
        private readonly ITodoRepository _todoRepository;
        private readonly ILogger _logger;
    
        public TodoController(ITodoRepository todoRepository,
            ILogger<TodoController> logger)
        { 
            _todoRepository = todoRepository;
            _logger = logger;
        }
    }

public IActionResult GetById(string id)
    { 
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
        var item = _todoRepository.Find(id);
        if (item == null)
        { 
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
            return NotFound();
        }
        return new ObjectResult(item);
    }

以下 Razor 页面示例会创建“级别”为 `Information` 且“类别”为 `TodoApiSample.Pages.AboutModel` 的日志：

public class AboutModel : PageModel
    { 
        private readonly ILogger _logger;
    
        public AboutModel(ILogger<AboutModel> logger)
        { 
            _logger = logger;
        }
    }

public void OnGet()
    { 
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation("Message displayed: {Message}", Message);
    }

日志“级别”代表所记录事件的严重程度。 日志“类别”是与每个日志关联的字符串。 `ILogger<T>` 实例会创建“类别”为类型 `T` 的完全限定名称的日志。 本文稍后部分将更详细地介绍`级别`和`类别`。

### 启动时创建日志 ###

要将日志写入 `Startup` 类，构造函数签名需包含 `ILogger` 参数：

public class Startup
    { 
        private readonly ILogger _logger;
    
        public Startup(IConfiguration configuration, ILogger<Startup> logger)
        { 
            Configuration = configuration;
            _logger = logger;
        }
    
        public IConfiguration Configuration {  get; }
    
        public void ConfigureServices(IServiceCollection services)
        { 
            services.AddMvc();
    
            // Add our repository type
            services.AddSingleton<ITodoRepository, TodoRepository>();
            _logger.LogInformation("Added TodoRepository to services");
        }
    
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        { 
            if (env.IsDevelopment())
            { 
                _logger.LogInformation("In Development environment");
                app.UseDeveloperExceptionPage();
            }
            else
            { 
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }
    
            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();
    
            app.UseMvc();
        }
    }

### 在程序中创建日志 ###

要将日志写入 `Program` 类，请从 DI 获取 `ILogger` 实例：

### 没有异步记录器方法 ###

日志记录应该会很快，不值得牺牲性能来使用异步代码。 如果你的日志数据存储很慢，请不要直接写入它。 首先考虑将日志消息写入快速存储，售后再将其变为慢速存储。 例如，记录到由另一进程读取和暂留以减缓存储的消息队列。

## 配置 ##

日志记录提供程序配置由一个或多个配置提供程序提供：

*  文件格式（INI、JSON 和 XML）。
 *  命令行参数。
 *  环境变量。
 *  内存中的 .NET 对象。
 *  未加密的机密管理器存储。
 *  加密的用户存储，如 Azure Key Vault。
 *  （已安装或已创建的）自定义提供程序。

例如，日志记录配置通常由应用设置文件的 `Logging` 部分提供。 以下示例显示了典型 *appsettings.Development.json* 文件的内容：

{ 
      "Logging": { 
        "LogLevel": { 
          "Default": "Debug",
          "System": "Information",
          "Microsoft": "Information"
        },
        "Console":
        { 
          "IncludeScopes": true
        }
      }
    }

`Logging` 属性可具有 `LogLevel` 和日志提供程序属性（显示控制台）。

`Logging` 下的 `LogLevel` 属性指定了用于记录所选类别的最低级别。 在本例中，`System` 和 `Microsoft` 类别在 `Information` 级别记录，其他均在 `Debug` 级别记录。

`Logging` 下的其他属性均指定了日志记录提供程序。 本示例针对控制台提供程序。 如果提供程序支持日志作用域，则 `IncludeScopes` 将指示是否启用这些域。 提供程序属性（例如本例的 `Console`）也可指定 `LogLevel` 属性。 提供程序下的 `LogLevel` 指定了该提供程序记录的级别。

如果在 `Logging.{providername}.LogLevel` 中指定了级别，则这些级别将重写 `Logging.LogLevel` 中设置的所有内容。

若要了解如何实现配置提供程序，请参阅 xref:fundamentals/configuration/index。

## 日志记录输出示例 ##

使用上一部分中显示的示例代码从命令行运行应用时，将在控制台中看到日志。 以下是控制台输出示例：

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
          Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
    info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
          Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
    info: TodoApi.Controllers.TodoController[1002]
          Getting item 0
    warn: TodoApi.Controllers.TodoController[4000]
          GetById(0) NOT FOUND
    info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
          Executing HttpStatusCodeResult, setting HTTP status code 404
    info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
          Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
    info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
          Request finished in 148.889ms 404

通过向 `http://localhost:5000/api/todo/0` 处的示例应用发出 HTTP Get 请求来生成前述日志。

在 Visual Studio 中运行示例应用时，“调试”窗口中将显示如下日志：

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
    Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
    TodoApi.Controllers.TodoController:Information: Getting item 0
    TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
    Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
    Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
    Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

由上一部分所示的 `ILogger` 调用创建的日志是以“`TodoApi.Controllers.TodoController`”开头的。 以“Microsoft”类别开头的日志来自 [ASP.NET][] Core 框架代码。 [ASP.NET][] Core 和应用程序代码使用相同的日志记录 API 和提供程序。

本文余下部分将介绍有关日志记录的某些详细信息及选项。

## NuGet 包 ##

`ILogger` 和 `ILoggerFactory` 接口位于 [Microsoft.Extensions.Logging.Abstractions][] 中，其默认实现位于 [Microsoft.Extensions.Logging][] 中。

## 日志类别 ##

创建 `ILogger` 对象后，将为其指定“类别”。 该类别包含在由此 `Ilogger` 实例创建的每条日志消息中。 类别可以是任何字符串，但约定需使用类名，例如“`TodoApi.Controllers.TodoController`”。

使用 `ILogger<T>` 获取一个 `ILogger` 实例，该实例使用 `T` 的完全限定类型名称作为类别：

public class TodoController : Controller
    {
        private readonly ITodoRepository _todoRepository;
        private readonly ILogger _logger;
    
        public TodoController(ITodoRepository todoRepository,
            ILogger<TodoController> logger)
        {
            _todoRepository = todoRepository;
            _logger = logger;
        }
     }

要显式指定类别，请调用 `ILoggerFactory.CreateLogger`：

public class TodoController : Controller
    { 
        private readonly ITodoRepository _todoRepository;
        private readonly ILogger _logger;
    
        public TodoController(ITodoRepository todoRepository,
            ILoggerFactory logger)
        { 
            _todoRepository = todoRepository;
            _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
        }
    }

`ILogger<T>` 相当于使用 `T` 的完全限定类型名称来调用 `CreateLogger`。

## 日志级别 ##

每个日志都指定了一个 `LogLevel` 值。 日志级别指示严重性或重要程度。 例如，可在方法正常结束时写入 `Information` 日志，在方法返回“404 找不到”状态代码时写入 `Warning` 日志。

下面的代码会创建 `Information` 和 `Warning` 日志：

在上述代码中，第一个参数是`日志事件 ID`。 第二个参数是消息模板，其中的占位符用于填写剩余方法形参提供的实参值。 稍后将在本文的`消息模板部分`介绍方法参数。

在方法名称中包含级别的日志方法（例如 `LogInformation` 和 `LogWarning`）是`ILogger 的扩展方法`。 这些方法会调用可接受 `LogLevel` 参数的 `Log` 方法。 可直接调用 `Log` 方法而不调用其中某个扩展方法，但语法相对复杂。 有关详细信息，请参阅 `ILogger` 和[记录器扩展源代码][Link 1]。

[ASP.NET][] Core 定义了以下日志级别（按严重性从低到高排列）。

*  跟踪 = 0
    
    有关通常仅用于调试的信息。 这些消息可能包含敏感应用程序数据，因此不得在生产环境中启用它们。 默认情况下禁用。
 *  调试 = 1
    
    有关在开发和调试中可能有用的信息。 示例:`Entering method Configure with flag set to true.` 由于日志数量过多，因此仅当执行故障排除时，才在生产中启用 `Debug` 级别日志。
 *  信息 = 2
    
    用于跟踪应用的常规流。 这些日志通常有长期价值。 示例：`Request received for path /api/todo`
 *  警告 = 3
    
    表示应用流中的异常或意外事件。 可能包括不会中断应用运行但仍需调查的错误或其他条件。 `Warning` 日志级别常用于已处理的异常。 示例：`FileNotFoundException for file quotes.txt.`
 *  错误 = 4
    
    表示无法处理的错误和异常。 这些消息指示的是当前活动或操作（例如当前 HTTP 请求）中的失败，而不是整个应用中的失败。 日志消息示例：`Cannot insert record due to duplicate key violation.`
 *  严重 = 5
    
    需要立即关注的失败。 例如数据丢失、磁盘空间不足。

使用日志级别控制写入到特定存储介质或显示窗口的日志输出量。 例如:

*  在生产中，通过 `Information` 级别将 `Trace` 发送到卷数据存储。 通过 `Critical` 级别将 `Warning` 发送到值数据存储。
 *  在开发过程中，通过`Critical` 级别将 `Warning` 发送到控制台，并在进行故障排除时通过 `Information` 级别添加 `Trace`。

本文稍后的`日志筛选`部分介绍如何控制提供程序处理的日志级别。

[ASP.NET][] Core 为框架事件写入日志。 本文前面部分提供的日志示例排除了低于 `Information` 级别的日志，因此未创建 `Debug` 或 `Trace` 级别日志。 以下示例介绍了通过运行配置为显示 `Debug` 日志的示例应用而生成的控制台日志：

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
          Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
    dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
          Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
    dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
          Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
    dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
          Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
    dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
          Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
    info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
          Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
    info: TodoApi.Controllers.TodoController[1002]
          Getting item 0
    warn: TodoApi.Controllers.TodoController[4000]
          GetById(0) NOT FOUND
    dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
          Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
    info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
          Executing HttpStatusCodeResult, setting HTTP status code 404
    info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
          Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
    dbug: Microsoft.AspNetCore.Server.Kestrel[9]
          Connection id "0HL6L7NEFF2QD" completed keep alive response.
    info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
          Request finished in 2.7286ms 404

## 日志事件 ID ##

每个日志都可指定一个事件 ID。 该示例应用通过使用本地定义的 `LoggingEvents` 类来执行此操作：

public class LoggingEvents
    { 
        public const int GenerateItems = 1000;
        public const int ListItems = 1001;
        public const int GetItem = 1002;
        public const int InsertItem = 1003;
        public const int UpdateItem = 1004;
        public const int DeleteItem = 1005;
    
        public const int GetItemNotFound = 4000;
        public const int UpdateItemNotFound = 4001;
    }

事件 ID 与一组事件相关联。 例如，与在页面上显示项列表相关的所有日志可能是 1001。

日志记录提供程序可将事件 ID 存储在 ID 字段中，存储在日志记录消息中，或者不进行存储。 调试提供程序不显示事件 ID。 控制台提供程序在类别后的括号中显示事件 ID：

info: TodoApi.Controllers.TodoController[1002]
          Getting item invalidid
    warn: TodoApi.Controllers.TodoController[4000]
          GetById(invalidid) NOT FOUND

## 日志消息模板 ##

每个日志都会指定一个消息模板。 消息模板可包含要填写参数的占位符。 请在占位符中使用名称而不是数字。

占位符的顺序（而非其名称）决定了为其提供值的参数。 在以下代码中，请注意消息模板中的参数名称未按顺序排列：

string p1 = "parm1";
    string p2 = "parm2";
    _logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

此代码创建了一个参数值按顺序排列的日志消息：

Parameter values: parm1, parm2

日志记录框架按此方式工作，这样日志记录提供程序即可实现[语义日志记录，也称为结构化日志记录][Link 2]。 参数本身会传递给日志记录系统，而不仅仅是格式化的消息模板。 通过此信息，日志记录提供程序能够将参数值存储为字段。 例如，假设记录器方法调用如下所示：

_logger.LogInformation("Getting item {ID} at {RequestTime}", id, DateTime.Now);

如果要将日志发送到 Azure 表存储，则每个 Azure 表实体都可具有 `ID` 和 `RequestTime` 属性，这简化了对日志数据的查询。 无需分析文本消息的超时，查询即可找到特定 `RequestTime` 范围内的全部日志。

## 日志记录异常 ##

记录器方法有可传入异常的重载，如下方示例所示：

catch (Exception ex)
    { 
        _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);

不同的提供程序处理异常信息的方式不同。 以下是上示代码的调试提供程序输出示例。

TodoApi.Controllers.TodoController:Warning: GetById(036dd898-fb01-47e8-9a65-f92eb73cf924) NOT FOUND
    
    System.Exception: Item not found exception.
     at TodoApi.Controllers.TodoController.GetById(String id) in C:\logging\sample\src\TodoApi\Controllers\TodoController.cs:line 226

## 日志筛选 ##

可为特定或所有提供程序和类别指定最低日志级别。 最低级别以下的日志不会传递给该提供程序，因此不会显示或存储它们。

要禁止显示所有日志，可将 `LogLevel.None` 指定为最低日志级别。 `LogLevel.None` 的整数值为 6，它大于 `LogLevel.Critical` 。

### 在配置中创建筛选规则 ###

项目模板代码调用 `CreateDefaultBuilder` 来为控制台和调试提供程序设置日志记录。 `CreateDefaultBuilder` 方法还使用如下所示的代码，设置日志记录以查找 `Logging` 部分的配置：

配置数据按提供程序和类别指定最低日志级别，如下方示例所示：

{ 
      "Logging": { 
        "Debug": { 
          "LogLevel": { 
            "Default": "Information"
          }
        },
        "Console": { 
          "IncludeScopes": false,
          "LogLevel": { 
            "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
            "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
            "Microsoft.AspNetCore.Mvc.Razor": "Error",
            "Default": "Information"
          }
        },
        "LogLevel": { 
          "Default": "Debug"
        }
      }
    }

此 JSON 将创建 6 条筛选规则：1 条用于调试提供程序， 4 条用于控制台提供程序， 1 条用于所有提供程序。 创建 `ILogger` 对象时，为每个提供程序选择一个规则。

### 代码中的筛选规则 ###

下面的示例演示了如何在代码中注册筛选规则：

WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
            logging.AddFilter("System", LogLevel.Debug)
                   .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))
        .Build();

第二个 `AddFilter` 使用类型名称来指定调试提供程序。 第一个 `AddFilter` 应用于全部提供程序，因为它未指定提供程序类型。

### 如何应用筛选规则 ###

先前示例中显示的配置数据和 `AddFilter` 代码会创建下表所示的规则。 前六条由配置示例创建，后两条由代码示例创建。

<table> 
 <thead> 
  <tr> 
   <th align="center">数字</th> 
   <th>提供程序</th> 
   <th>类别的开头为…</th> 
   <th>最低日志级别</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">1</td> 
   <td>调试</td> 
   <td>全部类别</td> 
   <td>信息</td> 
  </tr> 
  <tr> 
   <td align="center">2</td> 
   <td>控制台</td> 
   <td>Microsoft.AspNetCore.Mvc.Razor.Internal</td> 
   <td>警告</td> 
  </tr> 
  <tr> 
   <td align="center">3</td> 
   <td>控制台</td> 
   <td>Microsoft.AspNetCore.Mvc.Razor.Razor</td> 
   <td>调试</td> 
  </tr> 
  <tr> 
   <td align="center">4</td> 
   <td>控制台</td> 
   <td>Microsoft.AspNetCore.Mvc.Razor</td> 
   <td>Error</td> 
  </tr> 
  <tr> 
   <td align="center">5</td> 
   <td>控制台</td> 
   <td>全部类别</td> 
   <td>信息</td> 
  </tr> 
  <tr> 
   <td align="center">6</td> 
   <td>全部提供程序</td> 
   <td>全部类别</td> 
   <td>调试</td> 
  </tr> 
  <tr> 
   <td align="center">7</td> 
   <td>全部提供程序</td> 
   <td>系统</td> 
   <td>调试</td> 
  </tr> 
  <tr> 
   <td align="center">8</td> 
   <td>调试</td> 
   <td>Microsoft</td> 
   <td>跟踪</td> 
  </tr> 
 </tbody> 
</table>

创建 `ILogger` 对象时，`ILoggerFactory` 对象将根据提供程序选择一条规则，将其应用于该记录器。 将按所选规则筛选 `ILogger` 实例写入的所有消息。 从可用规则中为每个提供程序和类别对选择最具体的规则。

在为给定的类别创建 `ILogger` 时，以下算法将用于每个提供程序：

*  选择匹配提供程序或其别名的所有规则。 如果找不到任何匹配项，则选择提供程序为空的所有规则。
 *  根据上一步的结果，选择具有最长匹配类别前缀的规则。 如果找不到任何匹配项，则选择未指定类别的所有规则。
 *  如果选择了多条规则，则采用最后一条。
 *  如果未选择任何规则，则使用 `MinimumLevel`。

假设你使用上述规则列表为类别“`Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine`”创建了 `ILogger` 对象：

*  对于调试提供程序，规则 1、6 和 8 适用。 规则 8 最为具体，因此选择了它。
 *  对于控制台提供程序，符合的有规则 3、规则 4、规则 5 和规则 6。 规则 3 最为具体。

生成的 `ILogger` 实例将 `Trace` 级别及更高级别的日志发送到调试提供程序。 `Debug` 级别及更高级别的日志会发送到控制台提供程序。

### 提供程序别名 ###

每个提供程序都定义了一个别名；可在配置中使用该别名来代替完全限定的类型名称。 对于内置提供程序，请使用以下别名：

*  控制台
 *  调试
 *  EventLog
 *  AzureAppServices
 *  TraceSource
 *  EventSource

### 默认最低级别 ###

仅当配置或代码中的规则对给定提供程序和类别都不适用时，最低级别设置才会生效。 下面的示例演示如何设置最低级别：

WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
        .Build();

如果没有明确设置最低级别，则默认值为 `Information`，它表示 `Trace` 和 `Debug` 日志将被忽略。

### 筛选器函数 ###

对配置或代码没有向其分配规则的所有提供程序和类别调用筛选器函数。 函数中的代码可访问提供程序类型、类别和日志级别。 例如:

WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logBuilder =>
        { 
            logBuilder.AddFilter((provider, category, logLevel) =>
            { 
                if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" && 
                    category == "TodoApiSample.Controllers.TodoController")
                { 
                    return false;
                }
                return true;
            });
        })
        .Build();

## 系统类别和级别 ##

下面是 [ASP.NET][] Core 和 Entity Framework Core 使用的一些类别，备注中说明了可从这些类别获取的具体日志：

<table> 
 <thead> 
  <tr> 
   <th>类别</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Microsoft.AspNetCore</td> 
   <td>常规 <a href="http://ASP.NET" rel="nofollow">ASP.NET</a> Core 诊断。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.AspNetCore.DataProtection</td> 
   <td>考虑、找到并使用了哪些密钥。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.AspNetCore.HostFiltering</td> 
   <td>所允许的主机。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.AspNetCore.Hosting</td> 
   <td>HTTP 请求完成的时间和启动时间。 加载了哪些承载启动程序集。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.AspNetCore.Mvc</td> 
   <td>MVC 和 Razor 诊断。 模型绑定、筛选器执行、视图编译和操作选择。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.AspNetCore.Routing</td> 
   <td>路由匹配信息。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.AspNetCore.Server</td> 
   <td>连接启动、停止和保持活动响应。 HTTP 证书信息。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.AspNetCore.StaticFiles</td> 
   <td>提供的文件。</td> 
  </tr> 
  <tr> 
   <td>Microsoft.EntityFrameworkCore</td> 
   <td>常规 Entity Framework Core 诊断。 数据库活动和配置、更改检测、迁移。</td> 
  </tr> 
 </tbody> 
</table>

## 日志作用域 ##

“作用域”可对一组逻辑操作分组。 此分组可用于将相同的数据附加到作为集合的一部分而创建的每个日志。 例如，在处理事务期间创建的每个日志都可包括事务 ID。

范围是由 `BeginScope`方法返回的 `IDisposable` 类型，持续至释放为止。 要使用作用域，请在 `using` 块中包装记录器调用：

public IActionResult GetById(string id)
    { 
        TodoItem item;
        using (_logger.BeginScope("Message attached to logs created in the using block"))
        { 
            _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
            item = _todoRepository.Find(id);
            if (item == null)
            { 
                _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
                return NotFound();
            }
        }
        return new ObjectResult(item);
    }

下列代码为控制台提供程序启用作用域：

Program.cs:

.ConfigureLogging((hostingContext, logging) =>
    { 
        logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
        logging.AddConsole(options => options.IncludeScopes = true);
        logging.AddDebug();
    })

> 备注  
> 要启用基于作用域的日志记录，必须先配置 `IncludeScopes` 控制台记录器选项。
> 
> 若要了解关配置，请参阅配置部分。

每条日志消息都包含作用域内的信息：

info: TodoApi.Controllers.TodoController[1002]
          => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
          Getting item 0
    warn: TodoApi.Controllers.TodoController[4000]
          => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
          GetById(0) NOT FOUND

## 内置日志记录提供程序 ##

[ASP.NET][] Core 提供以下提供程序：

*  控制台
 *  调试
 *  EventSource
 *  EventLog
 *  TraceSource

本文稍后将介绍 `Azure 的日志记录`选项。

有关 stdout 日志记录的信息，请参阅 `对 IIS 上的 ASP.NET Core 进行故障排除` 和 `对 Azure 应用服务上的 ASP.NET Core 进行故障排除`。

### 控制台提供程序 ###

[Microsoft.Extensions.Logging.Console][] 提供程序包向控制台发送日志输出。

logging.AddConsole();

要查看控制台日志记录输出，请在项目文件夹中打开命令提示符并运行以下命令：

dotnet run

### 调试提供程序 ###

[Microsoft.Extensions.Logging.Debug][] 提供程序包使用`System.Diagnostics.Debug`类（`Debug.WriteLine` 方法调用）来写入日志输出。

在 Linux 中，此提供程序将日志写入 /var/log/message。

logging.AddDebug();

### EventSource 提供程序 ###

对于面向 [ASP.NET][] Core 1.1.0 或更高版本的应用，[Microsoft.Extensions.Logging.EventSource][] 提供程序包可实现事件跟踪。 在 Windows 中，它使用 [ETW][]。 提供程序可跨平台使用，但尚无支持 Linux 或 macOS 的事件集合和显示工具。

logging.AddEventSourceLogger();

可使用 [PerfView 实用工具][PerfView]收集和查看日志。 虽然其他工具也可以查看 ETW 日志，但在处理由 [ASP.NET][] 发出的 ETW 事件时，使用 PerfView 能获得最佳体验。

要将 PerfView 配置为收集此提供程序记录的事件，请向 Additional Providers 列表添加字符串 `*Microsoft-Extensions-Logging`。 （请勿遗漏字符串起始处的星号。）  
![其他 Perfview 提供程序][Perfview]

### `Windows EventLog` 提供程序 ###

[Microsoft.Extensions.Logging.EventLog][] 提供程序包向 Windows 事件日志发送日志输出。

logging.AddEventLog();

### `TraceSource` 提供程序 ###

[Microsoft.Extensions.Logging.TraceSource][] 提供程序包使用 `TraceSource` 库和提供程序。

logging.AddTraceSource(sourceSwitchName);

`AddTraceSource 重载` 允许传入资源开关和跟踪侦听器。

要使用此提供程序，应用必须在 .NET Framework（而非 .NET Core）上运行。 提供程序可将消息路由到多个`侦听器`，例如示例应用中使用的 `TextWriterTraceListener`。

## Azure 中的日志记录 ##

要了解 Azure 中的日志记录，请参阅下列部分：

*  Azure 应用服务提供程序
 *  Azure 日志流式处理
 *  Azure Application Insights 跟踪日志记录

### Azure 应用服务提供程序 ###

[Microsoft.Extensions.Logging.AzureAppServices][] 提供程序包将日志写入 Azure App Service 应用的文件系统，以及 Azure 存储帐户中的 [blob 存储][blob]。 面向 .NET Core 1.1 或更高版本的应用可使用该提供程序包。

如果面向 .NET Core，请注意以下几点：

*  `Microsoft.AspNetCore.App 元包`中不包括此提供程序包。 要使用提供程序，请安装该程序包。
 *  不要显式调用`AddAzureWebAppDiagnostics`。 将应用部署到 Azure 应用服务时，会自动使提供程序对应用可用。

如果面向 .NET Framework 或引用 `Microsoft.AspNetCore.App` 元包，请向项目添加提供程序包。 在 `ILoggerFactory`实例上调用 `AddAzureWebAppDiagnostics`：

logging.AddAzureWebAppDiagnostics();

`AddAzureWebAppDiagnostics`重载允许传入 `AzureAppServicesDiagnosticsSettings`。 设置对象可以覆盖默认设置，例如日志记录输出模板、blob 名称和文件大小限制。 （“输出模板”是一个消息模板，除了通过 `ILogger` 方法调用提供的内容之外，还可将其应用于所有日志。）

在部署应用服务应用时，应用程序将遵循 Azure 门户中“应用服务”页面下的`诊断日志`部分的设置。 更新这些设置后，更改会立即生效，无需重新启动或重新部署应用。  
![在这里插入图片描述][20190219180016846.png]  
日志文件的默认位置是 D:\\home\\LogFiles\\Application 文件夹，默认文件名为 diagnostics-yyyymmdd.txt。 默认文件大小上限为 10 MB，默认最大保留文件数为 2。 默认 blob 名为 \{app-name\}\{timestamp\}/yyyy/mm/dd/hh/\{guid\}-applicationLog.txt。 要详细了解默认行为，请参阅 `AzureAppServicesDiagnosticsSettings`。

该提供程序仅当项目在 Azure 环境中运行时有效。 项目在本地运行时，该提供程序无效 — 它不会写入本地文件或 blob 的本地开发存储。

### Azure 日志流式处理 ###

通过 Azure 日志流式处理，可从以下位置实时查看日志活动：

*  应用服务器
 *  Web 服务器
 *  请求跟踪失败

要配置 Azure 日志流式处理，请执行以下操作：

*  从应用的门户页导航到“诊断日志”页。
 *  将“应用程序日志记录(Filesystem)”设置为“开”。  
    ![在这里插入图片描述][20190219180120455.png]  
    导航到“日志流式处理”页，查看应用消息。 它们由应用通过 `ILogger` 接口记录。  
    ![在这里插入图片描述][20190219180143631.png]

### `Azure Application Insights` 跟踪日志记录 ###

Application Insights SDK 可收集和报告 [ASP.NET][] Core 日志记录基础结构生成的日志。 有关更多信息，请参见以下资源：

*  Application Insights 概述
 *  用于 [ASP.NET][] Core 的 Application Insights
 *  [Application Insights 日志记录适配器][Application Insights]。

## 第三方日志记录提供程序 ##

适用于 [ASP.NET][] Core 的第三方日志记录框架：

*  [elmah.io][]（[GitHub 存储库][GitHub]）
 *  [Gelf][]（[GitHub 存储库][GitHub 1]）
 *  [JSNLog][]（[GitHub 存储库][GitHub 2]）
 *  [KissLog.net][]（[GitHub 存储库][GitHub 3]）
 *  [Loggr][]（[GitHub 存储库][GitHub 4]）
 *  [NLog][]（[GitHub 存储库][GitHub 5]）
 *  [Sentry][]（[GitHub 存储库][GitHub 6]）
 *  [Serilog][]（[GitHub 存储库][GitHub 7]）
 *  [Stackdriver][]（[Github 存储库][Github]）

某些第三方框架可以执行[语义日志记录（又称结构化日志记录）][Link 2]。

使用第三方框架类似于使用以下内置提供程序之一：

1.  将 NuGet 包添加到你的项目。
2.  调用 `ILoggerFactory`。

有关详细信息，请参阅各提供程序的相关文档。 Microsoft 不支持第三方日志记录提供程序。

[ASP.NET]: http://ASP.NET
[Microsoft.Extensions.Logging.Abstractions]: https://www.nuget.org/packages/Microsoft.Extensions.Logging.Abstractions/
[Microsoft.Extensions.Logging]: https://www.nuget.org/packages/microsoft.extensions.logging/
[Link 1]: https://github.com/aspnet/Extensions/blob/release/2.2/src/Logging/Logging.Abstractions/src/LoggerExtensions.cs
[Link 2]: https://softwareengineering.stackexchange.com/questions/312197/benefits-of-structured-logging-vs-basic-logging
[Microsoft.Extensions.Logging.Console]: https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console
[Microsoft.Extensions.Logging.Debug]: https://www.nuget.org/packages/Microsoft.Extensions.Logging.Debug
[Microsoft.Extensions.Logging.EventSource]: https://www.nuget.org/packages/Microsoft.Extensions.Logging.EventSource
[ETW]: https://msdn.microsoft.com/library/windows/desktop/bb968803
[PerfView]: https://github.com/Microsoft/perfview
[Perfview]: /images/20210626/04b06d5ee5ea473bb2dc5a89d52cf8c3.png
[Microsoft.Extensions.Logging.EventLog]: https://www.nuget.org/packages/Microsoft.Extensions.Logging.EventLog
[Microsoft.Extensions.Logging.TraceSource]: https://www.nuget.org/packages/Microsoft.Extensions.Logging.TraceSource
[Microsoft.Extensions.Logging.AzureAppServices]: https://www.nuget.org/packages/Microsoft.Extensions.Logging.AzureAppServices
[blob]: https://azure.microsoft.com/documentation/articles/storage-dotnet-how-to-use-blobs/#what-is-blob-storage
[20190219180016846.png]: /images/20210626/d95cda8a044c49509b39d6b2ccf5debe.png
[20190219180120455.png]: /images/20210626/d31770979d0b4be982e630cfcb16fc5e.png
[20190219180143631.png]: /images/20210626/9b79c8ca40db4ace97ab8d5319f6c60c.png
[Application Insights]: https://github.com/Microsoft/ApplicationInsights-dotnet-logging/blob/develop/README.md
[elmah.io]: https://elmah.io/
[GitHub]: https://github.com/elmahio/Elmah.Io.Extensions.Logging
[Gelf]: http://docs.graylog.org/en/2.3/pages/gelf.html
[GitHub 1]: https://github.com/mattwcole/gelf-extensions-logging
[JSNLog]: http://jsnlog.com/
[GitHub 2]: https://github.com/mperdeck/jsnlog
[KissLog.net]: https://kisslog.net/
[GitHub 3]: https://github.com/catalingavan/KissLog-net
[Loggr]: http://loggr.net/
[GitHub 4]: https://github.com/imobile3/Loggr.Extensions.Logging
[NLog]: http://nlog-project.org/
[GitHub 5]: https://github.com/NLog/NLog.Extensions.Logging
[Sentry]: https://sentry.io/welcome/
[GitHub 6]: https://github.com/getsentry/sentry-dotnet
[Serilog]: https://serilog.net/
[GitHub 7]: https://github.com/serilog/serilog-extensions-logging
[Stackdriver]: https://cloud.google.com/dotnet/docs/stackdriver#logging
[Github]: https://github.com/googleapis/google-cloud-dotnet