自訂您的組建

  • 發行項

使用標準建置程序 (匯入 Microsoft.Common.props 和 Microsoft.Common.targets) 的 MSBuild 專案有幾個擴充性攔截程序，可以用來自訂您的建置程序。

許多可自訂的建置作業是由屬性所控制。 請務必知道設定屬性值的方式和位置，才能產生所需的效果。 您可以在命令列上 (以及在回應檔中)、在特殊檔案 (例如 Directory.Build.props) 中、在匯入的檔案中，或在專案檔中設定屬性。 請務必知道屬性的使用位置、設定或變更和匯入檔案的順序，包括從 .NET SDK 之類的 SDK 隱含匯入。

如需屬性清單，請參閱 MSBuild 通用屬性。

探索自訂選項

下列自訂選項會依增加複雜度和影響範圍的順序列出。 建議您從此清單頂端開始，使用最不複雜的自定義選項來符合您的目的。

自訂選項 描述
將引數新增至 MSBuild 命令列 設定會影響主要專案組件和所有相依專案之組建的全域屬性。
自訂單一專案的組建 將屬性新增至 .props 或 .targets 檔案，以自訂群組建設定。
處理建置程式中產生的檔案 如何確定產生的檔案已正確包含組建輸出。
自訂一或多個專案的組建 將屬性新增至 Directory.Build.props，或將屬性和目標新增至 Directory.Build.targets，以自訂資料夾之下所有專案的組建。 這項技術適用於設定 SDK 所設定或使用的屬性，以及設定自訂範圍，使其影響資料夾或子資料夾中的所有專案。
自訂本機組建 在本機電腦上對組建進行變更，而不影響共用來源檔案。
自訂所有 .NET 組建 針對 .NET 組建，自訂全系統範圍的組建。
自訂 C++ 組建 自訂 C++ 組建，範圍設定為專案、解決方案、資料夾，或受系統上 MSBuild 安裝所控管的所有組建。

將引數新增至專案的命令列 MSBuild 引動過程

您可以在命令列上設定全域屬性。 全域屬性會影響所有專案組建，包括相依性。 回想一下，建置專案會自動觸發所有專案相依性的可能組建。 MSBuild 的一般行為是建置任何過期的相依專案。 這些相依專案組建會從命令列使用與原始專案相同的全域屬性設定來啟動。

來源目錄中或更新版本的 Directory.Build.rsp 檔案會套用至專案的命令行組建。 如需詳細資料，請參閱 MSBuild 回應檔。

選擇將屬性新增至 .props 或 .targets 檔案

MSBuild 需相依於匯入順序，且屬性的最後一個定義 (或是 UsingTask 或目標) 將會是系統所使用的定義。

使用明確匯入時，您可以在任何時間點從 .props 或 .targets 檔案匯入。 以下是廣泛使用的慣例：

  • .props 檔案會以較早的匯入順序匯入。

  • .targets 檔案會以較晚的匯入順序匯入。

此慣例會由 <Project Sdk="SdkName"> 匯入強制執行 (也就是 Sdk.props 的匯入會在該檔案所有內容之前先發生，而 Sdk.targets 則會在檔案的所有內容之後最後發生)。

決定要將屬性置於何處時，請使用下列一般指導方針：

  • 對於許多屬性而言，定義它們的位置並不重要，因為它們不會被覆寫，而且只會在運行時間讀取。

  • 針對可能會在個別專案中自訂的行為，請將預設值設定在 .props 檔案中。

  • 藉由讀取可能自定義屬性的值，避免在檔案中 .props 設定相依屬性，因為在 MSBuild 讀取使用者的專案之前，不會發生自定義。

  • 在檔案中 .targets 設定相依屬性，因為它們會從個別項目挑選自定義專案。

  • 如果您需要覆寫屬性，請在所有使用者專案自訂皆有機會生效之後，於 .targets 檔案中這麼做。 請謹慎使用衍生屬性；您可能也需要覆寫衍生屬性。

  • 將項目包含在 .props 檔案中 (在屬性上設定條件)。 所有屬性都會在任何專案之前考慮，因此會挑選用戶專案屬性自定義，而且在檔案中 .props 匯入專案可讓使用者的專案有機會 Remove 或 Update 匯入所引進的任何專案。

  • 在 .targets 檔案中定義目標。 不過，如果 .targets 檔案是由 SDK 匯入，請記得此案例會使覆寫目標變得更為困難，因為使用者的專案預設並沒有位置可以覆寫它。

  • 可能的話，請盡量在評估期間自訂屬性，而非在目標內變更屬性。 此指導方針可讓載入專案並了解其進行情況的工作變得更加容易。

相關內容