------------------------------------------------------------

## Case #2: 用 SetConsoleCtrlHandler 穩定處理 CTRL+C/CTRL+BREAK

### Problem Statement（問題陳述）
業務場景：開發者在本機或傳統部署環境執行 Console App，需攔截使用者的 CTRL+C/CTRL+BREAK 以便釋放資源與資料落盤。
技術挑戰：需在不中斷主流程的情況下，確保能安全結束。
影響範圍：資源洩漏、資料遺失、進程非預期終止。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 預設 CTRL+C 會直接終止進程，無優雅關閉。
2. 未註冊控制台控制事件處理器，導致無法攔截。
3. 同步機制設計不當，易發生競態。
深層原因：
- 架構層面：未建立標準關閉協定。
- 技術層面：對 P/Invoke/Win32 控制事件理解不足。
- 流程層面：缺少本機終止流程測試。

### Solution Design（解決方案設計）
解決策略：透過 P/Invoke 註冊 SetConsoleCtrlHandler，攔截 CTRL_C_EVENT/CTRL_BREAK_EVENT，於 handler 內僅發訊號，主線程做清理。

實施步驟：
1. 註冊控制台控制事件
- 實作細節：SetConsoleCtrlHandler(ShutdownHandler,true)
- 所需資源：Kernel32 P/Invoke
- 預估時間：0.3 小時

2. 使用 AutoResetEvent 同步主流程
- 實作細節：handler 內 Set()；主線 WaitOne()
- 所需資源：System.Threading
- 預估時間：0.2 小時

3. 測試 CTRL+C 與 CTRL+BREAK
- 實作細節：本機 console 測試
- 所需資源：命令列
- 預估時間：0.2 小時

關鍵程式碼/設定：
```csharp
class Program
{
    static readonly AutoResetEvent Shutdown = new AutoResetEvent(false);

    [DllImport("Kernel32")]
    static extern bool SetConsoleCtrlHandler(ConsoleCtrlDelegate handler, bool add);

    delegate bool ConsoleCtrlDelegate(CtrlType sig);
    enum CtrlType { CTRL_C_EVENT = 0, CTRL_BREAK_EVENT = 1, CTRL_CLOSE_EVENT = 2 }

    static void Main()
    {
        SetConsoleCtrlHandler(Handler, true);
        Console.WriteLine("# Service Started.");
        Shutdown.WaitOne();
        Console.WriteLine("# Shutdown Program...");
        Console.WriteLine("# Service Stopped.");
        SetConsoleCtrlHandler(Handler, false);
    }

    static bool Handler(CtrlType sig)
    {
        Console.WriteLine($"# Signal: {sig}");
        Shutdown.Set(); // 僅發訊號，不做重工作
        return true;    // 告知系統已處理
    }
}

------------------------------------------------------------

## Case #3: 為何 Console App 接不到 Shutdown/Logoff：SetConsoleCtrlHandler 的邊界

### Problem Statement（問題陳述）
業務場景：Console App 需攔截系統關機/logoff 以做清理，但使用 SetConsoleCtrlHandler 不生效。
技術挑戰：誤以為所有控制台事件對 Console App 都適用。
影響範圍：Console App 在 OS/容器關閉時無法優雅關閉。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 官方文件註明：CTRL_LOGOFF_EVENT/CTRL_SHUTDOWN_EVENT 僅適用 Windows Service。
2. Console App 沒有訊息泵，不會收到相應關機訊息。
3. 容器 stop 觸發語義與本機互動模式不同。
深層原因：
- 架構層面：誤用低階 API 於不支援的程序型態。
- 技術層面：忽略文件小字說明。
- 流程層面：缺少在實際容器環境的驗證。

### Solution Design（解決方案設計）
解決策略：對 OS/容器關機改用「隱藏 WinForms + WndProc 攔截 WM_QUERYENDSESSION」，對 CTRL+C/關閉視窗則保留 SetConsoleCtrlHandler；依場景選擇適配機制。

實施步驟：
1. 分析官方文件與支援矩陣
- 實作細節：確認哪些事件對 Console/Service 有效
- 所需資源：MSDN
- 預估時間：0.2 小時

2. 方案切換
- 實作細節：導入 WinForms 訊息泵處理 OS 關機
- 所需資源：System.Windows.Forms
- 預估時間：1 小時

3. 回歸測試
- 實作細節：docker stop、本機 ctrl+c
- 所需資源：Docker、終端機
- 預估時間：1 小時

關鍵程式碼/設定：
```csharp
// 結論性片段：記錄支援範圍（非執行碼）
/*
- SetConsoleCtrlHandler:
  - 支援：CTRL_C, CTRL_BREAK, CTRL_CLOSE
  - 不支援（Console App）：CTRL_LOGOFF, CTRL_SHUTDOWN
- WndProc (WM_QUERYENDSESSION):
  - 支援：OS 關機/Session 結束語義
  - 需要：訊息泵（WinForms/隱藏視窗）
*/

