共用方式為


MSBuild

Microsoft建置引擎是建置應用程式的平臺。 這個引擎也稱為 MSBuild,提供項目檔的 XML 架構,可控制建置平台處理和建置軟體的方式。 Visual Studio 使用 MSBuild,但 MSBuild 並不相依於 Visual Studio。 藉由在專案或方案檔上叫用 msbuild.exedotnet 組建,您可以在未安裝 Visual Studio 的環境中協調和建置產品。

Visual Studio 會使用 MSBuild 來載入和建置受控專案。 Visual Studio 中的項目檔 (.csproj.vbproj.vcxproj和其他專案)包含 MSBuild XML 程式代碼,會在您在 IDE 中建置專案時執行。 Visual Studio 專案會匯入所有必要的設定和建置程式,以執行一般開發工作,但您可以從 Visual Studio 內或使用文字編輯器來擴充或修改它們。

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

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

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

如需 MSBuild for 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,以及適當的命令行選項。 命令行選項可讓您設定屬性、執行特定目標,以及設定控制建置程式的其他選項。 例如,您會使用下列命令行語法來建置 MyProj.proj 檔案,並將 Configuration 屬性設定為 Debug

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 建置系統會將專案特定的邏輯儲存在項目檔本身,並使用已匯入的 MSBuild XML 檔案搭配擴展名,例如 .props.targets 來定義標準建置邏輯。 .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 屬性放在 元素中,有條件地定義屬性。 除非條件評估結果為 true,否則將忽略條件元素的內容。 在下列範例中,如果尚未定義 Configuration 屬性,則會加以定義。

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

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

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

項目

項目是建置系統的輸入,通常用來表示檔案。 項目會根據使用者定義的項目名稱分組為項目類型。 這些專案類型可用來做為工作的參數,這些參數會使用個別專案來執行建置程式的步驟。

在專案檔案中宣告項目,方法是建立一個以項目類型名稱為 ItemGroup 元素的子元素。 例如,下列程式代碼會建立名為 Compile的項目類型,其中包含兩個檔案。

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

在整個專案檔中,可以使用語法 @(<ItemType>) 引用項目類型。 例如,範例中的項目類型會使用 @(Compile)來參考。

在 MSBuild 中,元素和屬性名稱會區分大小寫。 不過,屬性、專案和元數據名稱不是。 下列範例會建立項目類型 CompilecomPile或其他大小寫變體,並將項目類型設為值 "one.cs;two.cs"。

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

專案可以使用通配符來宣告,而且可能包含更進階建置案例的其他元數據。 如需項目的詳細資訊,請參閱 Items

任務

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

工作執行邏輯是以受控程式碼撰寫,並使用 UsingTask 元素對應至 MSBuild。 您可以撰寫實作 ITask 介面的受控類型,從而創建自己的任務。 如需如何撰寫工作的詳細資訊,請參閱 工作撰寫

MSBuild 包含一般工作,您可以修改以符合您的需求。 範例包括 Copy,其會複製檔案、MakeDir,這會建立目錄,以及編譯 Visual C# 原始程式碼檔案 Csc。 如需可用工作的清單以及使用方式資訊,請參閱 工作參考

工作會在 MSBuild 專案檔中執行,方法是建立一個元素,其中包含有該工作的名稱,作為 Target 元素的子項。 工作通常會接受參數,這些參數會作為元素的屬性來傳遞。 MSBuild 屬性和項目都可以當做參數使用。 例如,下列程式代碼會呼叫 MakeDir 工作,並傳遞先前範例中宣告的 BuildDir 屬性值。

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

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

目標

以特定順序將工作分組在一起,並將專案檔的區段公開為建置程式的進入點。 目標通常會分成邏輯區段,以提高可讀性和允許擴充。 將建置步驟分成目標,可讓您從其他目標呼叫一個建置程式,而不需將該程式代碼區段複製到每個目標。 例如,如果建置程式的數個進入點需要建置參考,您可以建立可建置參考的目標,然後從所需的每個進入點執行該目標。

在專案檔案中使用 Target 元素來宣告目標。 例如,下列程式代碼會建立名為 Compile的目標,然後呼叫 Csc 工作,該工作具有先前範例中宣告的項目清單。

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

在更進階的案例中,目標可用來描述彼此之間的關聯性,並執行相依性分析,以便在該目標 up-to-date 時略過整個建置程式的區段。 如需目標的詳細資訊,請參閱 目標

組建記錄

您可以將建置錯誤、警告和訊息記錄到主控台或其他輸出裝置。 如需詳細資訊,請參閱 使用 MSBuild 取得組建記錄

在 Visual Studio 中使用 MSBuild

Visual Studio 會使用 MSBuild 專案檔格式來儲存 Managed 專案的建置資訊。 使用 Visual Studio 介面新增或變更的項目設定會反映在針對每個項目產生的 .*proj 檔案中。 Visual Studio 會使用 MSBuild 的託管實例來建置受控專案。 這表示 Managed 專案可以建置在 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 上執行。 將編譯至多個架構的能力稱為多重目標架構。

以下是多目標化的一些優點:

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

  • 您可以將目標設為 架構配置檔,這是目標架構的預先定義子集。

  • 如果發行目前版本的 .NET Framework 的服務包,您可以選擇將其作為目標。

  • 多重目標保證應用程式只會使用目標架構和平臺中可用的功能。

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

自訂建置

MSBuild 提供各種自定義建置案例的支援。 大多數的內建功能都可以被覆寫或擴充。 請參閱 自訂組建

以程序設計方式存取 MSBuild

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

MSBuild 是開放原始碼

MSBuild 是一個開放原始碼專案,可接受 msBuild GitHub 存放庫 的用戶參與。

另請參閱

標題 描述
逐步解說:從頭開始建立 MSBuild 專案檔 示範如何使用文本編輯器,以累加方式建立基本項目檔。
操作指南:使用 MSBuild 介紹 MSBuild 的建置組塊,並示範如何在不關閉 Visual Studio IDE 的情況下撰寫、操作和偵錯 MSBuild 專案。
MSBuild 概念 呈現 MSBuild 的四個建置組塊:屬性、專案、目標和工作。
項目 描述 MSBuild 檔格式背後的一般概念,以及片段如何配合在一起。
MSBuild 屬性 介紹屬性和屬性集合。 屬性是可用來設定組建的索引鍵/值組。
目標 說明如何依特定順序將工作分組在一起,並在命令行上呼叫建置程式的區段。
任務 示範如何建立一個可執行程式碼單位,由 MSBuild 用於執行原子建置作業。
條件 討論如何在 MSBuild 專案中使用 Condition 屬性。
批處理 討論 MSBuild 如何依元數據分類專案清單,以在工作和目標中執行。
多重目標 示範如何以多個 .NET 版本和/或多個平台為目標。
取得建置記錄 描述如何記錄建置事件、訊息和錯誤。
MSBuild 如何建置專案 描述 MSBuild 中使用的內部建置程式
為程式代碼產生建立自訂任務 示範如何使用程式代碼範例建立自定義工作。
使用 MSBuild 產生 REST API 用戶端 示範如何使用程式代碼範例擴充組建來處理 REST API 用戶端產生。
其他資源 列出社群和支持資源,以取得 MSBuild 的詳細資訊。

參考