[译]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命名空间。
- 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