------------------------------------------------------------

## Case #4: 重現與驗證：docker stop 與 Console App 終止行為

### Problem Statement（問題陳述）
業務場景：需要可重現的驗證流程，判斷 docker stop 是否被 Console App 導入的關機處理成功攔截。
技術挑戰：容器內 stdout 在進程終止時可能中斷，觀測困難。
影響範圍：誤判方案可行性，導致上線風險。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. -f 追蹤 logs 會在容器 stop 後中斷，不一定看得到最後輸出。
2. 未建立系統化 build/run/stop 檢查流程。
3. 忽略以檔案輸出佐證最後訊息。
深層原因：
- 架構層面：缺少觀測性設計。
- 技術層面：對容器 stdout 行為了解不足。
- 流程層面：缺少標準化測試腳本。

### Solution Design（解決方案設計）
解決策略：建立固定流程（build → run → logs -f → stop），必要時導出檔案日誌輔助；對比 SetConsoleCtrlHandler 與 WndProc 版本，明確記錄實測結果。

實施步驟：
1. 撰寫 Dockerfile
- 實作細節：設定 ENTRYPOINT 指向可執行檔
- 所需資源：.NET 4.7.2 runtime 映像
- 預估時間：0.3 小時

2. 指令流程
- 實作細節：docker build/run/logs/stop；比對輸出
- 所需資源：Docker CLI
- 預估時間：0.3 小時

3. 檔案日誌備援
- 實作細節：最後輸出同步寫檔以確保觀測
- 所需資源：System.IO
- 預估時間：0.3 小時

關鍵程式碼/設定：
```dockerfile
FROM mcr.microsoft.com/dotnet/framework/runtime:4.7.2-windowsservercore-1709
WORKDIR C:/app
COPY . .
ENTRYPOINT ConsoleApplication.exe

------------------------------------------------------------

## Case #5: 在 Console App 建立隱藏 WinForms 與訊息泵（WndProc 攔截）

### Problem Statement（問題陳述）
業務場景：Console App 缺少 message pump，無法收到系統關機訊息；需在不轉成 Windows Service 的前提下補上此能力。
技術挑戰：如何在 Console App 中安全啟動 WinForms 訊息泵且不暴露 UI。
影響範圍：無法攔截關機、清理失敗、服務可用性問題。
複雜度評級：中

### Root Cause Analysis（根因分析）
直接原因：
1. 無訊息泵 → 收不到 WM_QUERYENDSESSION。
2. UI 依賴疑慮 → 不能引入可見窗體。
3. 執行緒模型不當 → 可能引發跨執行緒/STA 問題。
深層原因：
- 架構層面：Console 取代 Service 後的事件模型缺失。
- 技術層面：對 Win32 訊息機制掌握不足。
- 流程層面：未規劃 UI/非 UI 元件的最小依賴。

### Solution Design（解決方案設計）
解決策略：建立隱藏窗體（不可見、最小化、不在工作列），以 STA 背景執行緒啟動 Application.Run；在 WndProc 攔截 WM_QUERYENDSESSION 並以 WaitHandle 通知主線程執行關閉流程。

實施步驟：
1. 建立隱藏窗體類別
- 實作細節：Form.ShowInTaskbar=false, Visible=false
- 所需資源：System.Windows.Forms
- 預估時間：0.3 小時

2. 啟動訊息泵於 STA 背景執行緒
- 實作細節：Thread.SetApartmentState(STA)，Application.Run(form)
- 所需資源：System.Threading
- 預估時間：0.3 小時

3. 攔截 WM_QUERYENDSESSION
- 實作細節：override WndProc，設定 m.Result=1，發出 ShutdownEvent
- 所需資源：AutoResetEvent
- 預估時間：0.3 小時

關鍵程式碼/設定：
```csharp
public sealed class HiddenWindow : Form
{
    public readonly AutoResetEvent Signal = new AutoResetEvent(false);

