TFS Build扩展.docx

扩展TeamBuild--翻译《Team Build Extensibility.doc》

前沿：这几天忙着把公司的项目一个一个签入到VSTS中，结果在平台这个项目时遇到大问题，这个工程组居然有38个项目，里面还有NHibernate这种集成性不佳的东东。原先是自己写的本机编译的批处理Build.bat，（具体如何写在萧寒的博客里有），结果在TeamBuild的时候一塌糊涂。怎么办，只好我自己花一上午把Team Build Extensibility.doc翻译出来，大家动手自己搞。其余的项目也是一大堆的项目集成。不过主要问题是出在外部引用上，而且引用路径都有要求。现在先把翻译的给大家共享，以后再写写我们自己的案例。法律声明就没必要翻译了。时间仓促，有异议的同志请尽快指正。

1 Team Foundation Build扩展生成过程
1.1 法律声明
  This document supports a preliminary release of a software product that may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either expressed or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results from the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the expressly written permission of Microsoft Corporation.
  Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.  © 2005 Microsoft Corporation. All rights reserved.  Microsoft and Visual Studio 2005 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. 
All other trademarks are property of their respective owners.
1.2 目录
本文是通过描述在Team Foundation Build过程中写配置任务和这些配置任务的插件的来介绍进行Team Foundation Build过程可扩展的信息的预发布版本。使用的是Microsoft® Visual Studio 2005® Team System Beta3生成。
1.3 Table of Contents  

2 简介
Team Foundation Build是一个可扩展的生成自动化系统，能够进行公共生成并且与Team System的其它工具集成。Team Foundation Build提供了一个简单的基于向导的方法来创建生成类型。使用这个向导，你可以指派使用哪台机器来生成，生成哪个解决方案，运行测试，等等。通过向导创建的生成类型的最终结果是一组MSBuild生成脚本。Team Foundation Build使用MSBuild引擎来实际执行生成过程。
注意 要了解Team Foundation Build, the Team Build 向导和MSBuild更多的信息请看Microsoft® Visual Studio 2005® Team Foundation Server产品文档。
Team Foundation Build被设计成可扩展的。Team Build向导被设计用来创建描绘通用情况下的生成脚本。但是有某些生成情节需要我们对向导生成的脚本进行配置。Team Foundation Build自带了一些通用的任务来支持类似运行测试，从源代码控制中获取源代码等等这样的活动。例如，生成管理员可能希望在编译完成之后，测试开始之前将他编译好的程序集部署到指定的位置。公司可能会要求按特殊的编号方式生成系统，因此最重要的是在Team Foundation Build中的默然的编号方式的模式。一个开发者可能希望在生成过程完成之后对他输出的程序集进行标记。本页介绍了你如何才能达到在生成过程中你期望的点插入你配置的任务的配置水平。
2.1 理解Team Foundation 生成配置文件
Team Foundation 生成是基于MSBuild引擎。完整的Team Foundation生成过程是通过一套MSBuild格式的XML文件控制的。这些XML文件里的元素控制具体的生成过程。 
1) 目标元素
目标元素定义了项目如何生成。目标元素包含了一系列的MSBuild顺序运行的任务。一个目标可以依赖另一个目标，并且在这个目标中的任务要在要依赖的那个目标里的任务完成之后才能执行。例如，一个项目包含一个编译目标和一个部署目标，部署目标必须依赖于编译目标，因为项目必须在被编译之后才能部署。你可以定义一些目标，然后按照不同的需求用不同的方式处理，把它们串起来。而不需要对不同的情况，写单独的MSBuild文件。
2) 任务元素
任务元素指定了在生成过程中的代码。必须包含你希望运行的任务的名字。注意：这里名称叫“Task”但并不是XML节点。一个任务节点是由目标节点内的位置标识的。MSBuild自身带了一些通用的任务，都可以用于配置生成过程。
3) 使用任务元素
使用任务元素指定了任务包含的程序集。MSBuild脚本文件可以导入其它的脚本文件。例如，你可以在一个脚本文件中定义一些通用的配置信息，然后在其它文件的配置中包含这个文件。
 以下两个文件控制了Team Foundation Build的过程：
