@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/26-1-/346/216/222/347/250/213/344/275/234/346/245/255/345/256/232/346/231/202/344/273/273/345/213/231.md

@@ -0,0 +1,631 @@
+# 26.1 排程作業（定時任務）
+
+> **版本說明**：僅適用於 Furion 4.8.0+（Sundial）。Furion 已內建此功能；非 Furion 框架可安裝 `Sundial` 或 `Sundial.Dashboard`。
+
+---
+
+## 26.1.1 概述
+
+排程作業（定時任務）是指在預設時間點或按設定週期自動觸發執行的任務。應用場景包括：資料備份、定時發送郵件/簡訊、報表生成、資料採集、DevOps 定時發佈等。
+
+---
+
+## 26.1.2 快速入門
+
+### 定義作業處理程式
+
+```csharp
+public class MyJob : IJob
+{
+    private readonly ILogger<MyJob> _logger;
+    public MyJob(ILogger<MyJob> logger) => _logger = logger;
+
+    public Task ExecuteAsync(JobExecutingContext context, CancellationToken stoppingToken)
+    {
+        _logger.LogInformation($"{context}");
+        return Task.CompletedTask;
+    }
+}
+```
+
+### 註冊 Schedule 服務
+
+```csharp
+services.AddSchedule(options =>
+{
+    options.AddJob<MyJob>(Triggers.Secondly());          // 每秒執行
+    options.AddJob<MyJob>("myjob", Triggers.Secondly()); // 指定作業 Id
+});
+```
+
+### 多個觸發器
+
+```csharp
+options.AddJob<MyJob>(
+    Triggers.Minutely(),
+    Triggers.PeriodSeconds(5),
+    Triggers.Cron("3,7,8 * * * * ?", CronStringFormat.WithSeconds));
+```
+
+### 串行執行
+
+```csharp
+options.AddJob<MyJob>(concurrent: false, Triggers.Secondly());
+```
+
+> 串行模式下，若上次未完成則跳過本次觸發。可透過 `options.LogEnabled = false` 關閉跳過警告日誌。
+
+### HTTP 請求作業（4.8.7.7+）
+
+```csharp
+options.AddHttpJob(request =>
+{
+    request.RequestUri = "https://www.chinadot.net";
+    request.HttpMethod = HttpMethod.Get;
+    // request.Body = "{}";
+    // request.Headers.Add("framework", "Furion");
+    // request.Timeout = 100_000;
+    // request.PrintResponseContent = true;
+}, Triggers.PeriodSeconds(5));
+```
+
+### 委託方式（動態）作業
+
+```csharp
+options.AddJob((context, stoppingToken) =>
+{
+    context.ServiceProvider.GetLogger().LogInformation($"{context}");
+    return Task.CompletedTask;
+}, Triggers.PeriodSeconds(5));
+```
+
+### 臨時性作業（4.9.7.67+）
+
+```csharp
+options.AddJob<MyJob>(builder => builder.SetTemporary(), Triggers.PeriodMinutes(5));
+```
+
+### 設定作業組名稱（4.9.2.9+）
+
+```csharp
+options.GroupSet("group1", () =>
+{
+    options.AddJob<MyJob>(Triggers.Secondly());
+    options.AddJob<MyJob>(Triggers.Hourly());
+});
+```
+
+### 觸發器特性掃描
+
+```csharp
+options.AddJob(JobBuilder.Create<MyJob>().SetIncludeAnnotations(true));
+// 或批次掃描
+options.AddJob(App.EffectiveTypes.ScanToBuilders());
+```
+
+```csharp
+[Minutely]
+[PeriodSeconds(5)]
+[Cron("*/3 * * * * *", CronStringFormat.WithSeconds)]
+public class MyJob : IJob { }
+```
+
+### 執行階段動態操作
+
+```csharp
+// 注入 ISchedulerFactory
+_schedulerFactory.AddJob<MyJob>("動態作業 Id", Triggers.Secondly());
+```
+
+### 非 DI 環境使用（4.8.8.5+）
+
+```csharp
+await new ServiceCollection()
+    .AddSchedule(options => options.AddJob<MyJob>(Triggers.Period(5000)))
+    .GetScheduleHostedService()
+    .StartAsync(new CancellationTokenSource().Token);
+```
+
+---
+
+## 26.1.3 作業資訊 JobDetail
+
+### 屬性
+
+| 屬性 | 型別 | 預設值 | 說明 |
+|------|------|--------|------|
+| `JobId` | `string` | — | 作業 Id |
+| `GroupName` | `string` | — | 作業組名稱 |
+| `JobType` | `string` | — | 處理程式型別 FullName |
+| `AssemblyName` | `string` | — | 程式集 Name |
+| `Description` | `string` | — | 描述 |
+| `Concurrent` | `bool` | `true` | 並行（true）/ 串行（false） |
+| `IncludeAnnotations` | `bool` | `false` | 是否掃描觸發器特性 |
+| `Properties` | `string` | `"{}"` | 額外資料 |
+| `UpdatedTime` | `DateTime?` | — | 更新時間 |
+
+### JobBuilder 建立方式
+
+```csharp
+JobBuilder.Create<MyJob>();
+JobBuilder.Create("job1");
+JobBuilder.Create("YourProject", "YourProject.MyJob");
+JobBuilder.Create((context, stoppingToken) => { return Task.CompletedTask; });
+JobBuilder.From(jobDetail);        // 從執行階段建立
+JobBuilder.From(jsonString);       // 從 JSON 建立
+JobBuilder.Clone(fromJobBuilder);  // 克隆
+```
+
+### JobBuilder 設定方法
+
+`.SetJobId()` / `.SetGroupName()` / `.SetJobType<T>()` / `.SetDescription()` / `.SetConcurrent()` / `.SetIncludeAnnotations()` / `.SetProperties()` / `.SetDynamicExecuteAsync()` / `.SetTemporary()` / `.LoadFrom()`
+
+### 額外資料操作
+
+```csharp
+jobDetail.GetProperty<int>("count");
+jobDetail.AddOrUpdateProperty("count", count + 1);
+jobDetail.RemoveProperty("key");
+jobDetail.ClearProperties();
+jobDetail.ContainsProperty("key"); // 4.9.2.32+
+```
+
+> 額外資料值僅支援 `int32`、`int64`、`string`、`bool`、`null` 或其陣列。
+
+### 輸出格式
+
+```csharp
+jobDetail.ConvertToJSON();
+jobDetail.ConvertToSQL("tableName", PersistenceBehavior.Appended, NamingConventions.CamelCase);
+jobDetail.ConvertToMonitor();
+jobDetail.ToString();
+```
+
+### 啟用自動日誌（4.8.3.7+）
+
+```csharp
+options.JobDetail.LogEnabled = true;
+```
+
+---
+
+## 26.1.4 作業處理程式 IJob
+
+### JobExecutingContext 上下文
+
+| 屬性 | 說明 |
+|------|------|
+| `JobId` | 作業 Id |
+| `TriggerId` | 觸發器 Id |
+| `JobDetail` | 作業資訊 |
+| `Trigger` | 觸發器 |
+| `OccurrenceTime` | 計畫觸發時間（最準確） |
+| `ExecutingTime` | 實際執行時間 |
+| `RunId` | 本次執行唯一 Id（4.8.5.1+） |
+| `Result` | 設定/讀取執行結果（4.8.7.7+） |
+| `ServiceProvider` | 服務提供器（4.8.7.10+） |
+| `Mode` | 觸發方式：定時/手動（4.9.3.1+） |
+
+### 作業處理程式實例（4.8.8.13+）
+
+預設每次觸發都建立新實例。推薦高頻作業註冊為**單例**：
+
+```csharp
+services.AddSingleton<MyJob>();
+```
+
+自訂工廠：
+
+```csharp
+public class JobFactory : IJobFactory
+{
+    public IJob CreateJob(IServiceProvider sp, JobFactoryContext ctx)
+        => ActivatorUtilities.GetServiceOrCreateInstance(sp, ctx.JobType) as IJob;
+}
+
+options.AddJobFactory<JobFactory>();
+```
+
+### 異常處理與重試
+
+```csharp
+options.AddJob<MyJob>(Triggers.PeriodSeconds(3).SetNumRetries(3));
+```
+
+> 異常僅影響當次觸發，不影響下次執行。推薦使用作業執行器 `IJobExecutor` 設定全域重試策略。
+
+### 異常回退策略（4.8.8.6+）
+
+```csharp
+public class TestJob : IJob
+{
+    public Task ExecuteAsync(JobExecutingContext context, CancellationToken stoppingToken) { throw new Exception(); }
+    public Task FallbackAsync(JobExecutedContext context, CancellationToken stoppingToken)
+    {
+        Console.WriteLine("回退被呼叫");
+        return Task.CompletedTask;
+    }
+}
+```
+
+### 上下文資料（4.9.7.82+）
+
+```csharp
+public IDictionary<string, object> GetContextData()
+    => new Dictionary<string, object> { { "db", _dbContext } };
+
+// 在監視器/執行器中取得
+var db = context.GetItem<IDbContext>("db");
+```
+
+### Roslyn 動態建立（4.8.8.7+）
+
+```csharp
+var jobAssembly = Schedular.CompileCSharpClassCode(@"/* C# 程式碼 */");
+var jobType = jobAssembly.GetType("YourProject.MyJob");
+_schedulerFactory.AddJob(jobType, Triggers.PeriodSeconds(5));
+```
+
+---
+
+## 26.1.5 作業觸發器 Trigger
+
+### 屬性
+
+| 屬性 | 型別 | 預設值 | 說明 |
+|------|------|--------|------|
+| `TriggerId` | `string` | — | 觸發器 Id |
+| `JobId` | `string` | — | 作業 Id |
+| `TriggerType` / `AssemblyName` | `string` | — | 觸發器型別 |
+| `Args` | `string` | — | 初始化參數（`object[]` 序列化） |
+| `Status` | `TriggerStatus` | `Ready` | 觸發器狀態 |
+| `StartTime` / `EndTime` | `DateTime?` | — | 起止時間 |
+| `LastRunTime` / `NextRunTime` | `DateTime?` | — | 上次/下次執行時間 |
+| `NumberOfRuns` / `MaxNumberOfRuns` | `long` | `0` | 觸發次數 / 最大次數（0=不限） |
+| `NumberOfErrors` / `MaxNumberOfErrors` | `long` | `0` | 出錯次數 / 最大出錯（0=不限） |
+| `NumRetries` | `int` | `0` | 重試次數 |
+| `RetryTimeout` | `int` | `1000` | 重試間隔（ms） |
+| `StartNow` | `bool` | `true` | 是否立即啟動 |
+| `RunOnStart` | `bool` | `false` | 啟動時執行一次 |
+| `ResetOnlyOnce` | `bool` | `true` | 重啟時重置僅一次的作業 |
+| `Result` | `string` | — | 執行結果（4.8.7.7+） |
+| `ElapsedTime` | `long` | `0` | 執行耗時 ms（4.8.7.7+） |
+
+### TriggerStatus 列舉
+
+`Backlog(0)` / `Ready(1)` / `Running(2)` / `Pause(3)` / `Blocked(4)` / `ErrorToReady(5)` / `Archived(6)` / `Panic(7)` / `Overrun(8)` / `Unoccupied(9)` / `NotStart(10)` / `Unknown(11)` / `Unhandled(12)`
+
+### 內建觸發器速查（Triggers 靜態類）
+
+| 方法 | 說明 |
+|------|------|
+| `Period(ms)` / `PeriodSeconds(n)` / `PeriodMinutes(n)` / `PeriodHours(n)` | 間隔觸發 |
+| `Cron(expr, format)` | Cron 表達式 |
+| `Secondly()` / `Minutely()` / `Hourly()` / `Daily()` / `Monthly()` / `Weekly()` / `Yearly()` / `Workday()` | 週期觸發 |
+| `Secondly(n)` / `Minutely(n)` / `Hourly(n)` | 間隔 n 秒/分/時（4.9.7.224+） |
+| `SecondlyAt(3,5,6)` / `MinutelyAt(3)` / `HourlyAt(3)` / `DailyAt(3)` / `MonthlyAt(3)` / `WeeklyAt(3,"FRI")` / `YearlyAt(3,"MAR")` | Macro At 方式 |
+| `At("2025-11-26 13:20:13")` | 指定時間一次性觸發（4.9.7.214+） |
+
+### TriggerBuilder 建立方式
+
+```csharp
+Triggers.PeriodSeconds(5);
+Triggers.Cron("* * * * *");
+TriggerBuilder.Create<CronTrigger>("* * * * *", CronStringFormat.Default);
+TriggerBuilder.From(trigger);     // 從執行階段
+TriggerBuilder.From(jsonString);  // 從 JSON
+TriggerBuilder.Clone(from);       // 克隆
+```
+
+### TriggerBuilder 設定方法
+
+`.SetTriggerId()` / `.SetDescription()` / `.SetStatus()` / `.SetStartTime()` / `.SetEndTime()` / `.SetMaxNumberOfRuns()` / `.SetNumRetries()` / `.SetRetryTimeout()` / `.SetStartNow()` / `.SetRunOnStart()` / `.SetResult()` 等。
+
+### 更改觸發時間（AlterTo）（4.8.7.31+）
+
+```csharp
+triggerBuilder.AlterToPeriodSeconds(5);
+triggerBuilder.AlterToCron("* * * * *");
+triggerBuilder.AlterToSecondly();
+triggerBuilder.AlterToMinutelyAt(3, 5, 6);
+triggerBuilder.AlterTo<CustomTrigger>(30);
+```
+
+### 自訂觸發器
+
+```csharp
+public class CustomTrigger : Trigger
+{
+    public CustomTrigger(int seconds) => Seconds = seconds;
+    private int Seconds { get; set; }
+    public override DateTime? GetNextOccurrence(DateTime startAt) => startAt.AddSeconds(Seconds);
+}
+
+options.AddJob<MyJob>(Triggers.Create<CustomTrigger>(3));
+```
+
+### 觸發器特性
+
+`[Period]` / `[PeriodSeconds]` / `[PeriodMinutes]` / `[PeriodHours]` / `[Cron]` / `[Secondly]` / `[Minutely]` / `[Hourly]` / `[Daily]` / `[Monthly]` / `[Weekly]` / `[Yearly]` / `[Workday]` / `[SecondlyAt]` / `[MinutelyAt]` / `[HourlyAt]` / `[DailyAt]` / `[MonthlyAt]` / `[WeeklyAt]` / `[YearlyAt]` / `[At]`
+
+### 查看最近運行記錄（4.8.4.3+）
+
+```csharp
+var timelines = trigger.GetTimelines(); // 最近 5 條
+```
+
+---
+
+## 26.1.6 作業計畫 Scheduler
+
+### SchedulerBuilder 建立
+
+```csharp
+SchedulerBuilder.Create<MyJob>(Triggers.PeriodSeconds(5), Triggers.Minutely());
+SchedulerBuilder.Create(jobBuilder, triggerBuilder1, triggerBuilder2);
+SchedulerBuilder.From(scheduler);  // 從 IScheduler
+SchedulerBuilder.From(jsonString); // 從 JSON
+SchedulerBuilder.Clone(from);
+```
+
+### SchedulerBuilder 操作
+
+```csharp
+schedulerBuilder.GetJobBuilder();
+schedulerBuilder.GetTriggerBuilders();
+schedulerBuilder.AddTriggerBuilder(triggerBuilder);
+schedulerBuilder.UpdateTriggerBuilder(triggerBuilder);
+schedulerBuilder.RemoveTriggerBuilder("triggerId");
+schedulerBuilder.ConvertToJSON();
+```
+
+### 持久化標記
+
+`.Appended()` → INSERT / `.Updated()` → UPDATE / `.Removed()` → DELETE
+
+---
+
+## 26.1.7 ScheduleOptionsBuilder 設定
+
+```csharp
+services.AddSchedule(options =>
+{
+    options.UseUtcTimestamp = false;
+    options.LogEnabled = true;
+    options.ClusterId = "cluster1";
+    options.BuildSqlType = SqlTypes.SqlServer;
+    options.JobDetail.LogEnabled = true;
+    options.JobDetail.ConvertToSQL = (tableName, cols, detail, behavior, naming) => { };
+    options.Trigger.ConvertToSQL = (tableName, cols, trigger, behavior, naming) => { };
+    options.UnobservedTaskExceptionHandler = (obj, args) => { };
+    options.RunOnStartProvider = (trigger, checkTime) => { };
+
+    // 作業註冊
+    options.AddJob<MyJob>(Triggers.Secondly());
+    options.AddHttpJob(request => { }, Triggers.PeriodSeconds(5));
+    options.AddMonitor<YourJobMonitor>();
+    options.AddExecutor<YourJobExecutor>();
+    options.AddPersistence<DbJobPersistence>();
+    options.AddClusterServer<JobClusterServer>();
+});
+```
+
+---
+
+## 26.1.8 作業監視器 IJobMonitor
+
+```csharp
+public class YourJobMonitor : IJobMonitor
+{
+    public Task OnExecutingAsync(JobExecutingContext context, CancellationToken ct)
+    {
+        // 執行之前
+        return Task.CompletedTask;
+    }
+
+    public Task OnExecutedAsync(JobExecutedContext context, CancellationToken ct)
+    {
+        // 執行之後（context.Exception 可取得異常）
+        return Task.CompletedTask;
+    }
+}
+
+options.AddMonitor<YourJobMonitor>();
+```
+
+---
+
+## 26.1.9 作業執行器 IJobExecutor
+
+### 重試策略
+
+```csharp
+public class YourJobExecutor : IJobExecutor
+{
+    public async Task ExecuteAsync(JobExecutingContext context, IJob jobHandler, CancellationToken ct)
+    {
+        await Retry.InvokeAsync(async () => await jobHandler.ExecuteAsync(context, ct), 3, 1000);
+    }
+}
+```
+
+### 逾時控制
+
+```csharp
+public async Task ExecuteAsync(JobExecutingContext context, IJob jobHandler, CancellationToken ct)
+{
+    await jobHandler.ExecuteAsync(context, ct).WaitAsync(TimeSpan.FromMilliseconds(3000));
+}
+```
+
+---
+
+## 26.1.10 作業計畫工廠 ISchedulerFactory
+
+單例服務，提供執行階段操作作業的完整 API。
+
+### 常用方法速查
+
+| 方法 | 說明 |
+|------|------|
+| `GetJobs()` / `GetJobs("group")` | 查詢所有/分組作業 |
+| `GetNextRunJobs(DateTime.Now)` | 下一批觸發的作業 |
+| `TryGetJob("jobId", out scheduler)` / `GetJob("jobId")` | 取得單個作業 |
+| `TrySaveJob(builder, out scheduler)` | 儲存（新增/更新/刪除） |
+| `TryAddJob<T>(triggers, out scheduler)` | 新增作業 |
+| `TryUpdateJob(builder, out scheduler)` | 更新作業 |
+| `TryRemoveJob("jobId", out scheduler)` | 刪除作業 |
+| `ContainsJob("jobId")` | 檢查是否存在 |
+| `StartAll()` / `PauseAll()` / `RemoveAll()` | 全部啟動/暫停/刪除 |
+| `TryRunJob("jobId", out scheduler)` | 手動執行（4.8.7.11+） |
+| `TryCancelJob("jobId", out scheduler)` | 取消執行（4.9.1.9+） |
+| `TryStartJob("jobId")` / `TryPauseJob("jobId")` | 啟停單個作業（4.9.2.16+） |
+| `CancelSleep()` | 強制喚醒排程器 |
+| `GCCollect()` | 觸發 GC 回收（4.9.1.23+） |
+| `OnChanged` | 作業變更事件（4.8.8.29+） |
+| `OnExecutionRecord` | 觸發記錄通知（4.9.1.16+） |
+
+---
+
+## 26.1.11 作業計畫 IScheduler
+
+單個作業操作介面。
+
+```csharp
+scheduler.GetJobDetail();
+scheduler.GetTriggers();
+scheduler.GetTriggerBuilder("triggerId");
+scheduler.TryAddTrigger(triggerBuilder, out trigger);
+scheduler.TryUpdateTrigger(triggerBuilder, out trigger);
+scheduler.TryRemoveTrigger("triggerId", out trigger);
+scheduler.UpdateDetail(jobBuilder);
+scheduler.Start() / .Pause() / .Remove();
+scheduler.Run() / .Run("triggerId");         // 手動執行
+scheduler.Cancel() / .Cancel("triggerId");   // 取消執行
+scheduler.Reload();                          // 強制重新整理
+scheduler.ConvertToJSON();
+scheduler.GetEnumerable();                   // 轉可枚舉字典
+```
+
+---
+
+## 26.1.12 作業持久化器 IJobPersistence
+
+```csharp
+public class DbJobPersistence : IJobPersistence
+{
+    public Task<IEnumerable<SchedulerBuilder>> PreloadAsync(CancellationToken ct)
+    {
+        // 啟動時從資料庫載入作業
+        return Task.FromResult(Enumerable.Empty<SchedulerBuilder>());
+    }
+
+    public Task<SchedulerBuilder> OnLoadingAsync(SchedulerBuilder builder, CancellationToken ct)
+    {
+        // 初始化時進一步修改（可標記 .Updated() / .Appended() / .Removed()）
+        return Task.FromResult(builder);
+    }
+
+    public Task OnChangedAsync(PersistenceContext context)
+    {
+        var sql = context.ConvertToSQL("job_detail"); // 執行 SQL 即可
+        return Task.CompletedTask;
+    }
+
+    public Task OnTriggerChangedAsync(PersistenceTriggerContext context)
+    {
+        var sql = context.ConvertToSQL("job_trigger");
+        return Task.CompletedTask;
+    }
+
+    public Task OnExecutionRecordAsync(PersistenceExecutionRecordContext context)
+    {
+        // 寫入運行記錄表
+        return Task.CompletedTask;
+    }
+}
+
+options.AddPersistence<DbJobPersistence>();
+```
+
+> 框架自動生成標準 SQL（支援 `SqlTypes.SqlServer` / `MySQL` / `PostgreSQL` / `Sqlite` / `Oracle` / `Firebird`）。
+
+---
+
+## 26.1.13 作業叢集控制
+
+提供簡單的**故障轉移**功能（非負載均衡）。
+
+```csharp
+public class JobClusterServer : IJobClusterServer
+{
+    public void Start(JobClusterContext context) { /* 寫入 Waiting 狀態 */ }
+    public async Task WaitingForAsync(JobClusterContext context) { /* 輪詢檢查，條件滿足時呼叫 WorkNow */ }
+    public void Stop(JobClusterContext context) { /* 更新為 Crashed */ }
+    public void Crash(JobClusterContext context) { /* 更新為 Crashed */ }
+}
+
+options.ClusterId = "cluster1";
+options.AddClusterServer<JobClusterServer>();
+```
+
+`ClusterStatus` 列舉：`Crashed` / `Working` / `Waiting`（預設）。
+
+---
+
+## 26.1.16 Dashboard 看板（4.8.4+）
+
+```csharp
+app.UseStaticFiles();
+app.UseScheduleUI();  // 必須在 UseStaticFiles 之後
+```
+
+> 預設入口：`/schedule`，預設帳號：`schedule`，密碼為空。
+
+### 設定選項
+
+```csharp
+app.UseScheduleUI(options =>
+{
+    options.RequestPath = "/custom-job";
+    options.DisableOnProduction = true;
+    options.DisplayEmptyTriggerJobs = true;
+    options.DefaultExpandAllJobs = false;
+    options.Title = "定時任務看板";
+
+    options.LoginConfig.OnLoging = async (username, password, httpContext) =>
+        await Task.FromResult(username == "furion" && password == "furion");
+    options.LoginConfig.DefaultUsername = "";
+    options.LoginConfig.DefaultPassword = "";
+});
+```
+
+### Worker Service 中啟用看板
+
+```csharp
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureServices(services => { services.AddSchedule(); })
+    .ConfigureWebHostDefaults(builder => builder.Configure(app =>
+    {
+        app.UseStaticFiles();
+        app.UseScheduleUI();
+    }))
+    .Build();
+host.Run();
+```
+
+---
+
+## 26.1.15 部署建議
+
+- 部署到 IIS 需停用應用程式集區回收
+- **強烈建議**採用 Worker Service 獨立部署
+- 確保伺服器不會進入休眠
+
+---
+
+## 26.1.17 常見問題
+
+- **時間偏差**：使用 `context.OccurrenceTime` 而非 `DateTime.Now`
+- **參數序列化**：使用 `Schedular.Serialize()` / `Schedular.Deserialize<T>()`
+- **延遲操作**：使用 `Task.Delay` 而非 `Thread.Sleep`