MSBuild

项目
2025-02-07

Microsoft生成引擎是用于生成应用程序的平台。此引擎（也称为 MSBuild）为项目文件提供 XML 架构，用于控制生成平台处理和生成软件的方式。 Visual Studio 使用 MSBuild，但 MSBuild 不依赖于 Visual Studio。通过在项目或解决方案文件中调用 msbuild.exe 或 dotnet 生成，可以在未安装 Visual Studio 的环境中协调和生成产品。

Visual Studio 使用 MSBuild 加载和生成托管项目。 Visual Studio（.csproj、.vbproj、.vcxproj和其他）中的项目文件包含在 IDE 中生成项目时执行的 MSBuild XML 代码。 Visual Studio 项目导入所有必要的设置和生成过程来执行典型的开发工作，但可以从 Visual Studio 中或使用文本编辑器扩展或修改它们。

若要在没有 Visual Studio 的 Windows 系统上安装 MSBuild，请转到下载页上的 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。

有关 MSBuild for C++的信息，请参阅 MSBuild （C++）。

以下示例演示了如何通过从命令行而不是 Visual Studio IDE 调用 MSBuild 来运行生成。

未安装 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 生成工具，那么只能通过 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 样式项目。引用 SDK（如 .NET 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>

项目可以通过使用通配符声明，并且可能包括额外的元数据，以用于更高级的构建场景。有关条目的更多信息，请参阅条目。

任务

任务是 MSBuild 项目用于执行生成操作的可执行代码单元。例如，任务可能会编译输入文件或运行外部工具。可以重复使用任务，并且可以由不同项目中的不同开发人员共享这些任务。

任务的执行逻辑以托管代码编写，并使用 UsingTask 元素映射到 MSBuild。您可以通过编写一个实现 ITask 接口的托管类型来创建自己的任务。有关如何编写任务的详细信息，请参阅任务撰写。

MSBuild 包括可修改以满足要求的常见任务。示例包括复制，它复制文件、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 项目文件格式存储有关托管项目的生成信息。使用 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 上运行。这种使用多个框架作为编译目标的能力称为“多目标”。

以下是多目标分析的一些优势：

可以开发面向早期版本的 .NET Framework 的应用程序，例如版本 3.5 和 4.7.2。
可以将一个框架配置文件作为目标，该文件是目标框架的预定义子集。
如果发布当前版本 .NET Framework 的服务包，则可以以其为目标。
多重目标设定确保应用程序只使用目标框架和平台提供的功能。

有关详细信息，请参阅多重目标定位。

自定义生成

MSBuild 为各种自定义生成方案提供支持。大多数内置功能都可以重写或扩展。请参阅自定义生成。

以编程方式访问 MSBuild

如果要开发生成工具，可能需要从 .NET 应用程序以编程方式调用 MSBuild。通过使用 MSBuild API，可以控制复杂生成系统的各个方面。 MSBuild 提供了一个 NuGet 包，其中包含一个完整的 API（Microsoft.Build 命名空间），可以从 .NET 应用程序使用这些 API。请参阅使用 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 使用最佳实践	介绍使用 MSBuild 配置和运行生成的最佳做法
创建自定义任务以生成代码	演示如何使用代码示例创建自定义任务。
使用 MSBuild 生成 REST API 客户端	展示如何通过一个代码示例来扩展构建，以生成和处理 REST API 客户端。
其他资源	列出社区和支持资源，用于了解有关 MSBuild 的更多信息。

参考

MSBuild 参考
指向包含参考信息的主题的链接。
术语表
定义常见的 MSBuild 术语。

通过