使用相依性圖表驗證程式碼

為什麼要使用相依性圖表？

若要確定程式碼不會與其設計相衝突，請在 Visual Studio 中以相依性圖表驗證程式碼。 這可協助您：

• 尋找在您的程式碼與相依性圖表相依性之間的衝突。

• 尋找可能會受到建議變更所影響的相依性。

  例如，您可以編輯相依性圖表來顯示潛在的架構變更，然後驗證程式碼，以便查看受影響的相依性。

• 將程式碼重構或移轉至不同設計。

  在您將程式碼移至不同的架構時，請尋找需要運作的程式碼或相依性。

需求

• Visual Studio

  若要建立 .NET Core 專案的相依性圖表，您必須擁有 Visual Studio 2019 16.2 版或更新版本。

• 包含模型專案具有相依性圖表的解決方案。 這張相依性圖表必須與您要驗證的 C# 或 Visual Basic 專案的成品連結。 請參閱從您的程式碼建立相依性圖表 (部分機器翻譯)。

若要查看哪些 Visual Studio 版本支援這項功能，請參閱結構和模型化工具的版本支援 (部分機器翻譯)。

您可以在 Visual Studio 中的開放相依性圖表，或從命令提示字元手動驗證程式碼。 您也可以在執行本機組建或 Azure Pipelines 組建時自動驗證程式碼。

重要

如果您要使用 Team Foundation Server (TFS) 執行圖層驗證，則也必須在您的組建伺服器上安裝相同版本的 Visual Studio。

即時相依性驗證

相依性驗證會即時發生，錯誤會立即顯示在 [錯誤清單] 中。

• C# 和 Visual Basic 支援即時驗證。

• 若要在使用即時相依性驗證時啟用完整解決方案分析，請從 [錯誤清單] 中出現的金色列開啟選項設定。

  • 如果您不想要查看解決方案中的所有架構問題，您可以永久關閉金色列。
  • 如果您未啟用完整的解決方案分析，則只會針對正在編輯的檔案執行分析。

• 升級專案以啟用即時驗證時，對話方塊會顯示轉換的進度。

• 更新專案以進行即時相依性驗證時，NuGet 套件會針對所有專案升級為相同的版本，且是使用中最高的版本。

• 新增相依性驗證專案會觸發專案更新。

查看項目是否支援驗證

您可以將圖層連結到網站、Office 文件、純文字檔以及跨多個應用程式共用專案中的檔案，不過，驗證流程不包含這些檔案。 對於連結至個別圖層之專案或組件的參考，如果這些圖層之間沒有任何相依性，則不會出現驗證錯誤。 除非程式碼使用這些參考，否則不會考量此類參考的相依性。

1. 在相依性圖表上，選取一個或多個圖層，以滑鼠右鍵按一下選取範圍，然後按一下 [檢視連結]。

2. 在 [圖層總管] 中，查看 [支援驗證] 資料行。 如果值為 false，則這個項目不支援驗證。

包含其他 .NET 組件和專案來進行驗證

當您拖曳項目到相依性圖表時，參考對應的 .NET 組件或專案會自動新增至模型專案的 [圖層參考] 資料夾。 這個資料夾包含組件的參考以及驗證期間分析的專案。 您也可以手動包含其他 .NET 組件和專案以進行驗證，而不用手動拖曳到相依性圖表。

1. 在 [方案總管] 中，以滑鼠右鍵按一下模型專案或 [圖層參考] 資料夾，然後按一下 [新增參考]。

2. 在 [新增參考] 對話方塊中選取組件或專案，然後按一下 [確定]。

手動驗證程式碼

如果您有連結至解決方案項目的已開啟相依性圖表，您可以從圖表執行 [驗證] 捷徑命令。 您也可以使用命令提示字元執行 msbuild 命令，其中 /p:ValidateArchitecture 自訂屬性設定為 True。 例如，在您變更程式碼時定期執行圖層驗證，以便早期攔截相依性衝突。

從開啟的相依性圖表驗證程式碼

1. 以滑鼠右鍵按一下圖表介面，然後按一下 [驗證架構]。

   注意

   根據預設，相依性圖表 (.layerdiagram) 檔案的 [建置動作] 屬性會設為 [驗證]，以便在驗證程序中納入圖表。

   [錯誤清單] 視窗會報告發生的任何錯誤。 如需驗證錯誤的詳細資訊，請參閱針對圖層驗證問題進行疑難排解。

2. 若要檢視每個錯誤的來源，請按兩下 [錯誤清單] 視窗中的錯誤。

   注意

   Visual Studio 可能會顯示 Code Map，而非錯誤來源。 如果程式碼具有並非由相依性圖表所指定的組件相依性，或是程式碼遺失了相依性圖表所指定的相依性，則會出現此情況。 請檢閱 Code Map 或程式碼，以判斷相依性是否應存在。 如需 Code Map 的詳細資訊，請參閱對應解決方案之間的相依性。

