MSBuild
Microsoft建置引擎是建置應用程式的平臺。 這個引擎也稱為 MSBuild,提供項目檔的 XML 架構,可控制建置平台處理和建置軟體的方式。 Visual Studio 使用 MSBuild,但 MSBuild 並不相依於 Visual Studio。 藉由在專案或方案檔上叫用 msbuild.exe 或 dotnet 組建,您可以在未安裝 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 中,元素和屬性名稱會區分大小寫。 不過,屬性、專案和元數據名稱不是。 下列範例會建立項目類型 Compile
、comPile
或其他大小寫變體,並將項目類型設為值 "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 的詳細資訊。 |
參考
MSBuild 參考
包含參考資訊的主題連結。詞彙
定義常見的 MSBuild 詞彙。