MSBuildMSBuild

11/04/2016

本文内容

Microsoft 生成引擎是一个用于生成应用程序的平台。The Microsoft Build Engine is a platform for building applications. 此引擎(也称为 MSBuild)为项目文件提供了一个 XML 架构，用于控制生成平台处理和生成软件的方式。This engine, which is also known as MSBuild, provides an XML schema for a project file that controls how the build platform processes and builds software. Visual Studio 会使用 MSBuild，但 MSBuild 不依赖于 Visual Studio。Visual Studio uses MSBuild, but MSBuild doesn't depend on Visual Studio. 通过在项目或解决方案文件中调用 msbuild.exe，可以在未安装 Visual Studio 的环境中安排和生成产品。By invoking msbuild.exe on your project or solution file, you can orchestrate and build products in environments where Visual Studio isn't installed.

Visual Studio 使用 MSBuild 来加载和生成托管项目。Visual Studio uses MSBuild to load and build managed projects. Visual Studio 中的项目文件(.csproj、.vbproj、vcxproj 等)包含 MSBuild XML 代码，当你使用 IDE 来生成项目时，此代码就会运行。The project files in Visual Studio ( .csproj , .vbproj , .vcxproj , and others) contain MSBuild XML code that executes when you build a project by using the IDE. Visual Studio 项目会导入所有必要的设置和生成过程来执行典型的开发工作，但你可以从 Visual Studio 内或通过使用 XML 编辑器对其进行扩展或修改。Visual Studio projects import all the necessary settings and build processes to do typical development work, but you can extend or modify them from within Visual Studio or by using an XML editor.

有关适用于 C++ 的 MSBuild 的信息，请参阅 MSBuild (C++)。For information about MSBuild for C++, see MSBuild (C++).

下面的示例介绍了什么情况下可从命令行调用 MSBuild 而不是 Visual Studio IDE 来运行生成。The following examples illustrate when you might run builds by invoking MSBuild from the command line instead of the Visual Studio IDE.

你想要使用 64 位版本的 MSBuild。You want to use the 64-bit version of MSBuild. 通常情况下不必使用此版本的 MSBuild，但它可以让 MSBuild 访问更多内存。This version of MSBuild is usually unnecessary, but it allows MSBuild to access more memory.

你想要在多个进程中运行同一生成。You want to run a build in multiple processes. 不过，对于 C++ 和 C# 中的项目，你可以使用 IDE 实现相同的结果。However, you can use the IDE to achieve the same result on projects in C++ and C#.

你想要修改生成系统。You want to modify the build system. 例如，你可能想要实现以下操作：For example, you might want to enable the following actions:

在文件到达编译器之前先进行预处理。Preprocess files before they reach the compiler.

将生成输出复制到其他位置。Copy the build outputs to a different place.

从生成输出创建压缩文件。Create compressed files from build outputs.

执行后处理步骤。Do a post-processing step. 例如，你可能希望使用其他版本来标记程序集。For example, you might want to stamp an assembly with a different version.

你可以在 Visual Studio IDE 中编写代码，但使用 MSBuild 来运行生成。You can write code in the Visual Studio IDE but run builds by using MSBuild. 或者，你也可以在开发计算机的 IDE 中生成代码，但从命令行运行 MSBuild 来生成从多个开发人员集成的代码。As another alternative, you can build code in the IDE on a development computer but run MSBuild from the command line to build code that's integrated from multiple developers. 还可以使用 .NET Core 命令行接口 (CLI)(使用 MSBuild)来生成 .NET Core 项目。You can also use the .NET Core command-line interface (CLI), which uses MSBuild, to build .NET Core projects.

备注

你可以使用 Azure Pipelines 自动编译、测试和部署应用程序。You can use Azure Pipelines to automatically compile, test, and deploy your application. 你的生成系统会在开发人员签入代码(例如，作为持续集成策略的一部分)时或按照计划(例如，夜间版本验证测试生成)自动运行生成。Your build system can automatically run builds when developers check in code (for example, as part of a Continuous Integration strategy) or according to a schedule (for example, a nightly Build Verification Test build). Azure Pipelines 使用 MSBuild 来编译代码。Azure Pipelines compiles your code by using MSBuild. For more information, see Azure Pipelines.

本文提供 MSBuild 的概述。This article provides an overview of MSBuild. For an introductory tutorial, see Walkthrough: Using MSBuild.