1) Microsoft.TeamFoundation.Build.targets
这个文件定义了默认任务和目标的集合，这个文件是Team Foundation Build自带的，它定义了如：Clean、DropBuild、Compile等。目标包含了为特定目标调用的任务。在这个文件中的一些目标要依赖别的目标，这样为执行特定的要求而形成目标链。例如，编译目标依赖编译前目标，编译前目标中的所有任务必须在编译前执行。注意：不是所有的在这里定义的目标都必须在一个特定的生成中被调用，例如桌面生成不需要调用Clean目标。
Microsoft.TeamFoundation.Build.targets是Visual Studio Team System自带的，而且在“$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v8.0\TeamBuild\”中。这仅仅是系统中的这个文件的一个拷贝。配置者最好不修改这个文件。当这个文件共享用于一台计算机上的所有生成运行，对这个文件的所有编辑会影响这台机器上的所有的生成。
2) TfsBuild.proj   
这个文件是Team Foundation Build的主配置文件，这是一个包含所有生成类型的文件。在团队生成向导中提供的配置参数存储在这个文件中。它包含了生成机器、生成目录、生成的解决方案等等。这个文件在用户定义新的生成类型的时候由团队生成向导创建。这个文件导入了上面描述的.targets 文件。Team Foundation Build 传递这个文件给 MSBuild。任何这个文件的变更都会影响这个生成类型的生成。这个文件保存在源代码控制中的\MyProject\TeamBuildTypes\MyConfig目录下。这里MyProject 是团队项目的名称， MyConfig 是生成类型的名称。
2.2 Team Foundation Build目标执行命令
l BeforeEndToEndIteration*
l BuildNumberOverrideTarget*
l InitializeEndToEndIteration
l BeforeClean*
l CoreClean
l AfterClean*
l Clean
l InitializeBuild
l BeforeGet*
l InitializeWorkspace
l CoreGet
l AfterGet*
l PreBuild
l BeforeCompile*
l CoreCompile
l AfterCompile*
l Compile
l GetChangeSetsAndUpdateWorkItems
l PostBuild
l BeforeTest*
l CoreTest
l AfterTest*
l Test
l PackageBinaries*
l TeamBuild
l BeforeDropBuild*
l CoreDropBuild
l CopyLogFiles
l AfterDropBuild*
l DropBuild
l AfterEndToEndIteration*
l EndToEndIteration
标记“*”的目标可以做可扩展的定义。你必须根据你的需要插入你的任务。这里不建议你修改其它没带“*”的目标，因为Team Foundation Build会在这些目标中调用自己预定好的任务。
2.3 Foundation Build的可扩展性
要通过插入你自己配制的任务来扩展Team Foundation Build的话，你必须：
1) 使用团队生成向导来创建一个生成类型来获得一个基本的生成类型
2) 创建你配制的任务
3) 签出TfsBuild.proj文件编辑它
4) 通过在TfsBuild.proj文件中指派UsingTask元素来注册你的任务
5) 通过以下步骤调用你的任务：
a) 决定在生成过程中你希望在哪里调用你的任务
b) 从上面列表中选择目标元素的名称，表示在生成过程中在哪个点进行调用
c) 生成目标元素的名称
d) 指派目标元素中你调用的任务
6) 签入TfsBuild.proj文件并且配置任务dll使其产生效果
由于配置好的内容将应用到这台机器上的所有的生成，所以不能编辑Microsoft.TeamFoundation.Build.targets。以下节将介绍具体的步骤
2.3.1 创建一个生成类型
使用团队生成向导创建新的生成类型。创建了一个TfsBuild.proj文件，并且签入。你可以按照自己的要求添加自己的配置信息来编辑这个文件。
2.3.2 创建一个配置任务
任务提供了生成过程中运行的代码，并且在MSBuild脚本中的目标元素里指派任务。MSBuild是Team Foundation Build的引擎，配置任务必须是MSBuild能理解的格式。每个任务必须执行一个继承ITask接口的.Net类。ITask接口在Microsoft.Build.Framework.程序集中定义。你可以按照下面两个方式执行你的任务：
1) 你的类直接从ITask而来，并且执行这个接口的方法。
2) 你的类从帮助类而来，Task定义在Microsoft.Build.Utilities.dll 程序集中。选择这个选项使它很容易从你的任务中运行日志事件。 
这两个方法中，你必须添加Execute方法到你的类里。当这个任务运行的时候，就调用这个方法。这个方法没有参数，返回一个bool值：如果任务成功就返回True，失败就返回False。以下例子显示的是一个包含必须要素的最简单的任务，其中没有任何活动执行，直接返回一个True值。 
using System;
using Microsoft.Build.Utilities;
namespace MyTasks
{
public class SimpleTask : Task
{
public override bool Execute()
{
return true;
}
}
}
  你可以在你的任务中设置属性。这些属性就要求增加事件到你的任务。请参阅Visual Studio产品文档中MSBuild如何创建配置任务部分来了解细节。