3. 若要管理錯誤，請參閱解決圖層驗證錯誤。

在命令提示字元驗證程式碼

1. 開啟 Visual Studio 命令提示字元。

2. 選擇下列其中一項：

   • 若要根據解決方案中的特定模型專案來驗證程式碼，請使用下列自訂屬性執行 MSBuild。

     msbuild <FilePath+ModelProjectFileName>.modelproj /p:ValidateArchitecture=true
     

     -或-

     瀏覽至包含模型專案 (.modelproj) 檔案和相依性圖表的資料夾，然後使用下列自訂屬性執行 MSBuild：

     msbuild /p:ValidateArchitecture=true
     

   • 若要根據解決方案中的所有模型專案來驗證程式碼，請使用下列自訂屬性執行 MSBuild：

     msbuild <FilePath+SolutionName>.sln /p:ValidateArchitecture=true
     

     -或-

     瀏覽至方案資料夾 (其中必須包含相依性圖表所在的模型專案)，然後使用下列自訂屬性執行 MSBuild：

     msbuild /p:ValidateArchitecture=true
     

     發生的任何錯誤都將列出。 如需 MSBuild 的詳細資訊，請參閱 MSBuild 和 MSBuild 工作。

   如需驗證錯誤的詳細資訊，請參閱針對圖層驗證問題進行疑難排解。

管理驗證錯誤

在開發過程中，您可以隱藏驗證期間已報告過的某些衝突。 例如，您可能會想要隱藏已經處理的錯誤，或是與特定情節無關的錯誤。 當您隱藏錯誤時，最好在 Team Foundation 中記錄工作項目。

警告

您必須先連接 TFS 原始程式碼控制 (SCC) 才能建立或連結工作項目。 若您嘗試開啟連接至不同的 TFS SCC，Visual Studio 會自動關閉目前方案。 請先確認您已連接至適當的 SCC，再嘗試建立或連結至工作項目。 在更新版本的 Visual Studio 中，如果沒有連接至 SCC 即無法使用功能表命令。

針對驗證錯誤建立工作項目

• 在 [錯誤清單] 視窗中，以滑鼠右鍵按一下警告、指向 [建立工作項目]，然後按一下您要建立的工作項目類型。

使用下列工作來管理 [錯誤清單] 視窗中的驗證錯誤：

目標	請依照下列步驟：
在驗證期間隱藏選取的錯誤	以滑鼠右鍵按一下一個或多個選取的錯誤、指向 [管理驗證錯誤]，然後按一下 [隱藏錯誤]。 隱藏的錯誤會以刪除線的格式出現。 當您下一次執行驗證時，這些錯誤將不會出現。 隱藏的錯誤會在對應相依性圖表檔案的 .suppressions 檔案中追蹤。
停止隱藏選取的錯誤	以滑鼠右鍵按一下一個或多個選取的隱藏錯誤、指向 [管理驗證錯誤]，然後按一下 [停止隱藏錯誤]。 選取的隱藏錯誤將會在下一次執行驗證時出現。
在 [錯誤清單] 視窗中還原所有隱藏的錯誤	以滑鼠右鍵按一下 [錯誤清單] 視窗中的任何位置、指向 [管理驗證錯誤]，然後按一下 [顯示所有隱藏的錯誤]。
在 [錯誤清單] 視窗中隱藏所有隱藏的錯誤	以滑鼠右鍵按一下 [錯誤清單] 視窗中的任何位置、指向 [管理驗證錯誤]，然後按一下 [隱藏所有隱藏的錯誤]。

自動驗證程式碼

您可以在每次執行本機組建時執行圖層驗證。 如果您的小組使用 Azure DevOps，可以閘道簽入來執行圖層驗證，其中您可以藉由建立自訂 MSBuild 工作來指定，以及使用組建報告收集驗證錯誤。 若要建立閘道簽入組建，請參閱 TFVC 閘道簽入。

在本機組建執行期間自動驗證程式碼

使用文字編輯器來開啟模型專案 (.modelproj) 檔案，然後加入下列屬性：

<ValidateArchitecture>true</ValidateArchitecture>

- 或 -

1. 在 [方案總管] 中，以滑鼠右鍵按一下包含一個或多個相依性圖表的模型專案，然後按一下 [屬性]。

2. 在 [屬性] 視窗中，將模型專案的 [驗證架構] 屬性設為 [True]。

   這會將模型專案納入驗證程序中。

3. 在 [方案總管] 中，按一下要用於驗證作業的相依性圖表圖層圖表 (.layerdiagram) 檔案。