    public HiddenWindow()
    {
        ShowInTaskbar = false;
        Visible = false;
        WindowState = FormWindowState.Minimized;
    }

    protected override void WndProc(ref Message m)
    {
        const int WM_QUERYENDSESSION = 0x0011;
        if (m.Msg == WM_QUERYENDSESSION)
        {
            m.Result = (IntPtr)1; // 告知系統可結束
            Console.WriteLine("winmsg: WM_QUERYENDSESSION");
            Signal.Set();
        }
        base.WndProc(ref m);
    }
}

------------------------------------------------------------

## Case #6: 使用 SystemEvents.SessionEnding（需啟動訊息泵）

### Problem Statement（問題陳述）
業務場景：希望以較高階 API 處理 Session 結束（關機/登出）事件，不直接碰觸 WndProc。
技術挑戰：SystemEvents 僅在有訊息泵時才會觸發。
影響範圍：若未啟動訊息泵，事件不會被引發，關閉處理失效。
複雜度評級：中

### Root Cause Analysis（根因分析）
直接原因：
1. SystemEvents 事件依賴 UI 訊息迴圈。
2. Windows Service/Console 預設無訊息泵。
3. 文件要求需使用隱藏窗體或手動啟動訊息泵。
深層原因：
- 架構層面：高階 API 背後依賴 Win32 訊息。
- 技術層面：忽略註解中的關鍵前提。
- 流程層面：未建立事件觸發條件檢查。

### Solution Design（解決方案設計）
解決策略：仍以隱藏窗體啟動 Application.Run，但改以 SystemEvents.SessionEnding 來接收事件，將處理邏輯從 WndProc 移至事件處理器。

實施步驟：
1. 啟動訊息泵（同 Case #5）
- 實作細節：隱藏窗體 + Application.Run
- 所需資源：WinForms
- 預估時間：0.5 小時

2. 註冊 SessionEnding
- 實作細節：Microsoft.Win32.SystemEvents.SessionEnding += Handler
- 所需資源：SystemEvents
- 預估時間：0.2 小時

3. 同步處理
- 實作細節：事件內僅 Set()，主線做清理
- 所需資源：AutoResetEvent
- 預估時間：0.2 小時

關鍵程式碼/設定：
```csharp
using Microsoft.Win32;

class Program
{
    static readonly AutoResetEvent Shutdown = new AutoResetEvent(false);

    static void Main()
    {
        var t = new Thread(() =>
        {
            using (var form = new Form { Visible = false, ShowInTaskbar = false })
            {
                SystemEvents.SessionEnding += (s, e) =>
                {
                    Console.WriteLine($"SystemEvents: {e.Reason}");
                    Shutdown.Set();
                };
                Application.Run(form);
            }
        });
        t.SetApartmentState(ApartmentState.STA);
        t.IsBackground = true;
        t.Start();

        Console.WriteLine("# Service Started.");
        Shutdown.WaitOne();
        Console.WriteLine("# Shutdown Program...");
        Console.WriteLine("# Service Stopped.");
    }
}

------------------------------------------------------------

## Case #7: 組合式關閉方案：同時支援 CTRL+C 與 OS 關機

### Problem Statement（問題陳述）
業務場景：Console App 需同時兼容本機互動（CTRL+C/關閉視窗）與容器/OS 關機事件。
技術挑戰：多來源關閉訊號整合、避免重入、確保流程單一。
影響範圍：多次關閉、死鎖、競態條件。
複雜度評級：中

### Root Cause Analysis（根因分析）
直接原因：
1. 兩套機制（SetConsoleCtrlHandler、WndProc）可能同時觸發。
2. 處理器內執行重任務易阻塞或重入。
3. 缺乏關閉流程的 idempotent 設計。
深層原因：
- 架構層面：缺少關閉協定抽象
- 技術層面：訊號整合與同步控管不足
- 流程層面：未做重入測試

### Solution Design（解決方案設計）
解決策略：以單一 CancellationTokenSource/WaitHandle 代表關閉狀態；所有入口僅觸發「設為已關閉」；主線程統一執行清理，確保 idempotent。

實施步驟：
1. 建立 ShutdownCoordinator
- 實作細節：封裝 Set()/Cancel() 與 IsShutdown
- 所需資源：C#
- 預估時間：0.5 小時

2. 註冊兩種來源
- 實作細節：CtrlHandler + WndProc 均呼叫 coordinator.Signal()
- 所需資源：見前案例
- 預估時間：0.5 小時

3. 主線統一關閉
- 實作細節：WaitOne/WaitHandle.WaitAny
- 所需資源：System.Threading
- 預估時間：0.5 小時

關鍵程式碼/設定：
```csharp
class ShutdownCoordinator
{
    private int _signaled = 0;
    public readonly ManualResetEventSlim Event = new ManualResetEventSlim(false);