在命令提示符处使用 MSBuildUse MSBuild at a command prompt

若要在命令提示符处运行 MSBuild，请将项目文件随相应的命令行选项一起传递到 MSBuild.exe。To run MSBuild at a command prompt, pass a project file to MSBuild.exe , together with the appropriate command-line options. 命令行选项允许你设置属性、执行特定的目标，以及设置可控制生成过程的其他选项。Command-line options let you set properties, execute specific targets, and set other options that control the build process. 例如，使用以下命令行语法生成文件 MyProj.proj，并将 Configuration 属性设置为 Debug。For example, you would use the following command-line syntax to build the file MyProj.proj with the Configuration property set to Debug.

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

有关 MSBuild 命令行选项的详细信息，请参阅命令行参考。For more information about MSBuild command-line options, see Command-line reference.

重要

在下载项目之前，请确定代码的可信度。Before you download a project, determine the trustworthiness of the code.

项目文件Project file

MSBuild 使用简单且可扩展的基于 XML 的项目文件格式。MSBuild uses an XML-based project file format that's straightforward and extensible. 使用 MSBuild 项目文件格式，开发人员可以描述要生成的项，以及如何针对不同的操作系统和配置生成这些项。The MSBuild project file format lets developers describe the items that are to be built, and also how they are to be built for different operating systems and configurations. 另外，这种项目文件格式还允许开发人员创作可重用的生成规则，这些规则可以包含到不同的文件中，以便可以在产品内的不同项目之间一致地执行生成。In addition, the project file format lets developers author reusable build rules that can be factored into separate files so that builds can be performed consistently across different projects in the product.

以下各节介绍了 MSBuild 项目文件格式的一些基本元素。The following sections describe some of the basic elements of the MSBuild project file format. For a tutorial about how to create a basic project file, see Walkthrough: Creating an MSBuild project file from scratch.

属性Properties

属性表示可用于配置生成的键/值对。Properties represent key/value pairs that can be used to configure builds. 属性的声明方式是：创建一个与属性同名的元素，将其指定为 PropertyGroup 元素的子元素。Properties are declared by creating an element that has the name of the property as a child of a PropertyGroup element. 例如，下面的代码将创建一个名为 BuildDir 的属性，其值为 Build。For example, the following code creates a property named BuildDir that has a value of Build.

Build

通过在元素中放置一个 Condition 属性，你可以有条件地定义一个属性。You can define a property conditionally by placing a Condition attribute in the element. 除非条件的计算结果为 true，否则会忽略条件元素的内容。The contents of conditional elements are ignored unless the condition evaluates to true. 在下面的示例中，将定义 Configuration 元素(如果尚未定义)。In the following example, the Configuration element is defined if it hasn't yet been defined.

Debug

在整个项目文件中，可以使用语法 $() 来引用各个属性。Properties can be referenced throughout the project file by using the syntax $(). 例如，可以使用 $(BuildDir) 和 $(Configuration) 来引用前面示例中的属性。For example, you can reference the properties in the previous examples by using $(BuildDir) and $(Configuration).

有关属性的详细信息，请参阅 MSBuild 属性。For more information about properties, see MSBuild properties.

项Items

项是生成系统的输入，通常表示文件。Items are inputs into the build system and typically represent files. 将根据用户定义的项名称，将项编组到各种项类型中。Items are grouped into item types based on user-defined item names. 这些项类型可以用作任务的参数，任务使用各个项来执行生成过程的步骤。These item types can be used as parameters for tasks, which use the individual items to perform the steps of the build process.

项目文件中项的声明方法是：通过创建一个与项类型同名的元素，并将其指定为 ItemGroup 元素的子元素。Items are declared in the project file by creating an element that has the name of the item type as a child of an ItemGroup element. 例如，下面的代码将创建一个名为 Compile 的项类型，其中包括两个文件。For example, the following code creates an item type named Compile, which includes two files.

在整个项目文件中，可以使用语法 @() 来引用项目类型。Item types can be referenced throughout the project file by using the syntax @(). 例如，可以使用 @(Compile) 引用示例中的项类型。For example, the item type in the example would be referenced by using @(Compile).

在 MSBuild 中，元素和特性名称区分大小写。In MSBuild, element and attribute names are case-sensitive. 但是，属性、项和元数据名称不区分大小写。However, property, item, and metadata names are not. 下面的示例创建了项类型 Compile、comPile 或任何其他大小写变体，并为其指定了值“one.cs;two.cs”。The following example creates the item type Compile, comPile, or any other case variation, and gives the item type the value "one.cs;two.cs".

