本文件記錄第五階段 5E Windows Service 最小 hosting gate 的程式實作、測試、停止線、提交、推送與 Actions 驗收。5E 本輪只完成 ServiceHost 內可測試的 hosting gate、非敏感 options、runner delegation、console smoke path 保留與明確 --windows-service smoke path；沒有安裝 Windows Service，沒有新增 service installer、正式 service account、正式 log / config path、外部 DLL loading、DB DDL 或正式部署設定。
0. 基本資訊
| 驗收日期 | 2026-06-08 |
|---|---|
| 對應節點 | 第五階段 5E Windows Service |
| 程式 repo / branch | hs-device-control-template / poc/nmodbus-tcp |
| 程式基準 commit | c92342b |
| 程式 commit | 0789d35 |
| Commit 訊息 | 新增 5E Windows Service 最小 hosting gate |
| GitHub Actions | 27098568634 success |
| 文件狀態 | 第一批實作、提交、推送與 Actions 驗收紀錄已建立 |
1. 程式修改範圍
| 類別 | 檔案 |
|---|---|
| Windows Service options | src/HS.DeviceControl.ServiceHost/Options/WindowsServiceHostOptions.cs |
| Windows Service runner | src/HS.DeviceControl.ServiceHost/Services/WindowsServiceHostRunner.cs |
| ServiceHost entry point | src/HS.DeviceControl.ServiceHost/Program.cs |
| ServiceHost tests | tests/HS.DeviceControl.ServiceHost.Tests/ServiceHostRuntimeTests.cs |
2. 實作內容
| 項目 | 結果 |
|---|---|
| Options | 新增 WindowsServiceHostOptions，預設關閉，僅保存 service name、display name、description 等非敏感識別資訊。 |
| Options validation | 阻擋敏感或環境特定字串，不回顯原始值。 |
| Runner | 新增 WindowsServiceHostRunner，只代理既有 IServiceHostRuntime.Start()、Stop()、GetStatus()，不操作 OS service。 |
| Fault mapping | runtime 例外會轉成 APP-0004 與安全摘要，不暴露例外原文或 stack trace。 |
| Console smoke path | 保留既有無參數 Program.Main 輸出與 exit code。 |
| Windows hosting smoke path | 只在明確帶入 --windows-service 時執行 runner smoke path，仍不執行服務安裝。 |
| Package | 未新增 Microsoft.Extensions.Hosting.WindowsServices 或其他 package。 |
3. 測試與驗收結果
| 驗證項目 | 結果 |
|---|---|
| ServiceHost.Tests | 19 passed / 0 failed / 0 skipped |
| Application.Tests | 67 passed / 0 failed / 0 skipped |
| Solution tests | 548 passed / 0 failed / 0 skipped |
| Console smoke path | HS.DeviceControl.ServiceHost: Running... 後 Stopped...，exit code 0。 |
| Windows hosting smoke path | windows-service HS.DeviceControl.ServiceHost: Running... 後 Stopped...，exit code 0。 |
| 停止線掃描 | 未命中 Windows Service 安裝 API / installer、外部 DLL loading、DB DDL、WebApi auth 擴張、plugin folder scan。 |
| 污染字串掃描 | 程式 repo 指定文件與程式範圍未命中既定污染字串；本紀錄不重複列出字串內容。 |
| 程式 repo commit / push | 0789d35 已推送至 poc/nmodbus-tcp。 |
| GitHub Actions | 27098568634 completed success。 |
備註：solution 測試仍有既有 .NET 5.0 EOL warning，與本次 5E 修改無關。
4. 停止線確認
- 不安裝、解除安裝、啟動、停止或修改任何 OS 層 Windows Service。
- 不新增 service installer、install / uninstall script、
sc.exe指令或New-Service流程。 - 不新增
Microsoft.Extensions.Hosting.WindowsServicespackage，也不呼叫UseWindowsService。 - 不保存正式 service account、正式主機、正式 IP、正式路徑、正式 log path、正式 config path 或敏感 credential。
- 不新增 DB DDL、ALTER TABLE、DROP TABLE、formal Apply、正式 DB 初始化或正式 DB 寫入。
- 不變更 WebApi auth / Swagger、既有 API route 或 Application result mapping。
- 不載入外部 DLL、不掃描 plugin folder、不修改 Adapter public contract。
5. 驗收結論
5E Windows Service 最小 hosting gate 已在核准範圍內完成，並通過 ServiceHost、Application、solution 測試、兩條 smoke path、停止線掃描、污染掃描與 GitHub Actions。第五階段尚未完成，因 5F 整合驗收仍需在本文件同步、線上查核完成後，另由使用者回覆 5F 七項確認才可執行。