TFS Build扩展

扩展 TeamBuild 翻译 Team Build Extensibility doc 前沿 这几天忙着把公司的项目一个一个签入到 VSTS 中 结果在平台这个项目时遇 到大问题 这个工程组居然有 38 个项目 里面还有 NHibernate 这种集成性不佳的东东 原先是自己写的本机编译的批处理 Build bat 具体如何写在萧寒的博客里有 结果在 TeamBuild 的时候一塌糊涂 怎么办 只好我自己花一上午把 Team Build Extensibility doc 翻译出来 大家动手自己搞 其余的项目也是一大堆的项目集成 不过主要问题是出在外 部引用上 而且引用路径都有要求 现在先把翻译的给大家共享 以后再写写我们自己的 案例 法律声明就没必要翻译了 时间仓促 有异议的同志请尽快指正 1Team 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 目标执行命令 BeforeEndToEndIteration BuildNumberOverrideTarget InitializeEndToEndIteration BeforeClean CoreClean AfterClean Clean InitializeBuild BeforeGet InitializeWorkspace CoreGet AfterGet PreBuild BeforeCompile CoreCompile AfterCompile Compile GetChangeSetsAndUpdateWorkItems PostBuild BeforeTest CoreTest AfterTest Test PackageBinaries TeamBuild BeforeDropBuild CoreDropBuild CopyLogFiles AfterDropBuild DropBuild AfterEndToEndIteration 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 1C 任务代码示例 以下的代码计算生成目录下的 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 2TfsBuild proj 文件举例 以下是 TfsBuild proj 的例子 这个文件是用团队生成向导产生的 你必须添加如果有 异常就跳出任务的处理 这些处理的代码行在本例的末尾用粗体特别标注了 Other Windows Source Control Explorer 2 Ensure that your current workspace has a mapping for the TeamProjectName TeamBuildTypes folder and that you have done a Get Latest Version on that folder 3 Browse through the folders to TeamProjectName TeamBuildTypes BuildTypeName folder 4 From the list of files available in this folder right click on TfsBuild Proj Select Check Out For Edit Make the required changes to the file and save Checkin the file 1 Right click on the TfsBuild Proj file selected in Step 3 above and select Checkin Pending Changes 2 Use the pending checkin dialog to save your changes to the source control Once the file is checked in with the modifications all future builds using this build type will use the modified settings MyBuildMachine MyTeamProject d build MyDropServer drops true Priority 1 Severity 1 Default true