# DynamicQuartz

**Repository Path**: gitmy/dynamic-quartz

## Basic Information

- **Project Name**: DynamicQuartz
- **Description**: .NET 8 定时服务框架，对Quartz的一个封装，集成NLog，SqlSugar。支持微信通知，支持钉钉通知。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-25
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DynamicQuartz

## 📋 项目介绍

DynamicQuartz 是一个基于 Quartz.NET 的动态任务调度系统，采用 Blazor Server 构建 Web 管理界面，让您只需关注业务逻辑，无需关心调度细节。

### 主要特性

- ✅ **简单易用**：只需继承基类即可创建定时任务
- ✅ **Web 管理界面**：提供 Blazor Server 界面，可视化管理任务
- ✅ **实时监控**：支持任务状态实时查看、立即执行、暂停/恢复
- ✅ **日志管理**：集成 NLog，提供日志查看功能
- ✅ **多数据库支持**：基于 SqlSugar，支持 SQL Server、MySQL、Oracle 等
- ✅ **Windows 服务**：支持作为 Windows 服务运行
- ✅ **Oracle 多线程优化**：已解决 Oracle 数据库在多线程环境下的连接问题

## 🚀 快速开始

### 1. 环境要求

- .NET 8.0 SDK
- 支持的数据库：SQL Server / MySQL / Oracle / PostgreSQL 等

### 2. 配置数据库连接

在 `appsettings.json` 中配置数据库连接字符串：

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Your Connection String Here"
  },
  "ServerSettings": {
    "HostUrl": "http://localhost:11717"
  }
}
```

在 `Program.cs` 中注册 SqlSugar 客户端：

```csharp
var tup = new List<Tuple<string, string, SqlSugar.DbType>>
{
    new ("DefaultConnection", 
         builder.Configuration.GetConnectionString("DefaultConnection"), 
         SqlSugar.DbType.Oracle)  // 或 SqlSugar.DbType.SqlServer, SqlSugar.DbType.MySql 等
};

builder.Services.AddSqlSugarClient(tup);
```

### 3. 创建定时任务

在 `DynamicQuartz.Schedule/BusinessJob` 目录下创建任务类，继承 `QuartzScheduleBase`：

```csharp
using DynamicQuartz.Schedule.Core;
using Quartz;

namespace DynamicQuartz.Schedule.BusinessJob
{
    public class MyCustomJob : QuartzScheduleBase
    {
        public override string JobName => "我的自定义任务";
        
        public override string CronExpression => "0 0/5 * * * ?"; // 每5分钟执行一次
        
        public override async Task ExecuteJob(IJobExecutionContext context)
        {
            // 在这里编写业务逻辑
            Console.WriteLine($"任务执行时间：{DateTime.Now}");
            
            // 如果需要使用数据库
            var db = SqlSugarDataBase.DB("DefaultConnection");
            // var data = db.Queryable<YourEntity>().ToList();
            
            await Task.CompletedTask;
        }
    }
}
```

### 4. 运行项目

```bash
cd DynamicQuartz.Web
dotnet run
```

访问：`http://localhost:11717`

## 📚 项目结构

```
DynamicQuartz/
├── DynamicQuartz.Web/              # Blazor Server Web 项目
│   ├── Pages/                      # Blazor 页面
│   │   ├── FetchData.razor        # 任务管理页面
│   │   └── Log.razor              # 日志查看页面
│   └── Program.cs                 # 程序入口
├── DynamicQuartz.Schedule/         # 任务调度服务
│   ├── BusinessJob/               # 业务任务目录（在这里创建您的任务）
│   └── Core/                      # 调度核心
├── DynamicQuartz.Core/            # 核心领域层
│   └── SqlSugarExtension/         # SqlSugar 扩展
└── DynamicQuartz.Common/          # 公共组件
```

## 🔧 高级配置

### Oracle 数据库多线程配置

