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

package/knowledge/Furion_Teaching_Manual/25-/350/274/224/345/212/251/350/247/222/350/211/262/346/234/215/345/213/231WorkerService.md

@@ -0,0 +1,295 @@
+# 25. 輔助角色服務（Worker Service）
+
+---
+
+## 25.1 概述
+
+.NET Core 3.0+ 提供 Worker Service 專案範本，可編寫長時間執行的背景服務，並部署為 Windows 服務或 Linux 守護程式。
+
+兩種建立方式：
+
+| 方式 | 特點 | 推薦 |
+|------|------|------|
+| **共宿主方式** | 在現有 Web 應用中建立，與應用共存亡 | 中小型專案 |
+| **獨立 Worker Service** | 獨立專案、獨立部署、獨立生命週期 | 中大型專案 |
+
+---
+
+## 25.2 共宿主方式
+
+```csharp
+public class Worker : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            Console.WriteLine(DateTime.Now);
+            await Task.Delay(1000, stoppingToken);
+        }
+    }
+}
+
+// 註冊
+services.AddHostedService<Worker>();
+```
+
+### 最佳實踐
+
+建立獨立類別庫 `YourProject.BackgroundServices`，引用 Application / Core 層，透過 `AppStartup` 統一註冊：
+
+```csharp
+namespace YourProject.BackgroundServices;
+
+public sealed class Startup : AppStartup
+{
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddHostedService<Worker>();
+        services.AddHostedService<Worker2>();
+    }
+}
+```
+
+---
+
+## 25.3 獨立 Worker Service
+
+### 25.3.1 建立專案
+
+透過 Visual Studio 的 **Worker Service** 範本建立。
+
+### 25.3.2 基本 Worker
+
+```csharp
+public class Worker : BackgroundService
+{
+    private readonly ILogger<Worker> _logger;
+    public Worker(ILogger<Worker> logger) => _logger = logger;
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            _logger.LogInformation("Worker running at: {time}", DateTime.Now);
+            await Task.Delay(1000, stoppingToken);
+        }
+    }
+}
+```
+
+### 25.3.4 生命週期
+
+| 方法 | 說明 |
+|------|------|
+| `StartAsync` | 啟動，不可阻塞 |
+| `ExecuteAsync` | 核心業務邏輯，不可呼叫阻塞程式碼 |
+| `StopAsync` | 停止，不可阻塞 |
+
+### 25.3.5 整合 Furion
+
+**.NET 5~7：**
+
+```csharp
+public static IHostBuilder CreateHostBuilder(string[] args) =>
+    Host.CreateDefaultBuilder(args)
+        .Inject()
+        .ConfigureServices((hostContext, services) =>
+        {
+            // Furion 自動掃描並註冊 Worker，無需手動 AddHostedService
+        });
+```
+
+**.NET 8+：**
+
+```csharp
+var builder = Host.CreateApplicationBuilder(args).Inject();
+// Furion 自動註冊 Worker；Inject(false) 可關閉自動註冊
+var host = builder.Build();
+host.Run();
+```
+
+> `Inject()` 預設註冊了日誌、快取、相依性注入、載入設定、自訂 Startup 功能。整合後會自動掃描 `public` 的 Worker 類。
+
+### 25.3.6 註冊服務
+
+```csharp
+// .NET 8+
+var builder = Host.CreateApplicationBuilder(args).Inject();
+builder.Services.AddDatabaseAccessor(options => options.AddDb<DefaultDbContext>());
+builder.Services.AddHttpRemote();
+var host = builder.Build();
+host.Run();
+```
+
+---
+
+## 25.4 實現簡單定時任務
+
+> 強烈建議使用 **26.1 排程作業** 實現強大的分散式定時任務。
+
+### 25.4.1 間隔執行
+
+```csharp
+protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+{
+    while (!stoppingToken.IsCancellationRequested)
+    {
+        await Task.Delay(1000, stoppingToken);
+
+        var taskFactory = new TaskFactory(TaskScheduler.Current);
+        await taskFactory.StartNew(async () =>
+        {
+            // 業務程式碼
+            _logger.LogInformation("Worker running at: {time}", DateTime.Now);
+            await Task.CompletedTask;
+        }, stoppingToken);
+    }
+}
+```
+
+### 25.4.2 Cron 表達式執行
+
+```csharp
+using Furion.TimeCrontab;
+
+private readonly Crontab _crontab;
+
+public Worker(ILogger<Worker> logger)
+{
+    _logger = logger;
+    _crontab = Crontab.Parse("* * * * * *", CronStringFormat.WithSeconds);
+}
+
+protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+{
+    while (!stoppingToken.IsCancellationRequested)
+    {
+        await Task.Delay(_crontab.GetSleepTimeSpan(DateTime.Now), stoppingToken);
+
+        var taskFactory = new TaskFactory(TaskScheduler.Current);
+        await taskFactory.StartNew(async () =>
+        {
+            _logger.LogInformation("Worker running at: {time}", DateTime.Now);
+            await Task.CompletedTask;
+        }, stoppingToken);
+    }
+}
+```
+
+### 25.4.3 串行執行（等待上次完成）
+
+```csharp
+private bool _isLock = false;
+
+protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+{
+    while (!stoppingToken.IsCancellationRequested)
+    {
+        if (_isLock) goto next;
+        _isLock = true;
+
+        var taskFactory = new TaskFactory(TaskScheduler.Current);
+        var task = await taskFactory.StartNew(async () =>
+        {
+            await Task.Delay(2000); // 模擬耗時操作
+            _logger.LogInformation("Worker running at: {time}", DateTime.Now);
+            await Task.CompletedTask;
+        }, stoppingToken);
+
+        await task.ContinueWith(t => _isLock = false);
+
+    next:
+        await Task.Delay(_crontab.GetSleepTimeSpan(DateTime.Now), stoppingToken);
+    }
+}
+```
+
+---
+
+## 25.5 相依性注入
+
+Worker 僅提供**單例**作用域注入。需使用瞬時或作用域服務時，手動建立作用域：
+
+```csharp
+public class Worker : BackgroundService
+{
+    private readonly ILogger<Worker> _logger;
+    private readonly IServiceScopeFactory _scopeFactory;
+
+    public Worker(ILogger<Worker> logger, IServiceScopeFactory scopeFactory)
+    {
+        _logger = logger;
+        _scopeFactory = scopeFactory;
+    }
+
+    protected override Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        // 高頻場景：作用域放迴圈外
+        using var scope = _scopeFactory.CreateScope();
+        var services = scope.ServiceProvider;
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            // 低頻場景：作用域放迴圈內
+            // using var scope = _scopeFactory.CreateScope();
+
+            var dbContext = Db.GetDbContext(services);
+            var repository = Db.GetRepository<Person>(services);
+            var otherService = services.GetService<XXX>();
+        }
+
+        return Task.CompletedTask;
+    }
+}
+```
+
+---
+
+## 25.6 部署
+
+### 共宿主方式
+
+直接部署所在的 Web 應用即可。部署到 IIS 時需注意回收問題（參見 34.1.5）。
+
+### 部署到 Windows Service
+
+1. 安裝 `Microsoft.Extensions.Hosting.WindowsServices`
+2. 新增 `.UseWindowsService()`：
+
+```csharp
+Host.CreateDefaultBuilder(args)
+    .UseWindowsService()
+    .Inject()
+    .ConfigureServices((ctx, services) => { });
+```
+
+3. 發佈：`dotnet publish -c Release -o C:\FurionWorker`
+4. 以**管理員**模式操作：
+
+```bash
+sc.exe create FurionWorkerServices binPath= C:\FurionWorker\FurionWorker.exe
+sc.exe start FurionWorkerServices
+sc.exe stop FurionWorkerServices
+sc.exe delete FurionWorkerServices
+```
+
+> `=` 後面須有空格。刪除服務前請先關閉 Windows 服務工具。推薦參考 34.8 章節的新部署方式。
+
+### 部署到 Linux 守護程式
+
+1. 安裝 `Microsoft.Extensions.Hosting.Systemd`
+2. 新增 `.UseSystemd()`：
+
+```csharp
+Host.CreateDefaultBuilder(args)
+    .UseSystemd()
+    .Inject()
+    .ConfigureServices((ctx, services) => { });
+```
+
+---
+
+## 25.7 Windows 部署日誌問題
+
+預設部署為 Windows Service 後，日誌檔案可能寫入 `System32` 目錄。若使用 Furion 的 `AddFileLogging`，可嘗試以 `AppDomain.CurrentDomain.BaseDirectory` 作為日誌寫入目錄。