MSBuild

  • 發行項

Microsoft Build Engine 是建置應用程式的平台。 這個引擎也稱為 MSBuild，提供了專案檔的 XML 結構描述，以控制組建平台處理和建置軟體的方式。 Visual Studio 會使用 MSBuild，但 MSBuild 並不倚賴 Visual Studio。 藉由在專案或方案檔上叫用 msbuild.exe 或 dotnet build，就可以在未安裝 Visual Studio 的環境中組織及建置產品。

Visual Studio 會使用 MSBuild 載入及建置 Managed 專案。 Visual Studio 中的專案檔 (.csproj、.vbproj、.vcxproj 等等) 包含 MSBuild XML 程式碼，該程式碼會在您使用 IDE 建置專案時執行。 Visual Studio 專案會匯入所有必要的設定，並建置執行一般開發工作的流程，但是您可以在 Visual Studio 內或使用 XML 編輯器擴充或修改它們。

若要在沒有 Visual Studio 的 Windows 系統上安裝 MSBuild，請移至下載頁面上的 Build Tools for Visual Studio。 透過此方法安裝 MSBuild 會為您提供 MSBuild.exe。

針對 .NET Core 和 .NET 5 或更新版本，取得與 MSBuild 同等項目的另一種方式是安裝 .NET SDK。 .NET 建置命令 dotnet build 可在 macOS、Windows 或 Linux 上與 .NET SDK 搭配使用。 .NET 建置命令 dotnet build 是 .NET Core 版本 MSBuild.exe 的精簡包裝函式。 您可以使用 .NET Core 命令列介面 (CLI)，其使用 MSBuild 來建置以 .NET Core 和 .NET 5 和更新版本為目標的專案。

從 Visual Studio 2022 開始，當您在 Visual Studio 中建置時，會使用 64 位元版本的 MSBuild。

如需適用於 C++ 的 MSBuild 的詳細資訊，請參閱 MSBuild ( C++)。

下列範例說明何時可能會從命令列叫用 MSBuild，而不是從 Visual Studio IDE。

  • 未安裝 Visual Studio。

  • 您想要使用 64 位元版本的 MSBuild，而您使用的是 Visual Studio 2019 或更早版本。 通常並不需要這個版本的 MSBuild，不過它可讓 MSBuild 存取更多記憶體。

  • 您想要在多個流程中執行組建。 不過，您可以使用 IDE 在 C++ 和 C# 的專案中得到相同的結果。

  • 您想要修改建置系統。 例如，您可能會想要啟用下列動作：

    • 使用編譯器處理檔案之前，先對檔案進行前置處理。

    • 將組建輸出複製到不同位置。

    • 從組建輸出建立壓縮檔。

    • 進行後續處理步驟。 例如，您可能想要對組件加上不同版本的戳記。

您可以在 Visual Studio IDE 中撰寫程式碼，但是使用 MSBuild 執行組建。 另一種替代方式是，您可以在開發電腦的 IDE 中建置程式碼，但是從命令列執行 MSBuild 以建置程式碼，該程式碼是從多位開發人員共同作業的來源存放庫所整合。

注意

您可以使用 Azure Pipelines 自動編譯、測試和部署您的應用程式。 您的建置系統可以在開發人員簽入程式碼 (例如，做為連續整合策略的一部分) 時或是根據排程 (例如，夜間組建驗證測試組建) 自動執行組建。 Azure Pipelines 會使用 MSBuild 編譯您的程式碼。 如需詳細資訊，請參閱 Azure Pipelines。

如需 Windows 上 MSBuild 的入門教學課程，請參閱逐步解說：使用 MSBuild。

在命令提示字元中使用 MSBuild

若要在命令提示字元執行 MSBuild，請使用適當的命令列選項，將專案檔傳遞給 MSBuild.exe。 命令列選項能讓您設定屬性、執行特定目標，以及設定可控制建置流程的其他選項。 例如，您可以使用下列命令列語法，在 Configuration 屬性設為 Debug 的情況下建置 MyProj.proj 檔案。

MSBuild.exe MyProj.proj -property:Configuration=Debug

MSBuild 不會根據副檔名改變其行為，但慣例是：針對主要的 MSBuild 輸入檔 (稱為「專案檔案」) 使用 proj 為副檔名結尾，例如 .csproj、.vcxproj 或 .vbproj。

如需 MSBuild 命令列選項的詳細資訊，請參閱命令列參考。

重要

下載專案之前，請判斷程式碼的可信度。

針對 .NET Core 和 .NET 5 或更新版本，您通常會使用 dotnet build 來叫用 MSBuild。 請參閱 dotnet build。 如果您只安裝 .NET SDK，而不是 Visual Studio 或 Visual Studio Build Tools，則只能透過 dotnet build 具有 MSBuild。

命令列 dotnet build --help 會列出 dotnet build 特定的命令列選項，而不是 MSBuild.exe 的所有選項，但是您仍然可以使用 MSBuild 命令列參考中列出的所有命令列選項。 dotnet build 未處理的選項會傳遞至 MSBuild。