2.3.3 签出 TfsBuild.proj 文件
写完你的任务后，你必须注册它，并且在一个目标中调用它，使你的任务代码能在生成过程中希望的位置被执行。你会发现TfsBuild.proj 文件存放在Visual Studio Team Foundation源代码控制中的$/MyTeamProject/TeamBuildTypes/MyBuildName文件夹中。MyTeamProject是你的团队项目名字，是所有团队项目源文件的根节点。所有的生成类型存放在团队项目根节点下的TeamBuildTypes节点。MyBuildName是在你使用生成向导创建生成类型的时候取的生成类型的名字。如果你浏览TeamBuildTypes，你会看到你的生成类型的名字命名的文件夹，一个你先前定义的生成类型的文件夹。
如果你需要对签入文件有了解的话，参阅Visual Studio Team Foundation源代码控制文档，你必须：
1) 创建一个工作区，确保你映射了团队项目到本机文件夹。
2) 打开源代码控制浏览器，定位到你的生成类型中的TfsBuild.proj文件。
3) 右击TfsBuild.proj文件，选择获取最新版本。
4) 再次选择TfsBuild.proj文件，选择“签出以编辑”选项。
2.3.4 注册你的任务
创建了你的任务后，你必须通过在TfsBuild.proj文件中的UsingTask元素中指派你的任务来注册你的任务。这是因为MSBuild必须知道如何定位包含了任务类的程序集。如下：
1) 打开TfsBuild.proj文件
2) 创建一个UsingTask元素，并且指派详细的任务。下面的例子演示了如何创建这个元素：

-或-

-或-

3) 保存文件
  TaskName属性是一定要的，并且建议你设定它为类的全名称，这样避免在运行时含糊不清。AssemblyName属性提供了包含这个类的程序集的名字。这个程序集的名字也可以是强命名。例如：SimpleTask, Version=1.0.2,Culture=neutral。强命名是为了在全局程序集缓存中定位任务自身的程序集。当使用AssemblyName的时候，MSBuild会通过标准的程序集调用规则寻找任务程序集。如果程序集调用规则不能应用在你的任务上，就要使用AssemblyFile属性。程序集文件提供了包含这个程序集的磁盘定位库。这个程序集文件属性可以用全路径或相对路径来设置。
2.3.5 调用你的任务
现在你已经注册了你的任务，你必须在生成过程中所期待的某一点调用你指派的任务。为调用你的任务：
1) 决定在生成过程中你希望调用配置好的任务的点。仔细思考这样一个话题“我希望在标准Team Foundation Build步骤之前/后调用我的任务，在Team Foundation Build‘Get’步骤之前，还是在‘Compile’之前”。像先前的描述一样，任务指派在目标中，而且这些执行目标中的顺序在Microsoft.TeamFoundation.Build.targets文件中设定。任何给出的生成类型都支持两种生成类型：桌面生成和从Team Foundation Build用户接口初始化生成。不是所有的目标都是在桌面生成中被调用的。例如，清除目标不能在桌面生成中被调用。为了在团队生成中初始化一个生成，目标需要按照下面指定的步骤执行
2) 如果你希望在生成过程的‘Get’步骤调用你的配置任务。从上面所列，我们注意到GeforeGet是你必须考虑的任务。因此你要添加任务到BeforeGet目标
3) 打开TfsBuild.proj文件并且添加 你在上面选好的Target 元素。然后添加一个Task节点以调用你的任务到这个你刚添加的Taget中。例如，下面的TfsBuild.proj 中的片断设定了在‘Get’步骤之前，运行你的任务的TeamBuild（团队生成）：