4. 在 [屬性] 視窗中，確定圖表的 [建置動作] 屬性已設為 [驗證]。

   這會將相依性圖表納入驗證程序中。

若要管理 [錯誤清單] 視窗中的錯誤，請參閱解決圖層驗證錯誤。

疑難排解圖層驗證問題

下列表格描述圖層驗證的問題及其解決方式。 這些問題不同於因程式碼與設計衝突而導致的錯誤。 如需這些錯誤的詳細資訊，請參閱針對圖層驗證問題進行疑難排解。

問題	可能的原因	解決方案
發生非預期的驗證錯誤。	若圖層圖表是從方案總管中的其他相依性圖表或是從相同模型專案中的相依性圖表複製而來，系統即不會對此相依性圖表進行驗證。 以這種方式複製的相依性圖表所包含的參考會與原始相依性圖表相同。	請將新的相依性圖表新增至模型專案。 將來源相依性圖表中的項目複製到新圖表。

解決圖層驗證的錯誤

當您針對相依性圖表驗證程式碼時，如果程式碼設計發生衝突便會產生驗證錯誤。 例如，下列條件可能造成圖層驗證發生錯誤：

• 成品指派給錯誤的圖層。 在此情況下，請移動成品。

• 類別之類的成品以與架構發生衝突的方式使用另一個類別。 在此情況下，請重構程式碼以移除相依性。

若要解決這些錯誤，請更新程式碼直到驗證時不再出現錯誤為止。 您可以透過互動方式執行這項工作。

以下章節說明用於這些錯誤的語法，解釋這些錯誤的意義，並且建議解析或管理這些錯誤的作法。

語法	說明
ArtifactN(ArtifactTypeN)	ArtifactN 是與相依性圖表上的圖層相關聯的成品。 ArtifactTypeN 是 ArtifactN 的類型 (如 [類別] 或 [方法])，例如： MySolution.MyProject.MyClass.MyMethod(Method)
NamespaceNameN	命名空間的名稱。
LayerNameN	相依性圖表上圖層的名稱。
DependencyType	Artifact1 與 Artifact2 之間的相依性關聯性類型。 例如，Artifact1 與 Artifact2 具有 [呼叫] 關聯性。

錯誤語法	錯誤描述
DV0001：無效的相依性	當對應至 Layer 的程式碼項目 (命名空間、類型、成員) 參考對應至另一層的程式碼項目時，就會回報此問題，但在包含此圖層的相依性驗證圖表中，這些圖層之間沒有相依性箭號。 這是相依性條件約束違規。
DV1001：無效的命名空間名稱	此問題會在程式碼項目中回報，該程式碼項目是與「允許的命名空間名稱」屬性不包含定義此程式碼項目命名空間的圖層相關聯。 這是命名條件約束違規。 請注意，「允許的命名空間名稱」語法將為命名空間分號清單，其中允許定義與程式碼項目相關聯的圖層。
DV1002：對不可參考命名空間的相依性	此問題會在程式碼項目中回報，該程式碼項目與圖層相關聯，並且參考在命名空間中定義的另一個程式碼項目，該命名空間會在圖層的「不可參考的命名空間」屬性中定義。 這是命名條件約束違規。 請注意，「不可參考的命名空間」屬性定義為在已與這個圖層建立關聯的程式碼項目中，不應參考的分號分隔命名空間清單。
DV1003：不允許的命名空間名稱	此問題是在程式碼項目中回報，該程式碼項目是與「不允許的命名空間名稱」屬性包含定義此程式碼項目命名空間的圖層相關聯。 這是命名條件約束違規。 請注意，「不允許的命名空間名稱」屬性定義為在與這個圖層建立關聯的不應定義程式碼項目中的分號分隔命名空間清單。
DV2001：圖層圖表目前狀態	此問題會在不包含相依性圖表檔案的專案上回報，但會參考相依性驗證分析器。 如果尚未使用相依性驗證，您可以直接從 [方案總管] 移除「Microsoft.DependencyValidation.Analyzers」或是隱藏此警告。 若要新增相依性圖表，請參閱從您的程式碼建立相依性圖表 (部分機器翻譯)。
DV2002：未對應的類型基礎	當程式碼項目未對應至任何圖層時，就會回報此問題。
DV3001：遺漏連結	圖層 'LayerName' 連結至找不到的 'Artifact'。 您是否遺漏了組件參考?
DV9001：架構分析發現內部錯誤	結果可能不完整。 如需詳細資訊，請參閱詳細建置事件記錄檔或輸出視窗。

相關內容

• Visual Studio 中的即時相依性驗證
• 在開發期間驗證您的系統
• 影片：即時驗證結構相依性