Team System：TFS 版本控制核心架構與 Word 增益集實作入門

專欄緣起於 2004 年參與代號「Burton」的設計評審，當時不斷詢問「有擴充點嗎？」得到的回答總是「有的，Brian，你可以自訂」。Burton 後來成為 Visual Studio Team System，而如何自訂擴充正是本專欄主軸。首期我們將建立一個 Word 2003 增益集，實現文件簽入/簽出 TFS 版本控制存儲庫。

先決條件與組件參考

• Visual Studio 2005 Professional (或含 Team Suite 的角色型 SKU)
• Visual Studio 2005 Tools for Office Second Edition Beta
• Visual Studio 2005 Team Explorer
• Visual Studio 2005 SDK (msdn.microsoft.com/vstudio/extend)

核心 API 分散於三個組件 (隨 Team Explorer 安裝至 GAC，但未註冊至「加入參考」對話框)：

• Microsoft.TeamFoundation.Client.dll
• Microsoft.TeamFoundation.VersionControl.Client.dll
• Microsoft.TeamFoundation.VersionControl.Common.dll

需手動瀏覽 %Program Files%\Microsoft Visual Studio 8\Common7\IDE\PrivateAssemblies\ 加入參考，或修改登錄表使其顯示 (KB 306149)。

連線 TFS 與驗證

建立 tfsvcUtil 類別庫，核心邏輯封裝於共用成員中。連線步驟：

1. 建立 UICredentialsProvider 以便彈出登入對話框。
2. 呼叫 TeamFoundationServerFactory.GetServer(serverName, credentialsProvider) 取得 TeamFoundationServer 根物件。
3. 呼叫 Authenticate() 驗證身分。
4. 透過 GetService(GetType(VersionControlServer)) 取得 VersionControlServer 服務參考。

Public Shared Sub Connect(ByVal fqServerName As String, ByVal showLoginUI As Boolean)
    Try
        m_serverName = fqServerName
        If showLoginUI Then
            Dim icp As ICredentialsProvider = New UICredentialsProvider
            m_tfs = TeamFoundationServerFactory.GetServer(m_serverName, icp)
        Else
            m_tfs = TeamFoundationServerFactory.GetServer(m_serverName)
        End If
        m_tfs.Authenticate()
        m_tfsVCS = CType(m_tfs.GetService(GetType(VersionControlServer)), VersionControlServer)
        serverValidated = True
    Catch ex As Exception
        Throw New tfsUtilException(String.Format(MSG_UNEXPECTED, "Connect"), ex, m_serverName)
    End Try
End Sub

另提供接受「伺服器/通訊協定/連接埠」分離參數的多載。

工作區與資料夾對應

TFS 以「工作區」管理用戶端檔案。首次使用 Team Explorer 會以電腦名建立預設工作區。增益集需自行檢查/建立：

• 呼叫 Workstation.Current.GetLocalWorkspaceInfo(docPath) 取得 WorkspaceInfo；若無對應則回傳 Nothing。
• 若無現有對應，呼叫 GetDefaultWorkspace 取得或建立預設工作區 (以電腦名命名)。
• 建立 WorkingFolder 對應伺服器路徑 ($/TeamProject/...) 與本地資料夾，呼叫 Workspace.CreateMapping 註冊對應 (重複呼叫不會報錯)。

核心版控操作：PendAdd / PendEdit / CheckIn

• PendAdd：首次將文件納入版控，呼叫 Workspace.PendAdd(docPath)，回傳排隊項目數 (預期為 1)。
• GetPendingChanges：以文件路徑查詢 PendingChange() 陣列。
• CheckIn：傳入 PendingChange() 陣列與註解，回傳變更集編號；簽入成功後用戶端 API 會啟用檔案唯讀屬性。
• PendEdit：簽出編輯，用法同 PendAdd。

輔助 UI 表單

因 TFS 未公開「指定伺服器」、「加入版控」、「簽入」等對話框，專案另備三個 Windows Forms：

• frmAddTFS：輸入伺服器名、通訊協定、連接埠 (圖 2)。
• frmAddtoSCC：樹狀瀏覽專案與資料夾，支援即時展開載入子資料夾 (圖 3)。
• frmCheckIn：顯示待簽入文件與註解文字框 (圖 1)。

增益集整合細節

• 額外輔助方法：Disconnect (切換伺服器)、GetDocumentVCStatus (同步命令列按鈕狀態)、IsDocumentUnderVersionControl (檢查文件是否受版控)。
• 簽入需獨佔鎖定，增益集必須先關閉文件、執行簽入、再重新開啟。

透過豐富的 API，我們得以快速建構出可將 Word 文件納入 TFS 版控、共享管理的增益集。後續專欄將持續強化功能。