可以使用通配符声明项，并且对于更高级的生成方案，项可以包含其他元数据。Items can be declared by using wildcard characters and may contain additional metadata for more advanced build scenarios. 有关项的详细信息，请参阅项。For more information about items, see Items.

任务Tasks

任务是 MSBuild 项目用于执行生成操作的可执行代码单元。Tasks are units of executable code that MSBuild projects use to perform build operations. 例如，任务可能编译输入文件或运行外部工具。For example, a task might compile input files or run an external tool. 任务可以重用，并且可由不同项目中的不同开发人员共享。Tasks can be reused, and they can be shared by different developers in different projects.

任务的执行逻辑在托管代码中编写，并使用 UsingTask 元素映射到 MSBuild。The execution logic of a task is written in managed code and mapped to MSBuild by using the UsingTask element. 你可以通过创作一个实现 ITask 接口的托管类型来编写自己的任务。You can write your own task by authoring a managed type that implements the ITask interface. 有关如何编写任务的详细信息，请参阅任务写入。For more information about how to write tasks, see Task writing.

MSBuild 包含一些可按需进行修改的常见任务。MSBuild includes common tasks that you can modify to suit your requirements. 例如，用于复制文件的复制、用于创建目录的 MakeDir 以及用于编译 Visual C# 源代码文件的 Csc。Examples are Copy, which copies files, MakeDir, which creates directories, and Csc, which compiles Visual C# source code files. 有关可用任务的列表以及用法信息，请参阅任务参考。For a list of available tasks together with usage information, see Task reference.

通过创建一个与任务同名的元素，并将其指定为 Target 元素的子元素，可以在 MSBuild 项目文件中执行此任务。A task is executed in an MSBuild project file by creating an element that has the name of the task as a child of a Target element. 任务通常接受参数，参数将作为元素的特性进行传递。Tasks typically accept parameters, which are passed as attributes of the element. MSBuild 的属性和项都可用作参数。Both MSBuild properties and items can be used as parameters. 例如，以下代码将调用 MakeDir 任务，并将前面示例中声明的 BuildDir 属性的值传递到该任务。For example, the following code calls the MakeDir task and passes it the value of the BuildDir property that was declared in the earlier example.

有关任务的详细信息，请参阅任务。For more information about tasks, see Tasks.

目标Targets

目标按特定的顺序将任务组合到一起，并将项目文件的各个部分公开为生成过程的入口点。Targets group tasks together in a particular order and expose sections of the project file as entry points into the build process. 目标通常分组到各个逻辑部分中，以便提高可读性并实现扩展。Targets are often grouped into logical sections to increase readability and to allow for expansion. 通过将生成步骤拆分为目标，你可以从其他目标中调用生成过程的一个部分，而不必将那部分代码复制到每个目标中。Breaking the build steps into targets lets you call one piece of the build process from other targets without copying that section of code into every target. 例如，如果生成过程的多个入口点需要生成引用，你可以创建一个生成引用的目标，然后从所要求的每个入口点运行此目标。For example, if several entry points into the build process require references to be built, you can create a target that builds references and then run that target from every entry point where it's required.

目标是使用 Target 元素在项目文件中声明的。Targets are declared in the project file by using the Target element. 例如，以下代码将创建一个名为 Compile 的目标，该目标随后将调用具有前面示例中声明的项列表的 Csc 任务。For example, the following code creates a target named Compile, which then calls the Csc task that has the item list that was declared in the earlier example.

在更高级的方案中，目标可用于描述彼此之间的关系并执行依赖性分析，这样，如果目标是最新的，则可以跳过生成过程的整个部分。In more advanced scenarios, targets can be used to describe relationships among one another and perform dependency analysis so that whole sections of the build process can be skipped if that target is up-to-date. 有关目标的更多信息，请参阅目标。For more information about targets, see Targets.

生成日志Build logs

你可以将生成错误、警告和消息记录到控制台或其他输出设备。You can log build errors, warnings, and messages to the console or another output device.

在 Visual Studio 中使用 MSBuildUse MSBuild in Visual Studio

