[译]Walkthrough: Using MSBuild

原文

MSBuild是微软VS的Build平台。

你可以在Visual Studio或Windows命令行中运行MSBuild。在这我们使用VS创建一个MSBuild项目。你可以在VS中编辑项目文件，使用命令行来Build这个项目检查结果。

创建MSBuild项目

VS项目系统基于MSBuild。因此通过VS可以非常简单的创建一个项目文件。本节，你将创建一个C#的项目文件。

创建项目文件

打开VS
点击File菜单，指向New，然后点击Project
在弹出的New Project对话框中选择C#项目类型，然后点击Windows Forms Application项目模板。在Name box中输入BuildApp。然后选择解决方案的路径，例如D:\，默认选中Create directory for solution, 在Solution Name中输入BuildApp。
点击OK创建项目于文件

检查项目文件

在Solution Explorer中，点击BuilApp项目节点
在Properties浏览器中，可以看到Project File属性值为BuildApp.csproj。所有的项目于文件名的后缀都是proj。如果你创建的是VB项目，那么项目文件名为BuildApp.vbproj
右键项目节点，点击Unload Project
再次右键项目节点，点击Edit BuildApp.csproj。项目文件出现在代码编辑器中。

Targets & Tasks

项目文件是xml格式的，根节点为Project。

<?xml version="1.0" encoding="utf-8"?>

<Project ToolsVersion="12.0" DefaultTargets="Build"  xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

必须要置顶Project元素的xmlns命名空间。

build项目的工作是依靠Target和Task完成的。

task是最小的工作单元，是原子性的。task是独立的可执行组件，它可以有自己的输入和输出。Tasks更多详细信息见Tasks
target是要执行的task的名字集合。项目文件的最下面有两个target：BeforeBuild和AfterBuild。

<Target Name="BeforeBuild">

</Target>

<Target Name="AfterBuild">

</Target>

Targets更多详细信息见Targets

Project元素有个可选的DefaultTargets属性，用于选择默认的target去build，在这个例子中是Build。

<Project ToolsVersion="12.0" DefaultTargets="Build" ...

Buildtarget没有定义在项目文件中。它是通过Import元素从Microsoft.CSharp.targets文件中导入的。

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

添加一个Target和Task

在项目文件中的Import节点后添加：

<Target Name="HelloWorld">

</Target>

上面的代码创建了一个名为HelloWorld的target。

2. 在HelloWorld target中添加：

<Target Name="HelloWorld">

  <Message Text="Hello"></Message>  <Message Text="World"></Message>

</Target>

保存项目文件

Message task是MSBuild自带的众多task之一。更多请见Task Reference。

Message task有一个名为Text的属性用于输入要输出的文本。HelloWorldtarget执行了两次task：首先显示"Hello"，然后显示"World"。

Build Target

在Visual Stuido Command Prompt中运行MSBuild build上面定义的HelloWorld target。使用/target或/t来选择target。

build target

点击开始菜单, 点击所有程序，找到Visual Studio Tools文件夹，点击其中的Visual Studio Command Prompt
在命令窗口中CD到项目文件所在的文件夹，本例中是 D:\BuildApp\BuildApp
运行msbuild 使用参数/t:HelloWorld指定buildHelloWorld target：

msbuild buildapp.csproj /t:HelloWorld

检查输出，你应该可以看到两行"Hello"和"World"

Hello

World

Build Properties

Build Properties是用来指导build的键值对。在项目文件的最上面已经定义了一个build properties：

<PropertyGroup>

...

  <ProductVersion>10.0.11107</ProductVersion>

  <SchemaVersion>2.0</SchemaVersion>

  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>

  <OutputType>WinExe</OutputType>

...

</PropertyGroup>

所有的property都是PropertyGroup元素的子元素。属性名是子元素名，属性值是子元素的text元素。例如：

<TargetFrameworkVersion>v12.0</TargetFrameworkVersion>

上面定义了一个名为TargetFrameworkVersion的属性，其值为v12.0。

build properties可以随时重定义：

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

检查property的值

使用下面的方法获取属性值:

$(PropertyName)

检查属性值

在代码编辑器中，用下面的代码替换掉HelloWorld target:

<Target Name="HelloWorld">

  <Message Text="Configuration is $(Configuration)" />

  <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />

