Microsoft.Extensions.Logging.SqlServer

将 .NET 应用日志异步写入 SQL Server，支持高并发缓冲与后台批量入库。自动建表与存储过程，轻松实现集中日志持久化与查询分析。

功能简介

• 异步写入：日志先进入有界通道，后台托管服务消费写库，降低主线程阻塞。
• 自动初始化：首次运行自动创建日志表与存储过程（可自定义名称）。
• 可扩展处理器：默认使用存储过程写入，可实现 ISqlServerMessageHandler 自定义持久化策略。
• 多实例隔离：通过 SqlServerOptions.Key 支持多个 SQL Server 目标并行。
• 动态过滤：Filter 委托按分类与级别过滤日志。
• 连接重建：异常或连接串变化时自动重建 SqlConnection。
• 高性能缓冲：有界通道容量 1000（满时丢弃最旧日志），保障新日志持续写入。

安装方法

通过 NuGet 安装：

dotnet add package Microsoft.Extensions.Logging.SqlServer

快速开始

1. 基础配置（默认处理器）

using Microsoft.Extensions.Logging;

builder.Services.AddLogging(logging =>
{
    logging.AddSqlServer(options =>
    {
        options.ConnectionString = "Server=localhost;Database=LogsDb;Trusted_Connection=True;TrustServerCertificate=True;";
        options.Application = "MyApp";
        options.TableName = "[dbo].[_Log_System]";
        options.PorcName = "[dbo].[_Log_System_Append]";
        options.Key = "Logging.SqlServer";
        options.Filter = (category, level) => level >= LogLevel.Information;
    });
});

第一次运行将自动建表与存储过程。

2. 自定义消息处理器,系统已经默认实现

public class MyHandler : ISqlServerMessageHandler
{
    private readonly IOptionsMonitor<SqlServerOptions> _opt;
    private SqlConnection? _conn;
    public MyHandler(IOptionsMonitor<SqlServerOptions> opt) => _opt = opt;
    public async Task HandleAsync(SqlServerLoggingMessage msg, CancellationToken token = default)
    {
        _conn ??= new SqlConnection(_opt.CurrentValue.ConnectionString);
        if (_conn.State != System.Data.ConnectionState.Open)
            await _conn.OpenAsync(token);
        var sql = $"INSERT INTO {_opt.CurrentValue.TableName}(Application,Machine,Level,EventId,Category,Message,Source,StackTrace,Time) VALUES(@Application,@Machine,@Level,@EventId,@Category,@Message,@Source,@StackTrace,@Time)";
        await _conn.ExecuteAsync(sql, msg);
    }
    public void Dispose() => _conn?.Dispose();
}

// 注册
builder.Services.AddLogging(logging =>
{
    logging.AddSqlServer<MyHandler>(o =>
    {
        o.ConnectionString = "Server=...;Database=LogsDb;Trusted_Connection=True;";
        o.Application = "MyApp";
    });
});

3. 从配置绑定 (appsettings.json)

{
  "Logging": {
    "SqlServer": {
      "ConnectionString": "Server=localhost;Database=LogsDb;Trusted_Connection=True;TrustServerCertificate=True;",
      "Application": "MyApp",
      "TableName": "[dbo].[_Log_System]",
      "PorcName": "[dbo].[_Log_System_Append]",
      "Key": "Logging.SqlServer"
    }
  }
}

builder.Services.AddLogging(logging =>
{
    logging.AddSqlServer(o => builder.Configuration.GetSection("Logging:SqlServer").Bind(o));
});

配置参数说明

表结构 (默认自动创建)

字段：ID(bigint identity, PK), Application, Machine, Level, EventId, Category, Message, Source, StackTrace, Time(datetime)。并包含时间/级别/应用/机器索引。

存储过程示例：PorcName 负责插入一条日志记录。

优势

• 异步缓冲减轻主线程压力
• 自动建表开箱即用
• 可插拔处理器扩展写入策略
• 连接自动重建提升稳定性
• 支持多实例隔离与过滤

注意事项

• 高并发时满队列会丢弃最旧日志（可修改源码调整策略）。
• PorcName 属性命名保持与现有实现一致（拼写 Porc）。
• 建议生产环境提前手工创建表与存储过程并做必要索引优化。

许可证

版权所有 © netor.me
本项目遵循 MIT 协议。

联系方式

• 官网: http://netor.me
• 邮箱: support@netor.me