    public void Signal()
    {
        if (Interlocked.Exchange(ref _signaled, 1) == 0)
        {
            Console.WriteLine("# Shutdown signaled.");
            Event.Set();
        }
    }
}

------------------------------------------------------------

## Case #8: 訊息泵與主工作同步：AutoResetEvent 的正確用法

### Problem Statement（問題陳述）
業務場景：關機訊息由 UI 訊息泵接收，主工作線需在安全時機執行清理。
技術挑戰：避免在 WndProc/事件中做長工作，導致阻塞或錯過系統截止。
影響範圍：卡死、清理不完全、強制終止。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 在 WndProc 執行長任務阻塞訊息處理。
2. 缺少安全同步機制。
3. 主線程未等待關閉訊號。
深層原因：
- 架構層面：未分離訊號接收與業務清理
- 技術層面：對 WaitHandle 用法不熟
- 流程層面：缺少關閉時間窗規劃

### Solution Design（解決方案設計）
解決策略：WndProc/事件中僅 Set()，主工作 WaitOne() 後執行清理；必要時加入超時與取消權杖。

實施步驟：
1. 導入 AutoResetEvent/ManualResetEventSlim
- 實作細節：事件發出→主線等待
- 所需資源：System.Threading
- 預估時間：0.2 小時

2. 清理流程設計
- 實作細節：短平快；外部呼叫加超時
- 所需資源：取消權杖
- 預估時間：0.5 小時

3. 測試阻塞風險
- 實作細節：在 WndProc 故意 sleep 驗證風險
- 所需資源：N/A
- 預估時間：0.3 小時

關鍵程式碼/設定：
```csharp
// WndProc 事件中
ShutdownEvent.Set(); // 只發訊號，避免阻塞 Message Pump

// 主線程
if (ShutdownEvent.Wait(TimeSpan.FromSeconds(8)))
{
    // 在 Docker 預設等待時間內完成清理（示例值）
    DoCleanup();
}
else
{
    Console.Error.WriteLine("Cleanup timeout, exiting.");
}

------------------------------------------------------------

## Case #9: 打包 .NET Framework Console App 到 Windows 容器

### Problem Statement（問題陳述）
業務場景：將 Console App 以 Windows 容器部署，需正確撰寫 Dockerfile 並匹配基底映像與 Host。
技術挑戰：Windows 版本對齊、ENTRYPOINT 正確、工作目錄與檔案複製。
影響範圍：容器啟動失敗、無法觀測日志、關閉無法驗證。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 映像版本與 Host 不相容。
2. ENTRYPOINT 指向錯誤。
3. 工作目錄/檔案路徑問題。
深層原因：
- 架構層面：對 Windows 容器版本策略不熟。
- 技術層面：Dockerfile 細節疏漏。
- 流程層面：缺少 build/run 基礎檢查。

### Solution Design（解決方案設計）
解決策略：使用對應版本的 .NET Framework runtime 映像，設定 WORKDIR、COPY、ENTRYPOINT；建立標準 build-run-stop 流程。

實施步驟：
1. 撰寫 Dockerfile
- 實作細節：選擇對齊 Host 的 windowsservercore tag
- 所需資源：Docker Hub/MCR
- 預估時間：0.3 小時

2. Build/Push/Run
- 實作細節：docker build、docker run -d、docker logs -f
- 所需資源：Registry（可選）
- 預估時間：0.5 小時

3. Stop 驗證
- 實作細節：docker stop；觀測關閉訊息
- 所需資源：N/A
- 預估時間：0.2 小時

關鍵程式碼/設定：
```dockerfile
FROM mcr.microsoft.com/dotnet/framework/runtime:4.7.2-windowsservercore-1709
WORKDIR C:/app
COPY . .
ENTRYPOINT ConsoleApplication.exe