本项目已针对 Oracle 数据库在多线程环境（Quartz 定时任务并发）下进行优化，解决了 "Connection must be open for this operation" 错误。

关键配置（已内置）：

```csharp
new ConnectionConfig()
{
    DbType = DbType.Oracle,
    ConnectionString = "your_connection_string",
    IsAutoCloseConnection = true,  // 自动关闭连接（重要）
    MoreSettings = new ConnMoreSettings
    {
        IsAutoRemoveDataCache = true,  // 自动移除数据缓存
        SqlServerCodeFirstNvarchar = true
    }
}
```

### 在任务中使用数据库的最佳实践

**方式一：直接使用（推荐用于简单场景）**
```csharp
public override async Task ExecuteJob(IJobExecutionContext context)
{
    var db = SqlSugarDataBase.DB("DefaultConnection");
    var data = db.Queryable<YourEntity>().ToList();
}
```

**方式二：使用作用域（推荐用于复杂场景）**
```csharp
public override async Task ExecuteJob(IJobExecutionContext context)
{
    var db = SqlSugarDataBase.DB("DefaultConnection");
    
    // 为每个操作创建独立作用域，确保线程安全
    using (var scope = db.CopyNew())
    {
        var data = scope.Queryable<YourEntity>().ToList();
        // 执行其他数据库操作...
    }
}
```

### 作为 Windows 服务运行

项目已集成 Windows 服务支持，发布后可直接注册为服务：

```powershell
# 发布项目
dotnet publish -c Release

# 注册 Windows 服务
sc create DynamicQuartz binPath="E:\path\to\DynamicQuartz.Web.exe"

# 启动服务
sc start DynamicQuartz
```

## 📖 Cron 表达式示例

| 表达式 | 说明 |
|--------|------|
| `0 0/5 * * * ?` | 每5分钟执行一次 |
| `0 0 2 * * ?` | 每天凌晨2点执行 |
| `0 0 0/1 * * ?` | 每小时执行一次 |
| `0 0 12 * * ?` | 每天中午12点执行 |
| `0 0 9-17 * * ?` | 每天9点到17点每小时执行 |
| `0 0 0 * * MON-FRI` | 周一到周五每天0点执行 |

## 📝 功能说明

### 任务管理

- **查看任务列表**：显示所有已注册的定时任务及其状态
- **立即执行**：手动触发任务执行
- **暂停/恢复**：控制任务的执行状态
- **自动刷新**：每30秒自动刷新任务状态

### 日志查看

- 支持在线查看应用程序日志
- 按日期分类查看日志文件
- 实时查看日志内容

## 🛠️ 技术栈

- **前端框架**：Blazor Server (.NET 8)
- **任务调度**：Quartz.NET 3.14.0
- **ORM 框架**：SqlSugar 5.1.4
- **日志框架**：NLog 5.3.10
- **依赖注入**：Microsoft.Extensions.DependencyInjection

## ⚠️ 常见问题

### Q: Oracle 数据库报错 "Connection must be open for this operation"？
**A:** 本项目已解决此问题。确保：
1. 使用最新版本的代码
2. 在 `ConnectionConfig` 中设置 `IsAutoCloseConnection = true`
3. 在并发任务中考虑使用 `db.CopyNew()` 创建独立作用域

### Q: 如何修改 Web 服务监听端口？
**A:** 在 `appsettings.json` 中修改 `ServerSettings:HostUrl` 配置项。

### Q: 任务不执行怎么办？
**A:** 检查：
1. Cron 表达式是否正确
2. 任务是否被暂停
3. 查看日志文件是否有异常信息

## 📄 许可证

本项目遵循 MIT 许可证。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📮 联系方式

- Gitee: https://gitee.com/xuxml/dynamic-quartz

---

**注意**：参考 `DynamicQuartz.Schedule/BusinessJob/TestJob` 示例来创建您的第一个定时任务。