</Target>

保存项目文件
打开命令行窗口，运行下面的命令行:

msbuild buildapp.csproj /t:HelloWorld

你将看到下面的输出

Configuration is Debug

MSBuildToolsPath is C:\Program Files\MSBuild\12.0\bin

Conditional Properties（条件属性）

许多属性（如Configuration）是根据条件而定义的，例如：

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

意思是如果Configuration property没有定义的话就定义一个值为Debug名为Configuration的属性。

几乎所有的MSBuild元素都有Condition attribute。更多请见Conditions。

Reserved Properties

TODO

Enviroment Variables

TODO

在命令行中设置Properties

可以在命令行通过使用/property或/p来设置properties。

在命令行窗口中，输入并运行下面的命令：

msbuild buildapp.csproj /t:HelloWorld /p:Configuration=Release

检查输出。你应该可以看到:

Configuration is Release.

特殊字符

TODO

Build Items

一个item就是一个信息片段，典型的是一个文件名，被用来当作一个build系统的输入。例如，一组源文件的名字传入到Compile task中用于编译成为一个程序集。

所有的item都是ItemGroup元素的子元素。 item的名字就是子元素的名字，值为Include attribute。如果多个item的名字是一样的那么其值为一个集合用;分隔。例如：

<ItemGroup>

    <Compile Include="Program.cs" />

    <Compile Include="Properties\AssemblyInfo.cs" />

</ItemGroup>

上面的itemgroup有两个item。其值为:"Program.cs"和"Properties\AssemblyInfo.cs"。

下面的代码可以使用一个子元素达到上面的效果，关键在于Include中的;：

<ItemGroup>

    <Compile Include="Program.cs;Properties\AssemblyInfo.cs" />

</ItemGroup>

更多相关信息，请见Items:

检查Item Type值

通过下面的代码获取item type的值：

@(ItemType)

在代码编辑器中庸下面的代码替代HelloWorld target

<Target Name="HelloWorld">

  <Message Text="Compile item type contains @(Compile)" />

</Target>

保存项目文件
在命令行窗口中运行下面的命令:

msbuild buildapp.csproj /t:HelloWorld

检查输出，应该能看到下面的内容:

Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs

item type的值默认是用;分隔的。

可以通过下面的语法指定分隔符:

@(ItemType, Separator)

分行显示item type的值

在代码编辑器中，用下面的代码替换Message task：

<Message Text="Compile item type contains @(Compile, '%0A%0D')" />

保存项目文件
在命令行窗口中运行下面的命令:

msbuild buildapp.csproj /t:HelloWorld

输出如下

Compile item type contains Form1.cs

Form1.Designer.cs

Program.cs

Properties\AssemblyInfo.cs

Properties\Resources.Designer.cs

Properties\Settings.Designer.cs

Include, Exclude和通配符

可以在include attribute中使用通配符"*", "**", 和 "?" ，例如：

<Photos Include="images\*.jpeg" />

添加images文件夹下所有的.jpeg文件

<Photos Include="images\**.jpeg" />

添加images文件夹下及其子文件夹下所有的.jpeg文件

更多信息请见How to: Select the Files to Build

<Photos Include="images\*.jpeg" />

<Photos Include="images\*.gif" />

上面的代码创建了一个名为Photos的item type，包含了images文件夹下面的所有jped和gif文件。上面的代码等同于下面的代码：

<Photos Include="images\*.jpeg;images\*.gif" />

你可以使用Exclude attribute来排除文件:

<Compile Include="*.cs" Exclude="*Designer*">

添加所有的cs文件，除了名字含有"Designer"的文件。更多请见How to: Exclude Files from the Build。

Exclude attribute只作用于当前item。例如：

<Compile Include="*.cs" />

<Compile Include="*.res" Exclude="Form1.cs">

上面的代码中Exclude不起任何作用。

include & exclude items

在代码编辑器中，用下面的代码替换Message task：

<Message Text="Compile item type contains @(XFiles)" />

在Import元素后面添加item group:

<ItemGroup>

   <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />

</ItemGroup>

保存项目文件
在命令行窗口运行下面的命令:

msbuild buildapp.csproj /t:HelloWorld

检查输出，你将看到：

Compile item type contains Form1.cs;Program.cs;Properties/Resources.resx