# WatchDog

**Repository Path**: 53100/watch-dog

## Basic Information

- **Project Name**: WatchDog
- **Description**: WatchDog 是一个用于 ASP.Net Core Web 应用程序和 API 的实时消息、事件、HTTP（请求和响应）以及异常记录器和查看器。它允许开发人员记录和查看消息、事件、发送到其 Web 应用程序的 HTTP 请求，以及在 Web 应用程序运行期间捕获的异常，所有功能都支持实时操作。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://github.com/IzyPro/WatchDog
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-01-29
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# WatchDog

[![WatchDog](https://img.shields.io/badge/WatchDog-blueviolet)](https://github.com/IzyPro/WatchDog)
[![版本](https://img.shields.io/nuget/vpre/WatchDog.NET?color=orange)](https://www.nuget.org/packages/WatchDog.NET#versions-tab)
[![下载量](https://img.shields.io/nuget/dt/WatchDog.NET?color=red)](https://www.nuget.org/packages/WatchDog.NET#versions-tab)
[![MIT 许可证](https://img.shields.io/github/license/IzyPro/WatchDog?color=Green)](https://github.com/IzyPro/WatchDog/blob/main/LICENSE)
[![WatchDog](https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Fgithub.com%2FIzyPro%2FWatchDog)](https://twitter.com/intent/tweet?hashtags=WatchDog&original_referer=https%3A%2F%2Fdeveloper.twitter.com%2F&ref_src=twsrc%5Etfw%7Ctwcamp%5Ebuttonembed%7Ctwterm%5Eshare%7Ctwgr%5E&related=twitterapi%2Ctwitter&text=Hello%2C%20world!%0DCheck%20out%20this%20awesome%20developer%20tool&url=https%3A%2F%2Fgithub.com%2FIzyPro%2FWatchDog&via=HQWatchdog)


## 简介

`WatchDog` 是一个专为 `ASP.NET Core Web` 应用程序和 `API` 设计的实时消息、事件、HTTP（请求和响应）和异常记录器和查看器。它允许开发人员记录和查看消息、事件、对其 Web 应用程序的 HTTP 请求以及在运行时捕获的异常，全部实时显示。

 `WatchDog` 利用 **SignalR** 实现实时通信，默认使用轻量级数据库 **LiteDB**（无需配置），同时支持扩展至外部数据库（`MSSQL, MySQL, PostgreSQL, MongoDB`）。

## 主要功能

- **实时 HTTP 监控**：记录所有请求和响应的详细信息。
- **异常捕获**：自动捕获并记录应用程序运行时的异常。
- **代码内日志**：支持在业务代码中手动记录消息和事件。
- **实时仪表盘**：提供 `Web` 界面 (`/watchdog`) 查看日志，支持搜索和过滤。
- **多种数据库支持**：内置 `LiteDB`，支持一键切换至主流关系型数据库和 `MongoDB`。
- **日志自动清理**：支持配置定时自动清理旧日志。

## 截图预览

- *登录页面*

![Login](./imgs/login.png)

- *请求与响应查看器*

![请求和响应查看器](./imgs/watchlog.png)

- *异常日志示例*

![异常示例详情](./imgs/exceptionLog.png)

## 安装

### 方式一：.NET CLI

你需要安装 `WatchDog.NET` 包。在终端运行：

```bash
dotnet add package WatchDog.NET --version 1.4.12
```

### 方式二：NuGet 包管理器

除了 `dotnet cli` 安装，还可以通过 `nuget` 包管理器安装：

```bash
Install-Package WatchDog.NET --version 1.4.12
```


### 方式三：源码编译（推荐）

由于当前 `NuGet` 最新公开版本（`1.4.12`）存在安全隐患，且该项目已升级支持 **.NET 10**（支持 `.NET 8` 和 `.NET 10`），建议拉取源码自行编译打包。

```bash
# 克隆仓库
git clone https://gitee.com/dolayout/watch-dog.git
# 进入目录构建
cd watch-dog
dotnet pack -c Release --version "1.4.13-preview.1"
```

## 快速开始

### 1. 注册服务

在 `Program.cs` 中注册 `WatchDog` 服务。

```csharp
using WatchDog;

// 在 Program.cs 中 (适用于 .NET 6+)
builder.Services.AddWatchDogServices();
```

### 2. 配置中间件

在 `HTTP` 请求管道中启用 `WatchDog` 中间件。**注意顺序非常重要**。

```csharp
var app = builder.Build();

// 使用 WatchDog 异常记录器
app.UseWatchDogExceptionLogger();
...

// 建议在 UseRouting, UseAuthentication, UseAuthorization 之后添加
app.UseWatchDog(opt =>
{
   // 设置查看器的登录账号
   opt.WatchPageUsername = "admin";
   opt.WatchPagePassword = "Qwerty@123";
});
```

> 注意：在主要 WatchDog 中间件之前添加异常记录器，最好是在中间件层次结构的顶部，以便捕获可能的早期异常。

### 3. 查看日志

启动你的应用程序，访问 `/watchdog` 路径（例如：`https://localhost:5000/watchdog`），使用配置的用户名和密码登录即可查看实时日志。

## 进阶配置

### 设置外部数据库（可选）

`WatchDog` 默认使用 `LiteDB`。如果需要使用 `MySQL, PostgreSQL, MSSQL` 或 `MongoDB`，请按以下方式配置：

```csharp
services.AddWatchDogServices(opt =>
{
   // 选择数据库驱动类型
   opt.DbDriverOption = WatchDogDbDriverEnum.PostgreSql;
   // 设置外部数据库连接字符串
   opt.SetExternalDbConnString = "Server=localhost;Database=WatchDogDb;User Id=postgres;Password=root;";
});
```

### 设置自动清除日志（可选）

```csharp
services.AddWatchDogServices(opt =>
{
   opt.IsAutoClear = true; // 开启自动清除
   opt.ClearTimeSchedule = WatchDogAutoClearScheduleEnum.Weekly; // 清除频率，默认每周
});
```

### 可选配置项

在 `app.UseWatchDog()` 中可以配置更多选项：

```csharp
app.UseWatchDog(opt =>
{
   opt.WatchPageUsername = "admin";
   opt.WatchPagePassword = "Qwerty@123";

   // 可选配置项：
   // 黑名单：逗号分隔的路径，不记录这些指定 Endpoint 端点/接口
   opt.Blacklist = "Test/testPost, api/auth/login";
   // JSON 序列化器：如果项目使用了 NewtonsoftJson，需要指定
   opt.Serializer = WatchDogSerializerEnum.Newtonsoft;
   // CORS 策略名称
   opt.CorsPolicy = "MyCorsPolicy";
   // 应用程序使用 asp.net core8+ 输出缓存
   opt.UseOutputCache = true;
   // 启用正则表达式黑名单
   opt.UseRegexForBlacklisting = true;
 });
```

### 记录自定义日志

你可以在代码的任何位置调用 `WatchLogger` 来记录日志：

```csharp
using WatchDog;

// 记录普通信息
WatchLogger.Log("用户登录成功");

// 记录警告
WatchLogger.LogWarning("请求频率过高");

// 记录错误
WatchLogger.LogError("处理订单失败", eventId: "Order_001");
```

### 集成 Microsoft ILogger

你还可以将标准的 `ILogger` 日志汇总到 `WatchDog` 中：

```csharp
// .NET 6+ 在 Program.cs 中配置
builder.Logging.AddWatchDogLogger();
```

## 项目结构

该项目主要包含以下模块：

*   `WatchDog/`：核心库源码。
    *   `src/Controllers/`：包含处理日志查看请求的控制器。
    *   `src/Helpers/`：数据库操作辅助类（支持 `LiteDB, SQL, MongoDB`）。
    *   `src/Hubs/`：`SignalR` 集线器，用于实时推送日志。
    *   `src/Models/`：数据模型定义。
    *   `src/Services/`：后台自动清理服务等。
*   `WatchDogCompleteAPITest/`：`API` 项目演示。
*   `WatchDogCompleteMVCTest/`：`MVC` 项目演示。

## 贡献

如果你发现了 `Bug` 或者希望增加新功能：
1.  `Fork` 本仓库。
2.  创建你的特性分支 (`git checkout -b feature/AmazingFeature`)。
3.  提交你的更改 (`git commit -m 'Add some AmazingFeature'`)。
4.  推送到分支 (`git push origin feature/AmazingFeature`)。
5.  发起 `Pull Request`。

## 致谢

*   **Kelechi Onyekwere** - [GitHub](https://github.com/Khelechy) | [Twitter](https://twitter.com/khelechy1337)
*   **Israel Ulelu** - [GitHub](https://github.com/IzyPro) | [Twitter](https://twitter.com/IzyPro_)

---

**许可证**：本项目采用 `MIT` 许可证。