------------------------------------------------------------

## Case #10: 觀測與除錯：docker logs -f 與檔案輸出

### Problem Statement（問題陳述）
業務場景：需在容器停止時確認是否真的執行了關閉處理；stdout 可能在停止瞬間中斷。
技術挑戰：最後輸出可能看不到，造成誤判。
影響範圍：錯誤決策、追查困難。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. docker logs -f 在容器 stop 後中斷。
2. Console.WriteLine 緩衝未刷出。
3. 缺少檔案日誌作為佐證。
深層原因：
- 架構層面：觀測性設計不足
- 技術層面：IO 緩衝與容器行為不了解
- 流程層面：沒有雙管齊下紀錄策略

### Solution Design（解決方案設計）
解決策略：關閉處理同時寫 stdout 與檔案，確保最後輸出可靠；關鍵輸出前調用 Flush。

實施步驟：
1. 加入檔案日誌
- 實作細節：File.AppendAllText 寫入關鍵事件
- 所需資源：磁碟可寫路徑
- 預估時間：0.2 小時

2. 刷寫 stdout 緩衝
- 實作細節：Console.Out.Flush()
- 所需資源：N/A
- 預估時間：0.1 小時

3. 測試 stop 行為
- 實作細節：比較 stdout 與檔案輸出
- 所需資源：N/A
- 預估時間：0.2 小時

關鍵程式碼/設定：
```csharp
void LogCritical(string msg)
{
    Console.WriteLine(msg);
    Console.Out.Flush(); // 確保輸出
    try { File.AppendAllText("C:\\app\\shutdown.log", msg + Environment.NewLine); } catch { /* 容錯 */ }
}

------------------------------------------------------------

## Case #11: 不可攔截情境管理：docker rm -f／斷電

### Problem Statement（問題陳述）
業務場景：在強制移除（docker rm -f）或斷電時，無法攔截關閉事件。需界定與補救策略。
技術挑戰：不可攔截導致無法主動下線。
影響範圍：服務發現殘留、短暫錯誤率上升。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 強制終止不投遞關閉訊號。
2. 容器瞬斷使應用無法執行任何清理。
3. 僅依賴應用內清理不夠。
深層原因：
- 架構層面：需配合外部協調者做容錯
- 技術層面：誤認為所有關閉都可攔截
- 流程層面：缺乏不可攔截場景策略

### Solution Design（解決方案設計）
解決策略：明確標註不可攔截情境，將關閉清理設計為 best-effort；同時依賴外部編排（orchestrator/健康檢查）或後台清理機制處理殘留（例如：由外部自動摘除不健康實例）。

實施步驟：
1. 辨識不可攔截清單
- 實作細節：docker rm -f、主機斷電
- 所需資源：文件/測試
- 預估時間：0.2 小時

2. 設計 best-effort 清理
- 實作細節：在可攔截事件進行下線
- 所需資源：應用內邏輯
- 預估時間：0.5 小時

3. 外部補救
- 實作細節：依賴 orchestrator 健康檢查
- 所需資源：平台支援
- 預估時間：0.5 小時

關鍵程式碼/設定：
```text
策略說明：
- 攔截到（CTRL+C/WM_QUERYENDSESSION）：主動下線
- 攔截不到（rm -f/斷電）：交由外部健康檢查與摘除流程