Visual Studio 使用 MSBuild 项目文件格式存储有关托管项目的生成信息。Visual Studio uses the MSBuild project file format to store build information about managed projects. 通过使用 Visual Studio 接口添加或更改的项目设置将反映在为每个项目生成的 .*proj 文件中。Project settings that are added or changed by using the Visual Studio interface are reflected in the .*proj file that's generated for every project. Visual Studio 使用 MSBuild 的一个托管实例来生成托管项目。Visual Studio uses a hosted instance of MSBuild to build managed projects. 这意味着可以在 Visual Studio 中或在命令提示符处生成托管项目(即使未安装 Visual Studio)，并且结果将完全相同。This means that a managed project can be built in Visual Studio or at a command prompt (even if Visual Studio isn't installed), and the results will be identical.

有关如何在 Visual Studio 中使用 MSBuild 的教程，请参阅演练：使用 MSBuild。For a tutorial about how to use MSBuild in Visual Studio, see Walkthrough: Using MSBuild.

多定向Multitargeting

通过 Visual Studio，你可以将应用程序编译为在若干 .NET Framework 版本的任意一个上运行。By using Visual Studio, you can compile an application to run on any one of several versions of .NET Framework. 例如，可以将同一个应用程序编译为既能在 32 位平台的 .NET Framework 2.0 上运行，也能在 64 位平台的 .NET Framework 4.5 上运行。For example, you can compile an application to run on .NET Framework 2.0 on a 32-bit platform, and you can compile the same application to run on .NET Framework 4.5 on a 64-bit platform. 这种使用多个框架作为编译目标的能力称为“多目标功能”。The ability to compile to more than one framework is named multitargeting.

以下是多目标功能的一些优点：These are some of the benefits of multitargeting:

可以开发以多个 .NET Framework 早期版本(例如，版本 2.0、3.0 和 3.5)为目标的应用程序。You can develop applications that target earlier versions of .NET Framework, for example, versions 2.0, 3.0, and 3.5.

你可以将 .NET Framework 之外的框架作为目标，例如 Silverlight。You can target frameworks other than .NET Framework, for example, Silverlight.

可以一个 框架配置文件 为目标，该文件是目标框架的预定义子集。You can target a framework profile , which is a predefined subset of a target framework.

如果已发布 .NET Framework 当前版本的服务包，则可以将其作为目标。If a service pack for the current version of .NET Framework is released, you could target it.

多目标功能可以保证应用程序仅使用目标框架和平台中的可用功能。Multitargeting guarantees that an application uses only the functionality that's available in the target framework and platform.

有关详细信息，请参阅多定向。For more information, see Multitargeting.

请参阅See also

TitleTitle

描述Description

演示如何只使用文本编辑器以增量方式创建基本项目文件。Shows how to create a basic project file incrementally, by using only a text editor.

介绍 MSBuild 的构建基块，并演示如何在不关闭 Visual Studio IDE 的情况下编写、操作和调试 MSBuild 项目。Introduces the building blocks of MSBuild and shows how to write, manipulate, and debug MSBuild projects without closing the Visual Studio IDE.

演示 MSBuild 的四个生成块：属性、项、目标和任务。Presents the four building blocks of MSBuild: properties, items, targets, and tasks.

介绍 MSBuild 文件格式背后的常规概念，以及所有这些概念之间的关系。Describes the general concepts behind the MSBuild file format and how the pieces fit together.

介绍属性和属性集合。Introduces properties and property collections. 属性是可用于配置生成的键/值对。Properties are key/value pairs that can be used to configure builds.

介绍如何按特定的顺序将任务组合到一起，并允许从命令行调用生成过程的各个部分。Explains how to group tasks together in a particular order and enable sections of the build process to be called on the command line.

演示如何创建 MSBuild 可用于执行原子生成操作的可执行代码单元。Shows how to create a unit of executable code that can be used by MSBuild to perform atomic build operations.

论述如何在 MSBuild 元素中使用 Condition 特性。Discusses how to use the Condition attribute in an MSBuild element.

演示批处理、执行转换、多目标和其他高级技术。Presents batching, performing transforms, multitargeting, and other advanced techniques.

介绍如何记录生成事件、消息和错误。Describes how to log build events, messages, and errors.

描述 MSBuild 中使用的内部生成过程Describes the internal build process used within MSBuild

列出社区和支持资源，用于了解有关 MSBuild 的更多信息。Lists community and support resources for more information about MSBuild.

参考Reference

链接到包含参考信息的主题。Links to topics that contain reference information.

定义常见 MSBuild 术语。Defines common MSBuild terms.