Team System：打造自訂簽入策略，強化程式碼品質管控

在過去幾期專欄中，我們深入探討了 Team Foundation Server (TFS) 的版本控制與工作項目追蹤 API，並以此打造了一個 Microsoft Word 2003 增益集，實現文件簽入與工作項目關聯，彷彿 Visual Studio 2005 團隊總管的延伸。本期我們將聚焦於「簽入備註」與「簽入策略」——這兩項機制能在團隊層面強制執行規範，確保程式碼品質。下一期我將把這些功能整合進 Word 增益集中。

簽入備註與策略核心概念

簽入備註 是自由格式的文字欄位，可在簽入時攜帶分類資料。它們在團隊專案層級定義，可設為強制填寫。預設專案範本提供三種備註：「程式碼審閱者」、「安全性審閱者」與「效能審閱者」，皆非強制。您可透過團隊總管或 API 自訂備註，或在建立專案前修改程序範本中的 VersionControl.xml。定義時需指定標籤 (最長 64 字元)、是否必填、顯示順序；簽入時值最長可達 2048 + (2³⁰–1) 字元，前 2048 字元存在 nvarchar 欄位，超出部分存入 ntext。

簽入策略 則強制執行專案管理員訂定的規則，範圍從單純要求輸入註解，到執行靜態程式碼分析、執行測試等複雜邏輯。TFS 2005 內建三項策略，Power Tools 另補充四項，總計七項（見圖 1）。

策略安裝與啟用流程

實作策略需建立受控類別庫，實作 IPolicyDefinition 與 IPolicyEvaluation 兩個介面，並標記為可序列化。安裝步驟：

1. 將組件複製至安裝團隊總管的工作站。
2. 在登錄機碼 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\TeamFoundation\SourceControl\Checkin Policies 下新增字串值，Name 為組件檔名 (不含 .dll)，Data 為完整路徑。
3. 於團隊總管的「原始檔控制設定」→「簽入策略」索引標籤，按「新增」選取已註冊組件並啟用。

啟用後，每位開發人員的工作站皆需安裝該策略組件；TFS 目前無自動部署機制。

實作自訂策略：攔截「髒話」

以下示範建立一個掃描 .vb/.cs 檔案是否含「髒話」的策略：

1. 建立 Visual Basic 類別庫專案，加入 Microsoft.TeamFoundation.VersionControl.Client.dll 參考。
2. 實作 IPolicyDefinition：提供 Type、Description、InstallationInstructions 等屬性；若需設定對話框則實作 CanEdit/Edit。
3. 實作 IPolicyEvaluation：核心在 Evaluate 方法，枚舉 CheckedPendingChanges，讀取檔案內容並比對關鍵字清單，發現違規即建立 PolicyFailure 回傳。

Imports Microsoft.TeamFoundation.VersionControl.Client
Imports System.IO

<Serializable()> _
Public Class BadWords
    Implements IPolicyDefinition, IPolicyEvaluation

    Private badWords() As String = {"Dag", "Darn", "Doh"}
    <NonSerialized()> Private m_pendingCheckin As IPendingCheckin = Nothing

    ' IPolicyDefinition 實作省略...

    Public Function Evaluate() As PolicyFailure() Implements IPolicyEvaluation.Evaluate
        Dim failures As New List(Of PolicyFailure)
        For Each pc As PendingChange In m_pendingCheckin.PendingChanges.CheckedPendingChanges
            If pc.FileName.EndsWith(".vb") OrElse pc.FileName.EndsWith(".cs") Then
                Dim content As String = File.ReadAllText(pc.FileName)
                For Each w In badWords
                    If content.Contains(w) Then
                        failures.Add(New PolicyFailure(pc.FileName & " contains forbidden word: " & w, Me))
                        Exit For
                    End If
                Next
            End If
        Next
        Return failures.ToArray()
    End Function

    Public Sub Initialize(pendingCheckin As IPendingCheckin) Implements IPolicyEvaluation.Initialize
        m_pendingCheckin = pendingCheckin
    End Sub

    ' Activate、DisplayHelp、PolicyStateChanged、IDisposable 實作省略...
End Class

進階強化：精確定位與可設定關鍵字

初版策略僅回報檔案層級錯誤。為提供行號、程式碼片段等細節，需：

• 引入輔助類別 WordInfo (記錄關鍵字、行號、程式碼行)、CheckedFileInfo (檔案名、WordInfo 集合、PendingChange 參考)、BadWordPolicyFailure (繼承 PolicyFailure，攜帶 CheckedFileInfo)。
• 重寫 Evaluate 呼叫 GetWordInfo 逐行掃描，彙總違規資訊並封裝進 BadWordPolicyFailure。
• 實作 Activate 顯示詳細對話框 (雙擊錯誤時觸發)。
• 實作 IPolicyDefinition.Edit 提供關鍵字編輯 UI，並將清單持久化 (如文字檔)，取代硬式編碼陣列。

偵錯技巧

偵錯自訂策略：先從專案移除該策略、關閉所有 VS 實例，在策略專案屬性→偵錯分頁將「啟動動作」設為 devenv.exe，於 Type 與 Evaluate 設中斷點啟動偵錯。第二個 VS 執行個體會載入策略，命中中斷點即可逐步偵錯。

簽入策略框架極具彈性，未來期盼 Microsoft 改善安裝部署體驗。下一期將示範如何在程式碼與 Word 增益集中程式化運用簽入備註與策略。