4) 保存文件
2.3.6 签入TfsBuild.proj 和任务 .dll 文件
你必须签入修改后的TfsBuild.proj文件，确保其产生效果。Team Foundation Build在生成机器上通过源代码控制来同步这个文件，所以你本机的拷贝如果没有签入的话，将不能影响生成的设定。签入文件请参看Visual Studio Team Foundation源代码控制文件。
如果你需要Team Foundation Build同步任务dll到运行生成的机器上。你需要在团队项目节点下添加任务dll到源代码控制中。
2.4 举例任务
本节举例说明如何帮助我们进行Team Foundation生成的配置任务。假设一个用户把他的团队项目“MyTeamProj”通过生成过程获得一个二进制产品之后希望看到这个产品有多大。用户希望在生成后的日志文件中看到这个产品大小的数据。
他已经创建了一个叫“MyBuildType”的Team Foundation生成类型和添加预期的功能来完成这个工作的过程。通过Team Foundation Build，所有产生的二进制文件都会放到生成运行的那台机器的生成目录下的“Binaries’”文件夹中。
这个用户所写的任务是：把binaries文件夹下的所有文件的大小叠加后计算出总的二进制文件的大小。他叫这个任务为BuildTask.dll任务。他把BuildTask.dll签入到团队项目节下的“Tools”目录中的源代码控制中，因此这个任务.dll通过Team Foundation Build与那台生成机器同步。他要求只能在编译完成之后调用触发这个任务并且确定他指派的任务是到BeforeDropBuild目标中。每次他修改了TfsBuild.proj文件，就可以从这个文件中获得指示。
以下显示任务代码和TfsBuild.proj文件。注意：UsingTask元素和BeforeDropBuild目标元素在TfsBuild.proj文件中。在这个举例任务中，你在生成日志文件中看到文件的大小，Buildlog.log，显示在生成删除文件夹。如果你在你的生成过程中集成这个例子，并且打开Buildlog.log文件。你可以看到输出行如下：
“The total size is 9216 bytes in d:\BuildDir\MyTeamProj\MyBuildType\sources\..\Binaries\Release dir” 
2.4.1 C# 任务代码示例
 以下的代码计算生成目录下的Binaries文件夹中的二进制文件的大小。本解决方案节点属性通过Team Foundation生成脚本传递到这个任务中。
 using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Build.Framework;// 记着添加引用到本程序集
using Microsoft.Build.Utilities; // 记着添加引用到本程序集
using System.Diagnostics;
using System.IO;

namespace BuildTask
{
public class BinSize : Task
{
private string sourceDir;
[Required]
public string SourceDir
{
get { return sourceDir; }
set { sourceDir = value; }
}
public override bool Execute()
{
string szDir = sourceDir + "\\..\\Binaries";
ProcessDirectory(szDir);
return true;
}
private void ProcessDirectory(string targetDirectory)
{
// 获取指定目录下的文件列表的过程
string[] fileEntries = Directory.GetFiles(targetDirectory, "*.*");
if (fileEntries.Length > 0)
{
dwSize = 0;
szCurrDir = targetDirectory;
foreach (string fileName in fileEntries)
ProcessFile(fileName);
////////////////////////////////////////////////////////////////////////
//本日志信息将输出到生成log文件
//你需要添加代码来处理这些数据
//发布它到报表仓库中
///////////////////////////////////////////////////////////////////////
Log.LogMessage("The total size of is {0} bytes in {1} dir",
dwSize, targetDirectory);
}
//递归本目录下的子目录
string[] subdirectoryEntries = Directory.GetDirectories(targetDirectory);
foreach (string subdirectory in subdirectoryEntries)
ProcessDirectory(subdirectory);
}
private void ProcessFile(string path)
{
FileInfo fi = new FileInfo(path);
dwSize = dwSize + fi.Length;
}
private long dwSize;
private string szCurrDir;
}
}

2.4.2 TfsBuild.proj 文件举例
以下是TfsBuild.proj的例子。这个文件是用团队生成向导产生的，你必须添加如果有异常就跳出任务的处理。这些处理的代码行在本例的末尾用粗体特别标注了。 

"DesktopBuild" xmlns="

MyBuildMachine

MyTeamProject

d:\build

on>\\MyDropServer\drops

true

Priority=1;Severity=1