------------------------------------------------------------

## Case #12: 關閉處理只做「訊號＋短任務」的實作規範

### Problem Statement（問題陳述）
業務場景：關閉處理過長，會導致系統強制終止，留下半完成狀態。
技術挑戰：在短時間內完成必要清理，不阻塞訊息泵。
影響範圍：資料一致性、釋放資源、重啟風險。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 在訊息處理中執行長操作。
2. 無超時設計。
3. 無重試與降級計畫。
深層原因：
- 架構層面：缺少標準關閉規範
- 技術層面：同步機制誤用
- 流程層面：未建立關閉 SLO

### Solution Design（解決方案設計）
解決策略：Handler 中只做 Set() 與必要記錄；主線使用取消權杖與超時控制清理；清理動作設計為可重入/可補償。

實施步驟：
1. Handler/事件最小化
- 實作細節：僅 Set()/Log
- 所需資源：N/A
- 預估時間：0.1 小時

2. 主線清理超時
- 實作細節：CancellationTokenSource + Task.WhenAny
- 所需資源：Task、CTS
- 預估時間：0.5 小時

3. 清理動作可補償
- 實作細節：Idempotent 設計
- 所需資源：應用邏輯
- 預估時間：1 小時

關鍵程式碼/設定：
```csharp
var cts = new CancellationTokenSource(TimeSpan.FromSeconds(8));
var cleanup = Task.Run(async () =>
{
    await DeregisterAsync(cts.Token); // 可重試、可取消
    DisposeResources();
}, cts.Token);

await Task.WhenAny(cleanup, Task.Delay(Timeout.Infinite, cts.Token));

------------------------------------------------------------

## Case #13: 版本一致性與回歸測試矩陣設計

### Problem Statement（問題陳述）
業務場景：在 Windows 10/Server 不同版本上測試關閉處理，需確認行為一致。
技術挑戰：不同版本的容器/主機可能影響事件投遞行為。
影響範圍：跨環境不一致導致上線風險。
複雜度評級：中

### Root Cause Analysis（根因分析）
直接原因：
1. 主機/映像版本差異。
2. 不同版本網卡/驅動問題。
3. 測試未覆蓋多版本。
深層原因：
- 架構層面：缺少版本矩陣測試
- 技術層面：版本對齊策略不足
- 流程層面：未建立回歸標準

### Solution Design（解決方案設計）
解決策略：建立測試矩陣（Win10 1709/1803、WS 2016/1709 等），在每個環境進行 SetConsoleCtrlHandler 與 WndProc 對照測；記錄一致性。

實施步驟：
1. 明確矩陣
- 實作細節：羅列 OS/映像標籤
- 所需資源：文件
- 預估時間：0.3 小時

2. 自動化測試腳本
- 實作細節：PowerShell 迭代測試
- 所需資源：Docker/PS
- 預估時間：1 小時

3. 結果歸檔
- 實作細節：統一輸出到檔案
- 所需資源：日誌/報表
- 預估時間：0.5 小時

關鍵程式碼/設定：
```powershell
$tags = @("4.7.2-windowsservercore-1709", "4.7.2-windowsservercore-ltsc2016")
foreach ($tag in $tags) {
  docker build --build-arg BASETAG=$tag -t demo:$tag .
  docker run -d --name demo-$tag demo:$tag
  Start-Sleep -Seconds 2
  docker stop demo-$tag
  docker logs demo-$tag > out-$tag.txt
}

------------------------------------------------------------

## Case #14: UI 相依性最小化：隱藏視窗的安全設定

### Problem Statement（問題陳述）
業務場景：不希望引入可見 UI 或影響使用者桌面，但要使用 WinForms 的訊息泵。
技術挑戰：完全隱藏、避免任務列顯示與聚焦問題。
影響範圍：使用者體驗（在有桌面的環境）、混淆與誤操作。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 預設 Form 可能出現在任務列。
2. 可見性未正確設定。
3. 啟動時窗體狀態不當。
深層原因：
- 架構層面：UI 與非 UI 混用
- 技術層面：Form 屬性設定不熟
- 流程層面：未做 UX 影響評估

