---

applyTo: '**/*'

---

Windows Service Agent 開發指引設計規格

日期：2026-06-12

狀態：已確認設計，待使用者審閱書面規格

目標：將現有 Windows Service 開發與上架經驗，整理成 AI Agent 可直接理解、執行及驗證的標準開發套件。

1. 背景

工作區包含 Windows Service 原始碼、歷史發佈版本、設定檔、相依 DLL、InstallUtil 安裝紀錄及批次腳本。現有的《Windows Service 開發與上架規範》已適合人員閱讀，但尚未提供 AI Agent 所需的自動套用規則、任務工作流程與可重用程式碼資產。

本設計參考 .github 既有的下列文件模式：

• AGENTS.md：最高層行為規範、紅線與索引。
• WORKFLOW.md：由探勘、設計、實作到驗證的階段式流程。
• instructions/*.instructions.md：透過 applyTo 對特定檔案自動套用規則。
• skills/*/SKILL.md：依使用者意圖觸發的完整任務流程。
• skills/*/assets/：任務可直接重用的範本與資產。

2. 已確認的技術決策

2.1 技術基線

新建 Windows Service 預設強制採用：

• C#。
• .NET Framework 4.7.2。
• System.ServiceProcess.ServiceBase。
• ServiceProcessInstaller 與 ServiceInstaller。
• InstallUtil.exe 安裝與解除安裝。
• MSTest 測試專案。

.NET Worker Service 不列為預設路徑。若需求明確要求現代 .NET，Agent 必須先提出架構差異、主機相容性及上架方式變更，等待人工確認。

2.2 共用函式庫

強制優先使用 CHMC.dll：

• CHMC.Config：讀取 App.config 的 appSettings 與 connectionStrings。
• CHMC.Log：服務生命週期、Job 與例外日誌。
• CHMC.DbHelperSQL：資料庫存取基底。
• CHMC.AES 或既有相容加解密方法：處理機密設定。

Agent 不得自行建立另一套 Config、Logger、資料庫 Helper 或加解密元件。若 CHMC.dll 不存在、方法簽章無法確認或功能不足，必須輸出差異報告並等待決策。

2.3 強制分層

服務必須遵守：

Windows Service Host

        |

        v

BLL / Job

        |

        v

DAL

        |

        v

DTO

• Service Host：只負責服務啟停、設定驗證、Timer 管理與背景工作的生命週期。
• BLL/Job：負責業務規則、流程協調、執行結果與冪等控制。
• DAL：唯一可存取資料庫的層級，並透過 CHMC.DbHelperSQL 執行。
• DTO：純資料物件，不包含資料存取、排程或業務邏輯。

Service Host 不得直接撰寫 SQL、呼叫資料庫或承載完整業務流程。

2.4 排程策略

預設強制使用 System.Timers.Timer，且必須具備：

• 防重入。
• CancellationToken 或等效停止訊號。
• 執行逾時。
• 有限次重試。
• 安全停止。
• Timer 與背景工作的資源釋放。
• 啟動後立即執行時，不阻塞 OnStart。

只有多組日、週、月、Cron 排程或其他明確需要時，才可在人工確認後改用 Quartz。

3. 交付架構

採用「政策層 + 工作流程層 + 範本層」三件式 Agent 套件。

.github/

├── AGENTS.md

├── WORKFLOW.md

├── instructions/

│   └── WindowsService.instructions.md

└── skills/

    └── windows-service-development/

        ├── SKILL.md

        └── assets/

            ├── project-structure.md

            ├── ServiceHost.cs.template

            ├── ProjectInstaller.cs.template

            ├── TimerJobRunner.cs.template

            ├── App.config.template

            ├── install.cmd.template

            ├── uninstall.cmd.template

            ├── upgrade.cmd.template

            └── release-manifest.json.template

3.1 WindowsService.instructions.md

用途：對 Windows Service 專案內的 C#、Config、專案檔、測試及部署腳本自動套用強制規則。

內容必須包含：

• 適用檔案的 applyTo。
• 技術基線。
• 強制目錄與依賴方向。
• ServiceName、DisplayName、EXE、LogName 與版本命名。
• ServiceBase、ProjectInstaller 與 InstallUtil 規則。
• OnStart、OnStop 與 Dispose 規則。
• Timer 防重入、取消、逾時及安全停止規則。
• CHMC.dll 強制使用規則。
• 設定與機密管理規則。
• BLL、DAL、DTO 的責任與禁止事項。
• 日誌、測試、發佈包及安裝腳本最低標準。
• Agent 必須停止推測的條件。
• 提交前檢核清單。

3.2 SKILL.md

用途：使用者提出「建立、仿照、修改、升版、發佈或上架 Windows Service」時，驅動 Agent 完成端到端工作。

Skill metadata 必須清楚描述觸發情境及不適用情境。

工作流程：

1. 讀取 .github/AGENTS.md、WORKFLOW.md、Windows Service instruction 及本 Skill。

2. 探勘參考服務、CHMC.dll 用法、目標 Framework 與部署模式。

3. 蒐集或推導必要需求。

4. 輸出設計摘要並確認。

5. 建立 Solution、Service、BLL、DAL、DTO 與 Test 專案。

6. 套用資產範本。

7. 建立設定、日誌、防重入、取消、逾時與例外處理。

8. 執行建置與測試。

9. 產生 Release 發佈目錄與部署腳本。

10. 執行安全及發佈驗證。

11. 回報產物、指令、驗證證據與未驗證事項。

3.3 assets/

資產使用中性佔位符，Skill 必須要求 Agent 在產生實際專案時全部替換，禁止在最終程式碼保留 {ServiceName} 等佔位符。

每個資產責任：

| 資產 | 責任 |

|---|---|

| project-structure.md | 標準 Solution、專案、部署與文件目錄 |

| ServiceHost.cs.template | ServiceBase、OnStart、OnStop、Dispose 與背景啟動 |

| ProjectInstaller.cs.template | ServiceName、DisplayName、Description、Automatic 與服務帳號提示 |

| TimerJobRunner.cs.template | Timer、防重入、CancellationToken、Timeout、RunId 與日誌 |

| App.config.template | .NET 4.7.2、CHMC 設定、Interval、Timeout、LogFolder 與加密連線 |

| install.cmd.template | 管理員檢查、InstallUtil、啟動、錯誤碼與狀態驗證 |

| uninstall.cmd.template | 停止等待、InstallUtil /u、不存在服務處理與錯誤碼 |

| upgrade.cmd.template | 舊版停止與解除、新版安裝、啟動驗證及失敗提示 |

| release-manifest.json.template | ServiceName、版號、Framework、Commit、設定變更、Checksum 與回復版號 |

4. Agent 必要輸入

Agent 在設計前至少取得或從工作區確認：

• 系統與服務用途。
• ServiceName。
• DisplayName。
• Description。
• Solution 與 Assembly 名稱。
• 工作或 Job 名稱。
• 執行週期秒數。
• 是否啟動後立即執行。
• 資料來源與外部系統。
• DEV、TEST、PROD 的服務名稱與設定差異。
• 日誌目錄與保留天數。
• 部署根目錄。
• 服務帳號需求。
• 是否需要資料庫交易、寄信、檔案或 API。

若資訊缺少但可由相鄰專案安全推導，Agent 可提出推導值供確認；不得默默硬編。

5. 標準專案結構

<ServiceName>/

├── <ServiceName>.sln

├── src/

│   ├── <ServiceName>.Service/

│   │   ├── Program.cs

│   │   ├── ServiceHost.cs

│   │   ├── ServiceHost.Designer.cs

│   │   ├── ProjectInstaller.cs

│   │   ├── ProjectInstaller.Designer.cs

│   │   └── App.config

│   ├── <ServiceName>.BLL/

│   │   └── Jobs/

│   ├── <ServiceName>.DAL/

│   └── <ServiceName>.DTO/

├── tests/

│   └── <ServiceName>.Tests/

├── deploy/

│   ├── install.cmd

│   ├── uninstall.cmd

│   ├── upgrade.cmd

│   ├── rollback.md

│   └── release-manifest.json

└── docs/

    ├── README.md

    ├── CHANGELOG.md

    └── RUNBOOK.md

若現有 Solution 已有不同但清楚的分層結構，Agent 應優先遵循既有模式，不進行無關搬移。

6. Service Host 行為

6.1 OnStart

只允許：

• 驗證設定。
• 建立停止訊號。
• 初始化 Timer 與 Job Runner。
• 以背景方式啟動服務。
• 記錄服務名稱、版本、環境與執行週期。

禁止：

• 同步執行長時間 Job。
• 直接存取資料庫。
• 吞掉啟動錯誤後仍回報成功。

6.2 OnStop

必須：

• 停止 Timer。
• 阻止新 Job 進入。
• 發出取消訊號。
• 在設定的停止逾時內等待目前 Job。
• 釋放 Timer、CancellationTokenSource 與 Runner。
• 記錄停止結果。

6.3 Timer Runner

Timer Runner 必須：

• 以 Interlocked 或 SemaphoreSlim 防止同 Job 重入。
• 每次執行產生 RunId。
• 記錄開始、完成、失敗、跳過與耗時。
• 使用 CancellationToken。
• 套用工作逾時。
• 在 finally 中解除防重入鎖定。
• Job 失敗不得終止 Timer 執行緒或整個服務程序。

7. BLL、DAL、DTO 規則

7.1 BLL / Job

• 一個 Job 對應一項清楚的業務工作。
• 驗證輸入與必要設定。
• 協調 DAL、API、File 與 Mail。
• 實作冪等、結果統計與可重跑行為。
• 不撰寫 SQL。
• 例外使用 CHMC.Log 記錄，並將失敗狀態回傳 Runner。

7.2 DAL

• 唯一可撰寫 SQL 的層級。
• 強制繼承或包裝既有 CHMC.DbHelperSQL 模式。
• 強制參數化 SQL。
• 連線字串透過 CHMC.Config.ConnectionString() 取得。
• 正確釋放 DataSet、Command、Parameter 與 DAL 資源。
• 不包含排程或業務規則。

具體 DbHelperSQL 方法簽章必須由參考專案或組件文件確認。Agent 不得假設 Web 專案的所有 DAL 簽章可直接套用到服務專案。

7.3 DTO

• 只包含資料屬性與必要的資料列映射。
• 不包含 SQL、Config、Log、Timer 或業務流程。
• 可空資料庫欄位必須使用 Nullable 或明確 null 處理。

8. 設定與機密

• App.config 使用 .NETFramework,Version=v4.7.2。
• 一般設定透過 CHMC.Config.appSettings()。
• 連線透過 CHMC.Config.ConnectionString()。
• 連線字串、密碼與 Token 不得以明文進入程式碼、註解、測試或版本控制。
• 不得把舊明文留在 XML 註解。
• 正式環境不得含 Platform=debug、EnableTest=1 或等效旗標。
• Interval、JobTimeoutSeconds、StopTimeoutSeconds 與 LogRetentionDays 必須驗證範圍。

9. 測試策略

MSTest 至少涵蓋：

• 設定缺少與範圍錯誤。
• Timer 正確觸發。
• Job 防重入。
• Job 成功。
• Job 例外後服務可繼續。
• Cancellation。
• Job Timeout。
• OnStop 等待與逾時。
• 冪等重跑。
• DEV/PROD 設定隔離。

Unit Test 不得直接連正式資料庫。需要資料庫的測試必須標示 Integration Test 並使用專用環境。

10. 發佈與上架

發佈資料夾使用：

YYYYMMDDNN

Release 包必須包含：

• EXE。
• .exe.config。
• 實際使用的 DLL。
• Install、Uninstall、Upgrade 腳本。
• release manifest。
• CHANGELOG。
• README 或 RUNBOOK。

不得包含：

• Debug 輸出。
• 測試專案與測試資料。
• *.InstallLog。
• *.InstallState。
• 明文機密。
• 未使用 DLL。

安裝腳本必須：

• 以 %~dp0 定位。
• 檢查系統管理員權限。
• 檢查 EXE 與 InstallUtil。
• 使用雙引號處理路徑。
• 檢查每一步錯誤碼。
• 啟動後使用 sc.exe query 驗證。
• 成功回傳 0，失敗回傳非 0。
• 不以 pause 作為錯誤處理。

11. 停止推測與差異報告

遇到下列情況，Agent 不得自行決定：

• 找不到 CHMC.dll。
• 無法確認 CHMC 方法簽章。
• ServiceName 已存在或與其他環境衝突。
• 要修改既有共用 DLL。
• 要改用 Quartz。
• 要改用 .NET Worker Service。
• 要使用 LocalSystem。
• 需要新增明文機密。
• 無法確認正式資料庫或部署主機。
• 升版流程無法確認舊版 ImagePath。

固定報告格式：

## Windows Service 差異報告



**需求**：

**目前標準**：

**發現差異**：

**影響範圍**：

**建議方案 A**：

**建議方案 B**：

**需要人工決策**：是

12. .github 既有文件整合

12.1 AGENTS.md

新增：

• Windows Service 最高層技術基線。
• CHMC.dll 強制使用。
• 分層與禁止 Host 直接存取資料庫。
• Windows Service instruction、Skill 與完整規範索引。

既有 ASP.NET 棕地紅線不應被改寫或弱化。

12.2 WORKFLOW.md

新增獨立的 Windows Service 工作流程章節：

1. 參考服務與 CHMC 評估。

2. 服務識別及排程設計。

3. DTO、DAL、BLL/Job、Host 由下而上建構。

4. MSTest。

5. Release 建置。

6. YYYYMMDDNN 發佈包。

7. InstallUtil 安裝、升版、回復及上架驗證。

既有 ASP.NET 新功能流程保持不變。

13. 完成定義

本 Agent 指引套件完成時，必須同時滿足：

• Windows Service instruction 存在且 applyTo 可覆蓋服務相關檔案。
• Skill metadata 可由建立、仿照、修改、升版、發佈、安裝 Windows Service 等意圖觸發。
• Skill 明確要求讀取 instruction 與資產。
• 九份資產均存在且彼此命名一致。
• 所有 C# 範本使用 .NET Framework 4.7.2 可用語法。
• Host、BLL/Job、DAL、DTO 的依賴方向一致。
• Timer 範本具備防重入、取消、逾時與安全停止。
• 所有設定、日誌、資料庫及加解密規則強制使用 CHMC.dll。
• Install、Uninstall、Upgrade 腳本具備路徑、權限、狀態與錯誤碼檢查。
• AGENTS.md 與 WORKFLOW.md 含 Windows Service 索引及流程。
• 指引包含 Agent 停止推測條件與固定差異報告。
• 不包含實際 IP、帳號、密碼、Token、郵件或正式連線字串。
• 文件不得含未完成標記、空白章節或未定義規則。

14. 不在本次範圍

• 建立實際的新 Windows Service 業務專案。
• 修改或重新編譯 CHMC.dll。
• 將既有服務遷移到現代 .NET。
• 實際登入主機安裝服務。
• 建立 CI/CD Pipeline。
• 修改現有 Windows Service 部署包。