專案檔

MSBuild 會使用直接且可擴充的 XML 專案檔格式。 MSBuild 專案檔格式讓開發人員可以描述將要建置的項目，以及如何針對不同的作業系統和組態來建置這些項目。 此外，專案檔格式還能讓開發人員撰寫可重複使用的建置規則供個別檔案使用，讓這些組建在產品內的不同專案中仍有一致的表現。

Visual Studio 建置系統會將專案特定的邏輯儲存在專案檔本身，並使用具有 .props 和 .targets 之類副檔名的匯入 MSBuild XML 檔案，來定義標準建置邏輯。 .props 檔案會定義 MSBuild 屬性，.targets 檔案會定義 MSBuild 目標。 這些匯入有時會顯示在 Visual Studio 專案檔中，但是在較新的專案中，例如 .NET Core、.NET 5 和 .NET 6 專案中，您看不到專案檔中的匯入；而是會看到 SDK 參考，如下所示：

<Project Sdk="Microsoft.Net.Sdk">

這些稱為 SDK 樣式專案。 當您參考 .NET SDK 之類的 SDK 時，SDK 會隱含指定 .props 和 .target 檔案的匯入。

下列章節將說明 MSBuild 專案檔格式的一些基本項目。 如需如何建立基本專案檔的教學課程，請參閱逐步解說：從頭開始建立 MSBuild 專案檔。

屬性

屬性表示成對的索引鍵/值組，可以用來設定組建。 宣告屬性的方式是建立具有屬性名稱的項目，做為 PropertyGroup 項目的子項目。 例如，下列程式碼會建立名為 BuildDir 並具有 Build 值的屬性。

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

您可以在項目中放入 Condition 屬性 (Attribute)，藉此定義條件式屬性 (Property)。 除非條件判斷值為 true，否則會忽略條件式項目的內容。 下列範例會定義 Configuration 屬性 (如果尚未定義的話)。

<Configuration  Condition=" '$(Configuration)' == '' ">DefaultValue</Configuration>

使用語法 $(<PropertyName>)，就可以在整個專案檔中參考屬性。 例如，您可以使用 $(BuildDir) 和 $(Configuration) 參考上述範例中的屬性。

如需屬性的詳細資訊，請參閱 MSBuild 屬性。

項目

項目是建置系統的輸入內容，通常代表檔案。 項目會依據使用者定義的項目名稱分組為各個項目類型。 這些項目類型可以做為工作的參數，工作會使用個別項目來執行建置流程的步驟。

在專案檔中宣告項目 (Item) 的方式就是建立一個具有項目 (Item) 類型名稱的項目 (Element)，做為 ItemGroup 項目 (Element) 的子系。 例如，下列程式碼會建立名為 Compile 的項目 (Item) 類型，其中包含兩個檔案。

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

使用語法 @(<ItemType>)，就可以在整個專案檔中參考項目類型。 例如，範例中的項目類型應該是藉由使用 @(Compile) 參考的。

在 MSBuild 中，項目 (Element) 和屬性 (Attribute) 名稱區分大小寫。 不過，屬性 (Property)、項目 (Item) 和中繼資料名稱則不區分大小寫。 下列範例會建立項目類型 Compile、comPile 或任何其他大小寫變化，並且為項目類型提供 "one.cs;two.cs" 值。

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

在進階的建置案例中，可以使用萬用字元宣告項目，而項目中可包含額外中繼資料。 如需項目的詳細資訊，請參閱項目。

工作

工作是 MSBuild 專案用來執行建置作業之可執行程式碼的單元。 例如，工作可能是編譯輸入檔，或是執行外部工具。 工作可以重複使用，而且可以由不同專案中的不同開發人員共用。

工作的執行邏輯是以受控程式碼撰寫，並使用 UsingTask 項目對應到 MSBuild。 若想撰寫自己的工作，您可以撰寫一個實作 ITask 介面的 Managed 類型。 如需有關如何撰寫工作的詳細資訊，請參閱工作撰寫。

MSBuild 包含您可以依據自己需求修改的一般工作。 範例包括用於複製檔案的 Copy、用於建立目錄的 MakeDir，以及用於編譯 Visual C# 原始程式碼檔的 Csc。 如需可用工作的清單和用法資訊，請參閱工作參考。

在 MSBuild 專案檔中執行工作的方式就是建立一個具有工作名稱的項目，作為 Target 元素的子系。 工作通常會接受參數，而這些參數會當做項目的屬性傳遞。 MSBuild 屬性和項目都可當做參數使用。 例如，下列程式碼會呼叫 MakeDir 工作，並將前面範例中宣告的 BuildDir 屬性值傳遞給此工作。

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

如需工作的詳細資訊，請參閱工作。

目標