### Solution Design（解決方案設計）
解決策略：通過 ShowInTaskbar=false、Visible=false、WindowState=Minimized，並避免任何 UI 操作；專注於訊息攔截。

實施步驟：
1. 設定隱藏
- 實作細節：初始化表單時設定相關屬性
- 所需資源：WinForms
- 預估時間：0.1 小時

2. 禁用 UI 行為
- 實作細節：不做任何控件操作
- 所需資源：N/A
- 預估時間：0.1 小時

3. 驗證不暴露
- 實作細節：檢查任務列/焦點
- 所需資源：本機測試
- 預估時間：0.1 小時

關鍵程式碼/設定：
```csharp
public HiddenWindow()
{
    ShowInTaskbar = false;
    Visible = false;
    WindowState = FormWindowState.Minimized;
    // 無任何 UI 控件與顯示邏輯
}

------------------------------------------------------------

## Case #15: 正確處理 WM_QUERYENDSESSION：m.Result 設定與返回

### Problem Statement（問題陳述）
業務場景：收到 WM_QUERYENDSESSION 時，應用需以正確方式回應，避免阻礙系統關閉。
技術挑戰：不當回應可能造成系統等待/強制終止。
影響範圍：用戶體驗、資料一致性。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 未設定 m.Result 導致預設行為不確定。
2. 在 WndProc 長時間阻塞。
3. 當機處理不完善。
深層原因：
- 架構層面：事件回應缺規範
- 技術層面：對 WM_QUERYENDSESSION 契約不熟
- 流程層面：未設計錯誤處理

### Solution Design（解決方案設計）
解決策略：在 WndProc 中檢測 WM_QUERYENDSESSION 後，立即設定 m.Result=(IntPtr)1 表示同意關閉，僅發訊號，避免阻塞。

實施步驟：
1. 攔截訊息
- 實作細節：m.Msg == 0x11
- 所需資源：WinForms
- 預估時間：0.1 小時

2. 設置結果並發訊號
- 實作細節：m.Result=1；Set()
- 所需資源：AutoResetEvent
- 預估時間：0.1 小時

3. 測試
- 實作細節：docker stop 驗證
- 所需資源：Docker
- 預估時間：0.2 小時

關鍵程式碼/設定：
```csharp
protected override void WndProc(ref Message m)
{
    const int WM_QUERYENDSESSION = 0x11;
    if (m.Msg == WM_QUERYENDSESSION)
    {
        m.Result = (IntPtr)1; // 同意結束
        ShutdownEvent.Set();
        return; // 立即返回，避免阻塞
    }
    base.WndProc(ref m);
}

------------------------------------------------------------

## Case #16: 主程式結構設計：不阻塞主線、正確退出 Application.Run

### Problem Statement（問題陳述）
業務場景：需要訊息泵常駐且不阻塞主工作，關閉時要確保 Application.Run 能退出並釋放資源。
技術挑戰：如何在 Console App 中正確啟動/結束 WinForms 訊息泵。
影響範圍：資源洩漏、進程無法結束。
複雜度評級：中

### Root Cause Analysis（根因分析）
直接原因：
1. 訊息泵啟動於前景執行緒導致阻塞。
2. 關閉時未調用 Application.ExitThread。
3. 未正確處理 UI 執行緒生命週期。
深層原因：
- 架構層面：執行緒生命週期管理缺失
- 技術層面：WinForms 與 Console 執行緒互動理解不足
- 流程層面：無退出流程驗證

### Solution Design（解決方案設計）
解決策略：在背景 STA 執行緒啟動 Application.Run；收到關閉訊號後，主線清理完成再呼叫 Application.ExitThread 讓訊息泵退出，最後 Join UI 執行緒。

實施步驟：
1. 背景 STA 執行緒啟動訊息泵
- 實作細節：Thread + Application.Run
- 所需資源：WinForms
- 預估時間：0.3 小時

2. 結束訊息泵
- 實作細節：Application.ExitThread()
- 所需資源：N/A
- 預估時間：0.2 小時

3. Join 執行緒
- 實作細節：uiThread.Join()
- 所需資源：N/A
- 預估時間：0.1 小時

