.NET10之内置日志配置与使用指南

ASP.NET Core 内置了开箱即用的日志框架 （基于 ILogger/ILoggerFactory 接口），无需安装任何第三方包，支持控制台、调试器、Windows事件日志等多种输出方式，通过依赖注入（DI）使用，是官方推荐的标准日志方案。

本文基于 .NET 6+ 顶级语句（Program.cs） 编写，适配所有现代 ASP.NET Core 项目。

---

一、核心概念

1. ILogger：日志操作核心接口，负责写入日志
2. 日志提供器：决定日志输出位置（控制台、调试窗口等）
3. 日志级别：控制日志详细程度（从详细到严重）
4. 依赖注入 ：通过构造函数注入 ILogger<T> 使用，无需手动创建

---

二、零配置快速使用（最简方案）

新建 ASP.NET Core 项目后，框架已自动完成日志配置，直接注入即可使用：

1. 控制器中使用日志

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Controllers
{
    public class HomeController : Controller
    {
        // 1. 构造函数注入 泛型日志器（推荐）
        private readonly ILogger<HomeController> _logger;

        public HomeController(ILogger<HomeController> logger)
        {
            _logger = logger;
        }

        public IActionResult Index()
        {
            // 2. 写入不同级别的日志
            _logger.LogInformation("首页被访问了！"); // 常规信息（最常用）
            _logger.LogWarning("这是一条警告日志");
            _logger.LogError("这是一条错误日志");

            return View();
        }
    }
}

2. 运行效果

• 控制台：直接输出日志
• Visual Studio：输出窗口 → 选择 ASP.NET Core Web 服务器 查看日志

---

三、日志级别（必知）

ASP.NET Core 定义了6种日志级别，级别越高，优先级越高：

级别	数值	说明	生产环境建议
Trace	0	最详细日志（包含敏感数据）	❌ 禁用
Debug	1	调试用详细信息	✅ 开发环境
Information	2	默认级别，常规业务信息	✅ 开启
Warning	3	非阻塞性警告	✅ 开启
Error	4	业务异常/错误	✅ 开启
Critical	5	系统崩溃级严重错误	✅ 开启
None	6	关闭所有日志	-

---

四、自定义配置（推荐）

我们可以通过 代码 或 配置文件（appsettings.json） 配置日志级别、输出提供器。

方式1：代码配置（Program.cs）

清除默认配置、自定义输出位置和级别：

var builder = WebApplication.CreateBuilder(args);

// ===================== 内置日志配置 =====================
// 1. 清除框架默认的日志提供器（可选）
builder.Logging.ClearProviders();

// 2. 添加日志输出提供器
builder.Logging.AddConsole();   // 输出到控制台
builder.Logging.AddDebug();     // 输出到VS调试窗口
// builder.Logging.AddEventLog(); // Windows系统事件日志（仅Windows）

// 3. 设置全局默认日志级别
builder.Logging.SetMinimumLevel(LogLevel.Information);

// 4. 针对特定命名空间过滤日志（减少冗余）
builder.Logging.AddFilter("Microsoft", LogLevel.Warning);  // 框架日志只输出警告及以上
builder.Logging.AddFilter("System", LogLevel.Error);      // 系统日志只输出错误及以上

// ========================================================

// 注册控制器/视图（MVC）
builder.Services.AddControllersWithViews();

var app = builder.Build();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

方式2：配置文件配置（appsettings.json）

生产环境首选，无需修改代码，直接修改配置文件：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",                // 全局默认级别
      "Microsoft.AspNetCore": "Warning",       // 框架日志级别
      "MyApp.Controllers": "Debug"             // 自定义命名空间级别（更详细）
    },
    "Console": { // 控制台提供器单独配置
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "AllowedHosts": "*"
}

---

五、高级用法（生产必备）

1. 带参数的结构化日志

不要用字符串拼接 ，使用占位符 {变量名}，支持结构化日志（方便日志分析）：

int userId = 1001;
string userName = "张三";

// 推荐：结构化日志
_logger.LogInformation("用户 {Id} 登录成功，用户名：{Name}", userId, userName);

2. 异常日志

直接传入异常对象，框架会自动打印堆栈信息：

try
{
    throw new Exception("数据库连接失败");
}
catch (Exception ex)
{
    // 第一个参数：异常对象，第二个：日志消息
    _logger.LogError(ex, "获取用户数据时发生异常，用户ID：{Id}", userId);
}

3. 日志作用域（上下文追踪）

为一组日志添加统一上下文（如请求ID、用户ID），方便排查问题：

// 创建日志作用域
using (_logger.BeginScope("请求ID：{RequestId}", Guid.NewGuid()))
{
    _logger.LogInformation("开始处理订单");
    _logger.LogInformation("订单处理完成");
    // 这两条日志都会自动带上 请求ID
}

4. 服务类中使用日志

和控制器用法完全一致，构造函数注入即可：

public class UserService
{
    private readonly ILogger<UserService> _logger;

    public UserService(ILogger<UserService> logger)
    {
        _logger = logger;
    }

    public void AddUser()
    {
        _logger.LogInformation("新增用户成功");
    }
}

---

六、内置日志提供器

官方内置的输出方式（无需第三方包）：

1. AddConsole() → 控制台输出（开发最常用）
2. AddDebug() → Visual Studio 调试窗口输出
3. AddEventLog() → Windows 系统事件日志（仅Windows）
4. AddEventSource() → ETW 事件追踪（高级场景）

---

七、补充：文件日志（内置不支持）

ASP.NET Core 内置日志没有文件输出功能 ，生产环境需要文件日志时，推荐用官方集成的 Serilog（轻量、易用）：

Serilog 快速配置

1. 安装 NuGet 包：

   Serilog.AspNetCore

2. 修改 Program.cs：

   var builder = WebApplication.CreateBuilder(args);
   
   // 替换内置日志为 Serilog
   builder.Host.UseSerilog((context, config) =>
   {
       config
           .WriteTo.Console() // 输出到控制台
           .WriteTo.File("logs/log-.txt", rollingInterval: RollingInterval.Day); // 按天分割文件
   });
   
   builder.Services.AddControllersWithViews();
   var app = builder.Build();
   
   app.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
   app.Run();

✅ 用法不变，依旧注入 ILogger<T> 使用，日志会自动写入文件。

---

总结

1. 开箱即用 ：无需配置，直接注入 ILogger<T> 就能写日志
2. 两种配置 ：代码配置（灵活）+ appsettings.json（生产推荐）
3. 核心用法 ：
   • 构造函数注入日志器
   • 用 LogInformation/LogError 写日志
   • 异常日志直接传入 Exception 对象
4. 生产建议 ：
   • 关闭 Trace/Debug 级别日志
   • 使用结构化日志
   • 用 Serilog 实现文件日志输出