目標 (Target) 會將工作以特殊順序組成群組，並公開 (Expose) 專案檔的區段做為建置處理序的進入點 (Entry Point)。 目標通常會分組為許多邏輯區段，以提高可讀性和進行擴充。 將建置步驟分成多個目標之後，您就可以從其他目標呼叫一段建置流程，而不需要在每個目標內複製那一段程式碼。 例如，如果建置流程的許多個進入點都必須建置參考，您可以建立一個建置參考的目標，再於每個需要建置參考的進入點執行此目標。

在專案檔中，目標是使用 Target 項目宣告的。 例如，下列程式碼會建立名為 Compile 的目標，接著呼叫 Csc 工作，而此工作具有在前面範例中宣告的項目清單。

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

在進階案例中，目標可用於描述彼此之間的關係並執行相依性分析，如果目標是最新版，即可略過建置流程的整個區段。 如需目標的詳細資訊，請參閱目標。

組建記錄檔

您可以將建置錯誤、警告和訊息記錄至主控台或另一個輸出裝置。 如需記錄的詳細資訊，請參閱使用 MSBuild 取得組建記錄檔。

在 Visual Studio 中使用 MSBuild

Visual Studio 使用 MSBuild 專案檔案格式來儲存有關受控專案的建置資訊。 使用 Visual Studio 介面新增或變更的專案設定，會反映在針對每個專案產生的 .proj 檔案中。 Visual Studio 會使用 MSBuild 的裝載執行個體來建置受控專案。 這表示受控專案可以在 Visual Studio 中或是於命令提示字元 (即使未安裝 Visual Studio) 建置，其結果完全相同。

如需如何在 Visual Studio 中使用 MSBuild 的教學課程，請參閱逐步解說：使用 MSBuild。

多目標

透過使用 Visual Studio，您可以編譯應用程式以在 .NET Framework 或 .NET Core (包括 .NET 5 和更新版本) 的數個版本中的任一版上執行。 例如，您可以編譯應用程式以在 32 位元平台的 .NET Framework 4 上執行，也可以編譯同一個應用程式以在 64 位元平台的 .NET Framework 4.8 上執行。 編譯為一個以上 Framework 版本的能力稱為「多目標」(Multitargeting)。

以下為多目標的一些優點：

  • 您可以開發以較舊版 .NET Framework (例如 3.5 和 4.7.2 版) 為目標的應用程式。

  • 您可以將「Framework 設定檔」當做目標，這是預先定義的目標 Framework 子集。

  • 如果 .NET Framework 目前版本的 Service Pack 已發行，您可以將它當做目標。

  • 多目標可保證應用程式只使用目標 Framework 和平台中提供的功能。

如需詳細資訊，請參閱多目標。

自訂建置

MSBuild 提供各種自訂建置案例的支援。 大部分的內建功能都可以覆寫或擴充。 請參閱自訂您的組建。

以程式設計方式存取 MSBuild

如果您正在開發建置工具，您可能想要以程式設計方式從 .NET 應用程式叫用 MSBuild。 藉由使用 MSBuild API，您可以控制複雜建置系統的所有層面。 MSBuild 提供具有完整 API 的 NuGet 套件 (Microsoft.Build 命名空間)，您可以針對這些用途從 .NET 應用程式使用這些套件。 請參閱使用 MSBuild API。

MSBuild 是開啟原始碼

MSBuild 是一個開放原始碼專案，可接受使用者參與，就像 .NET 生態系統的其餘部分一樣。 GitHub 中提供包含 MSBuild 來源的存放庫：MSBuild GitHub 存放庫。

另請參閱

標題 描述
逐步解說：從頭開始建立 MSBuild 專案檔案 顯示如何僅使用文字編輯器來累加建立基本專案檔。
逐步解說：使用 MSBuild 介紹 MSBuild 的建置區塊，以及顯示如何在不關閉 Visual Studio IDE 的情況下，撰寫和管理 MSBuild 專案及進行偵錯。
MSBuild 概念 呈現 MSBuild 的四個建置組塊：屬性、項目、目標和工作。
項目 描述 MSBuild 檔案格式的一般概念，以及項目如何彼此搭配。
MSBuild 屬性 介紹屬性和屬性集合。 屬性是成對的索引鍵/值組，可以用來設定組建 (Build)。
目標 解釋如何以特定順序將各項工作集合在一起成為群組，並能夠在命令列上呼叫建置流程的區段。
工作 顯示如何建立 MSBuild 可用來執行原子建置作業的可執行程式碼單元。
條件 討論如何在 MSBuild 項目中使用 Condition 屬性。
批次處理 討論 MSBuild 如何依中繼資料分類項目清單，以在工作和目標中執行。
多目標 示範如何以多個 .NET 版本和/或多個平台為目標。
取得組建記錄檔 描述如何記錄建置事件、訊息和錯誤。
MSBuild 如何建置專案 描述 MSBuild 中使用的內部建置程式
建立程式碼產生的自訂工作 示範如何使用程式碼範例建立自訂工作。
使用 MSBuild 產生 REST API 用戶端 示範如何使用程式碼範例擴充組建來處理 REST API 用戶端產生。
其他資源 列出社群和支援資源，以提供 MSBuild 的詳細資訊。

參考