關鍵程式碼/設定：
```csharp
var uiThread = new Thread(() => Application.Run(new HiddenWindow()));
uiThread.SetApartmentState(ApartmentState.STA);
uiThread.IsBackground = true;
uiThread.Start();

// 關閉邏輯完成後：
System.Windows.Forms.Application.ExitThread();
uiThread.Join(TimeSpan.FromSeconds(2)); // 保守等待

------------------------------------------------------------

## Case #17: 與 Service Discovery 整合：關閉前主動下線（Consul 範例位）

### Problem Statement（問題陳述）
業務場景：服務需在進程終止前，立即向 Consul 通知下線，避免流量導向已關閉實例。
技術挑戰：確保在短關閉時間窗內完成 HTTP 請求且具重試。
影響範圍：錯誤率上升、使用者體驗下降。
複雜度評級：中

### Root Cause Analysis（根因分析）
直接原因：
1. 未攔截關閉事件。
2. 下線請求可能超時或失敗。
3. 無重試與超時控制。
深層原因：
- 架構層面：服務註冊/下線流程未標準化
- 技術層面：呼叫庫/網路異常處理不足
- 流程層面：未在容器關閉時測試

### Solution Design（解決方案設計）
解決策略：基於 Case #1 的攔截能力，在關閉訊號後，以短超時（例如 2-3s）對 Consul 發送 deregister；失敗記錄並快速放棄，避免阻塞整體關閉。

實施步驟：
1. 注入 Service Discovery Client
- 實作細節：HTTP Client 設短超時
- 所需資源：System.Net.Http
- 預估時間：0.5 小時

2. 實作 Deregister
- 實作細節：組出 /v1/agent/service/deregister/{id}
- 所需資源：Consul API
- 預估時間：0.5 小時

3. 關閉流程整合
- 實作細節：訊號→deregister（短超時、可重試一次）
- 所需資源：CTS
- 預估時間：0.5 小時

關鍵程式碼/設定：
```csharp
static async Task DeregisterAsync(string consulAddr, string serviceId, CancellationToken ct)
{
    using var http = new HttpClient { BaseAddress = new Uri(consulAddr), Timeout = TimeSpan.FromSeconds(2) };
    var resp = await http.PutAsync($"/v1/agent/service/deregister/{serviceId}", new StringContent(""), ct);
    Console.WriteLine($"Consul deregister: {(int)resp.StatusCode}");
}

------------------------------------------------------------

## Case #18: 測試與驗證腳本化：一次跑通 build→run→logs→stop

### Problem Statement（問題陳述）
業務場景：每次改動關閉邏輯後，都要快速驗證整條鏈路。
技術挑戰：手動驗證耗時、易漏步驟。
影響範圍：迭代慢、品質不穩。
複雜度評級：低

### Root Cause Analysis（根因分析）
直接原因：
1. 手動操作重複且易錯。
2. 無標準化腳本。
3. 缺少輸出比對。
深層原因：
- 架構層面：測試自動化不足
- 技術層面：腳本化能力不足
- 流程層面：無可追溯輸出

### Solution Design（解決方案設計）
解決策略：以 PowerShell 腳本統一執行 build/run/logs/stop，導出日志到檔案並比對是否包含關鍵字（如 WM_QUERYENDSESSION）。

實施步驟：
1. 腳本化
- 實作細節：封裝四步驟
- 所需資源：PowerShell
- 預估時間：0.5 小時

2. 關鍵字檢查
- 實作細節：Select-String 日誌內容
- 所需資源：N/A
- 預估時間：0.3 小時

3. 報表輸出
- 實作細節：輸出 pass/fail
- 所需資源：N/A
- 預估時間：0.2 小時

關鍵程式碼/設定：
```powershell
docker build -t demo.console .
docker rm -f demo.console 2>$null
docker run -d --name demo.console demo.console | Out-Null
Start-Sleep -Seconds 2
docker stop demo.console | Out-Null
docker logs demo.console > out.txt
if (Select-String -Path out.txt -Pattern "WM_QUERYENDSESSION") { "PASS" } else { "FAIL" }