[TFS 2017] 使用 Sandcastle 自動產生 API 說明文件

Sandcastle 是用來產生 .NET 文件,今天我要通過 TFS 自動化產生 .NET 說明文件

開發環境

  • Windows Server 2016
  • SQL 2016 Devloper SP1
  • TFS 2017 Update1
  • VS 2017 Update1

步驟

下載安裝 Sandcastle

https://github.com/EWSoftware/SHFB/releases

  • Sandcastle Help File Builder and Tools:TFS 跟 VS IDE 都要安裝
  • Sandcastle Help File Builder Visual Studio Package:VS IDE 安裝

勾選 XML Documentation file at VS2017

如下圖:

新增 Sandcastle 專案 at VS2017

,如下圖:

在 Sandcastle 專案 Documentation 加入 BLL.csproj,如下圖:


 

新增 SHFBROOT Capabilities at TFS2017

安裝完 Sandcastle Help File Builder and Tools 後 TFS 仍會建置失敗,因為 Agent Capabilities 沒有 SHFBROOT 的環境變數,所以建置路徑是錯的,如下圖:

解法就是新增 SHFBROOT Capabilities或是重新開機

新增一個 SHFBROOT | C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder,如下圖:

或者重新開機

 

複製檔案到成品區 at TFS2017

Help 是 Sandcastle 專案的輸出,文件最後會在這裡,我需要把它放到 $(build.artifactstagingdirectory),所以在 Contents 新增一個過濾條件 **\Help\**

 

執行建置後就能看到成品

 

設定IIS

IIS 網站結構目錄如下

 

Agent Service 的 Account 需要有存取 TFS 及 IIS 目錄的權限

 

發行說明文件 at TFS2017

我這邊用檔案複製來完成發行動作

Source Folder:成品區來源,$(System.DefaultWorkingDirectory)/Live Doc/drop/ApiLiveDoc/BLL.Documentation/Help

Contents:過濾條件,**

Target Folder:網站實體目錄,C:\inetpub\doc\api\LiveDoc

進階-Clean Target Folder:true

完成之後就可以在線上看到文件囉~

若有謬誤,煩請告知,新手發帖請多包涵


Microsoft MVP Award 2010~2017 C# 第四季
Microsoft MVP Award 2018~2022 .NET

Image result for microsoft+mvp+logo