Instruction asset

編輯一般指令

共用內容只保存一份；工具差異放在專用補充，下載時才組合。

基本資料

名稱

唯一代稱

小寫英文、數字與連字號；建立後仍可修改但不可重複。

簡短說明

主要分類

預設排序

標籤

尚無標籤，可先到「分類與標籤」建立。

共用 Markdown 與即時預覽

共用指令內容

---
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 強制分層

服務必須遵守：

```text
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 套件。

```text
.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. 標準專案結構

```text
<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. 發佈與上架

發佈資料夾使用：

```text
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。

固定報告格式：

```markdown
## 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 部署包。

格式化預覽

工具與套用範圍

適用工具

GitHub Copilot Codex Claude Code Cursor Antigravity

套用範圍

指定路徑模式

每行一筆。當次下載仍可覆寫，不會修改此正式設定。

工具專用補充

只填差異，不要複製整份共用內容。

GitHub Copilot

Codex

Claude Code

Cursor

Antigravity

修改說明

選填；會保存在這次建立的新版本中。

取消