Пошаговое руководство. Расширение возможностей Team Foundation Build с помощью настраиваемых задач
Обновлен: Ноябрь 2007
Функциональные возможности Team Foundation Build можно расширить путем создания собственных настраиваемых задач, которые будут выполняться во время построения. В этом разделе описываются действия, которые следует предпринять для расширения определения построения с помощью настраиваемой задачи.
Требуемые разрешения
Для выполнения данного пошагового руководства, необходимо, чтобы разрешение Управление построением имело значение Разрешить. Дополнительные сведения см. в разделе Разрешения Team Foundation Server.
Создание определения построения
Для создания нового определения построения воспользуйтесь диалоговым окном Определение построения. Можно либо использовать совместный доступ к существующему файлу TFSBuild.proj, либо создать новый с помощью средства Мастер создания файла проекта MSBuild. Настройка связанных с файлом TFSBuild.proj определений построения выполняется путем редактирования этого файла. Сведения о создании определений построения см. в разделе Создание определения построения.
Создание настраиваемых задач
В задачах предоставляется код, выполняющийся во время процесса построения. Эти задачи содержатся в элементах Target файлов проектов MSBuild. MSBuild является ядром Team Foundation Build. Настраиваемые задачи должны иметь формат, поддерживаемый MSBuild. Каждая задача должна быть реализована в виде класса платформы .NET, реализующего интерфейс ITask, который определен в построении Microsoft.Build.Framework.dll.
Существуют два подхода к реализации задачи.
Реализация непосредственно интерфейса ITask.
Создание класса, производного от вспомогательного класса Task, который определен в построении Microsoft.Build.Utilities.dll. Класс Task реализует интерфейс ITask и предоставляет реализации по умолчанию некоторых элементов интерфейса ITask.
В обоих случаях необходимо добавить в свой класс метод с названием Execute, то есть метод, который вызывается при выполнении задачи. Этот метод не принимает никаких параметров и возвращает значение Boolean: true, если задача успешно выполнена, или false, если задачу выполнить не удалось. В следующем примере показана задача, не выполняющая никакого действия и возвращающая значение true.
using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;
namespace MyTasks
{
public class SimpleTask : Task
{
public override bool Execute()
{
return true;
}
}
}
Задачи могут также принимать параметры, вызывать события и вести журнал выходных данных. Дополнительные сведения см. в разделах Задачи MSBuild и Общие сведения о MSBuild.
Извлечение файла TFSBuild.proj
После того, как задача написана, следует зарегистрировать ее и поместить ее вызов в одном из целевых объектов, чтобы код задачи выполнялся в требуемом месте процесса построения. При использовании средства Мастер создания проекта MSBuild для создания файла проекта MSBuild, и использовании расположения по умолчанию в системе управления версиями, ваш файл TFSBuild.proj находится в папке $/МойКомандныйПроект/TeamBuildTypes/МоеИмяСборки в каталоге системы управления версиями Visual Studio Team System. В этом сценарии МойКомандныйПроект является именем вашего проекта и корневым узлом всех источников командного проекта, а МоеИмяПостроения является именем, заданным для определения построения, для которого был первоначально создан файл TFSBuild.proj.
Для определения местоположения файла TFSBuild.proj в системе управления версиями выберите определение построения в папке Сборки в области Сред. Командный обозреватель, щелкните его правой кнопкой мыши и выберите команду Изменить. Расположение файла TFSBuild.proj в системе управления версиями отображается в области Файл проекта диалогового окна Определение построения.
.gif "Примечание") Примечание. |
|---|
Не редактируйте файл Microsoft.TeamFoundation.Build.targets, поскольку изменения будут применены ко всем построениям на данном компьютере. |
Дополнительные сведения об извлечении файлов см. в разделе Работа с системой управления версиями Team Foundation.
Регистрация задач
После создания задачи необходимо зарегистрировать ее указанием этой задачи в элементе UsingTask файла TFSBuild.proj. Элемент UsingTask сопоставляет задачу с построением, содержащим реализацию задачи. Дополнительные сведения см. в разделе Элемент UsingTask (MSBuild).
Регистрация настраиваемой задачи
Откройте файл TFSBuild.proj.
Добавьте к файлу элемент UsingTask и укажите подробные сведения о вашей задаче.
Пример.
<UsingTask TaskName="MyTasks.SimpleTask" AssemblyName="MyAssembly.Build.Tasks"/>-или-
<UsingTask TaskName="MyTasks.SimpleTask" AssemblyFile="MyAssembly.Build.Tasks.dll"/>-или-
<UsingTask TaskName="MyTasks.SimpleTask" AssemblyFile="c:\somediskpath\MyAssembly.Build.Tasks.dll"/>Сохраните файл.
Выполнение настраиваемой задачи
После создания и регистрации задачи следует указать место в процессе построения, где задача должна выполняться.
Выполнение задачи
Определите, где в процессе построения требуется выполнять настраиваемую задачу.
Дополнительные сведения о расширении процесса построения см. в разделе Описание файлов конфигурации Team Foundation Build.
Откройте файл TFSBuild.proj и добавьте элемент Target, выбранный ранее.
Чтобы задача выполнялась, добавьте элемент задачи внутрь элемента Target.
Например, следующий код XML в файле TFSBuild.proj указывает выполнять задачу SimpleTask в целевом объекте BeforeGet, выполняющемся немедленно перед целевым объектом Get.
<Target Name="BeforeGet"> <SimpleTask /> </Target>Сохраните файл.
Возврат файлов
Чтобы изменения вступили в силу, необходимо вернуть в систему управления версиями файл TFSBuild.proj. Система Team Foundation Build копирует этот файл из системы управления версиями на компьютер построения, поэтому изменения, внесенные в локальную копию файла на вашем компьютере не повлияют на процесс построения. Дополнительные сведения о возврате файлов в систему управления версиями см. в разделе Практическое руководство. Возврат ожидающих изменений.
Если требуется, чтобы система Team Foundation Build скопировала DLL-файл задачи на компьютер построения, необходимо добавить DLL задачи в систему управления версиями в узле командного проекта.
Пример задачи
В этом примере создается настраиваемая задача, расширяющая определение или определения сборок, связанные с файлом TFSBuild.proj. Задача записывает в журнал размеры файлов, сгенерированных в процессе построения. Этот пример состоит из двух частей:
Код задачи.
Файл TFSBuild.proj.
Записанные этой задачей в журнал данные можно просмотреть в файле журнала построения, Buildlog.txt, находящегося в папке сброса файлов построения. Журнал построения содержит данные подобного вида:
The total size is 9216 bytes in d:\BuildDir\MyTeamProj\MyBuildType\sources\..\Binaries\Release dir (Общий размер 9216 байт в каталоге d:\BuildDir\MyTeamProj\MyBuildType\sources\..\Binaries\Release)
Код задачи C#
Приведенный ниже пример содержит код, вычисляющий общий размер двоичных файлов путем сложения размера файлов, находящихся в папке двоичных файлов.
| Примечание. |
|---|
Все двоичные файлы, сгенерированные во время построения, находятся в папке Binaries в папке каталога построения агента построения. |
Чтобы включить в построение эту задачу, скомпилированный DLL-файл следует вернуть в систему управления версиями, в папку командного проекта. Это гарантирует, что файл будет скопирован к агенту построения во время построения.
Следующий код вычисляет размер двоичных файлов в папке Binaries каталога построения. Свойство корневого каталога решения передается задачей с помощью сценария Team Foundation Build.
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)
{
// Process the list of files found in the directory.
string[] fileEntries = Directory.GetFiles(targetDirectory, "*.*");
if (fileEntries.Length > 0)
{
dwSize = 0;
szCurrDir = targetDirectory;
foreach (string fileName in fileEntries)
ProcessFile(fileName);
////////////////////////////////////////////////////////////////////////
// This log message would just print out a line in the build log file.
// You need to add code to do what you need to do with this data. e.g.
// publishing it into the warehouse for reporting.
///////////////////////////////////////////////////////////////////////
Log.LogMessage("The total size of is {0} bytes in {1} dir",
dwSize, targetDirectory);
}
// Recurse into subdirectories of this directory.
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;
}
}
Файл TFSBuild.proj
Когда задача скомпилирована и возвращена в систему управления версиями, необходимо, чтобы она вызывалась из файла TFSBuild.proj. В этом примере задачу необходимо вызвать после того, как файлы скомпилированы, а все двоичные файлы скопированы в каталог Binaries. Следовательно, задачу необходимо выполнять в целевом объекте BeforeDropBuild. Дополнительные сведения о расширяемых целевых объектах в TFSBuild.proj см. в разделе Описание файлов конфигурации Team Foundation Build.
Пример ниже содержит код из измененного файла TFSBuild.proj. Этот пример XML-файла почти полностью сгенерирован средством Мастер создания файла проекта MSBuild, за исключением элементов UsingTask и Target, которые находятся в конце файла.
<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="DesktopBuild" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<!-- TO EDIT BUILD TYPE DEFINITION
TODO: Update all of the comments in this file!
To edit the build type, you will need to edit this file which was generated
by the Create New Build Type wizard. This file is under source control and
needs to be checked out before making any changes.
The file is available at:
$/{TeamProjectName}/TeamBuildTypes/{BuildTypeName}
where you will need to replace TeamProjectName and BuildTypeName with your
Team Project and Build Type name that you created
Checkout the file
1. Open Source Control Explorer by selecting View -> 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
-->
<!-- Do not edit this -->
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TeamBuild\Microsoft.TeamFoundation.Build.targets" />
<ProjectExtensions>
<!-- Team Foundation Build Version - DO NOT CHANGE -->
<ProjectFileVersion>2</ProjectFileVersion>
<!-- DESCRIPTION
TODO: Obsolete.
-->
<Description>this one automatically builds on check in</Description>
<!-- BUILD MACHINE
TODO: Obsolete.
-->
<BuildMachine>ahetod-test2</BuildMachine>
</ProjectExtensions>
<PropertyGroup>
<!-- Properties set by the build type creation wizard -->
<!-- TEAM PROJECT
TODO: Obsolete.
-->
<TeamProject>TeamProjectName</TeamProject>
<!-- BUILD DIRECTORY
TODO: Obsolete.
-->
<BuildDirectoryPath>C:\Documents and Settings\user\Local Settings\Temp\1\TeamProjectName\BuildDefinitionName</BuildDirectoryPath>
<!-- DROP LOCATION
TODO: Obsolete.
-->
<DropLocation>\\UNKNOWN\drops</DropLocation>
<!-- TESTING
Set this flag to enable/disable running tests as a post build step.
-->
<RunTest>false</RunTest>
<!-- CODE ANALYSIS
To change CodeAnalysis behavior edit this value. Valid values for this
can be Default,Always or Never.
Default - To perform code analysis as per the individual project settings
Always - To always perform code analysis irrespective of project settings
Never - To never perform code analysis irrespective of project settings
-->
<RunCodeAnalysis>Never</RunCodeAnalysis>
<!-- Additional Properties -->
<!-- WorkItemType
The type of the work item created on a build break - if empty, "Bug" will be used
-->
<WorkItemType Condition=" '$(WorkItemType)'=='' "></WorkItemType>
<!-- WorkItemFieldValues
Add/edit key value pairs to set values for fields in the work item created
during the build process. Please make sure the field names are valid
for the work item type being used.
-->
<WorkItemFieldValues>Symptom=build break;Steps To Reproduce=Start the build using Team Build</WorkItemFieldValues>
<!-- WorkItemTitle
Title for the work item created on build failure
-->
<WorkItemTitle>Build failure in build:</WorkItemTitle>
<!-- DescriptionText
Description for the work item created on a build failure
-->
<DescriptionText>This work item was created by Team Build on a build failure.</DescriptionText>
<!-- BuildLogText
Additional text for the work item create on a build failure.
-->
<BuildlogText>The build log file is at:</BuildlogText>
<!-- ErrorWarningLogText
Additional text for the work item create on a build failure
-->
<ErrorWarningLogText>The errors/warnings log file is at:</ErrorWarningLogText>
<!-- UpdateAssociatedWorkItems
Set this flag to enable/disable updating associated workitems on a successful build
-->
<UpdateAssociatedWorkItems>true</UpdateAssociatedWorkItems>
<!-- AdditionalVCOverrides
Additional text for the VCOverrides file generated for VC++ projects
-->
<AdditionalVCOverrides></AdditionalVCOverrides>
<!-- CustomPropertiesForClean
Custom properties to pass to the MSBuild task while calling the "Clean" target for all solutions.
The format should be: PropertyName1=value1;PropertyName2=value2;...
-->
<CustomPropertiesForClean></CustomPropertiesForClean>
<!-- CustomPropertiesForBuild
Custom properties to pass to the MSBuild task while calling the default targets for all solutions.
The format should be: PropertyName1=value1;PropertyName2=value2;... To pass custom properties to
individual solutions, use the Properties metadata item of the SolutionToBuild ItemGroup.
-->
<CustomPropertiesForBuild></CustomPropertiesForBuild>
</PropertyGroup>
<ItemGroup>
<!-- SOLUTIONS
The paths of the solutions to build. To add/delete solutions, edit this
ItemGroup. For example, to add a solution MySolution.sln, add the following line:
<SolutionToBuild Include="$(BuildProjectFolderPath)\path\MySolution.sln" />
To change the order in which the solutions are built, modify the order in
which the solutions appear below.
To call a target (or targets) other than the default, add a metadata item named
Targets. To pass custom properties to the solution, add a metadata item named
Properties. For example, to call the targets MyCustomTarget1 and MyCustomTarget2,
passing in properties Property1 and Property2, add the following:
<SolutionToBuild Include="$(BuildProjectFolderPath)\path\MySolution.sln">
<Targets>MyCustomTarget1;MyCustomTarget2</Targets>
<Properties>Property1=Value1;PropertyTwo=Value2</Properties>
</SolutionToBuild>
-->
<SolutionToBuild Include="$(BuildProjectFolderPath)/../../SimpleAppToBuild/SimpleAppToBuild.sln">
<Targets></Targets>
<Properties></Properties>
</SolutionToBuild>
</ItemGroup>
<ItemGroup>
<!-- CONFIGURATIONS
The list of configurations to build. To add/delete configurations, edit
this value. For example, to add a new configuration, add the following lines:
<ConfigurationToBuild Include="Debug|x86">
<FlavorToBuild>Debug</FlavorToBuild>
<PlatformToBuild>x86</PlatformToBuild>
</ConfigurationToBuild>
The Include attribute value should be unique for each ConfigurationToBuild node.
-->
<ConfigurationToBuild Include="Release|Any CPU">
<FlavorToBuild>Release</FlavorToBuild>
<PlatformToBuild>Any CPU</PlatformToBuild>
</ConfigurationToBuild>
</ItemGroup>
<ItemGroup>
<!-- TEST ARGUMENTS
If the RunTest property is set to true then the following test arguments will be used to run
tests. Tests can be run by specifying one or more test lists and/or one or more test containers.
To run tests using test lists, add MetaDataFile items and associated TestLists here:
<MetaDataFile Include="$(SolutionRoot)\HelloWorld\HelloWorld.vsmdi">
<TestList>BVT1;BVT2</TestList>
</MetaDataFile>
To run tests using test containers, add TestContainer items here:
<TestContainer Include="$(OutDir)\HelloWorldTests.dll" />
<TestContainer Include="$(SolutionRoot)\TestProject\WebTest1.webtest" />
<TestContainer Include="$(SolutionRoot)\TestProject\LoadTest1.loadtest" />
-->
</ItemGroup>
<ItemGroup>
<!-- ADDITIONAL REFERENCE PATH
The list of additional reference paths to use while resolving references.
For example:
<AdditionalReferencePath Include="C:\MyFolder\" />
<AdditionalReferencePath Include="C:\MyFolder2\" />
-->
</ItemGroup>
<UsingTask TaskName="BuildTask.BinSize" AssemblyFile="$(SolutionRoot)\tools\BuildTask.dll" /> <Target Name="BeforeDropBuild"> <BinSize SourceDir="$(SolutionRoot)" /> </Target>
</Project>
См. также
Задачи
Практическое руководство. Написание задачи