Getting Started With Automated Build Studio 4

http://www.automatedqa.com/downloads/abs.asp

Copyright Notice Automated Build Studio, as described in this on-line help system, is licensed under the software license

agreement distributed with the product. The software may be used or copied only in accordance with the terms of its license.

Automated Build Studio is Copyright © 2002-2007 AutomatedQA Corporation. ALL RIGHTS RESERVED.

No part of this help can be reproduced, stored in any retrieval system, copied or modified, transmitted in any form or by any means electronic or mechanical, including photocopying and recording for purposes others than the purchaser’s personal use.

All AutomatedQA product names are trademarks or registered trademarks of AutomatedQA Corporation. All other trademarks, service marks and trade names mentioned in this Help system or elsewhere in the Automated Build Studio software package are the property of their respective owners.

Automated Build Studio includes the UnzDll.dll library that is supplied by Info-Zip. This library is copyright © 1990-2005 Info-ZIP. This software is provided “as is”, without warranty of any kind, expressed or implied. In no event shall Info-ZIP or its contributors be held liable for any direct, indirect, incidental, special or consequential damages arising from the use of or inability to use this software.

Table of Contents 3

Table of Contents INTRODUCTION......................................................................................................................................6

Overview..................................................................................................................................................6 System Requirements...............................................................................................................................9 Supported Tools .....................................................................................................................................10 What’s New in Automated Build Studio 4 ............................................................................................14 Getting Support ......................................................................................................................................19 Automated Build Studio Samples ..........................................................................................................19 Automated Build Studio and Windows Firewall ...................................................................................21

GETTING STARTED .............................................................................................................................24 Basic Concepts.......................................................................................................................................24 User Interface – Overview .....................................................................................................................29 Creating a Macro....................................................................................................................................35 Adding, Removing and Arranging Operations in a Macro ....................................................................38 Modifying Operation Properties ............................................................................................................41 Saving and Loading Macros ..................................................................................................................45 Using Macro Configurations..................................................................................................................45 Running Macros.....................................................................................................................................53 Logging Macro Runs .............................................................................................................................54 Analyzing Results of Macro Runs .........................................................................................................55 Getting Started – Further StepsSending Notifications ...........................................................................56

Exporting Results of Macro Runs ......................................................................................................57 Handling Errors in Macros................................................................................................................58 Incrementing the Build Version Number............................................................................................62 Scheduling Macro Runs .....................................................................................................................64

BUILD STRATEGIES ............................................................................................................................67 Continuous Integration...........................................................................................................................67

Continuous Integration Support.........................................................................................................67 Tracing Task Triggers........................................................................................................................71

Distributed Builds ..................................................................................................................................74 Distributed Builds – Overview...........................................................................................................74 Distributed Build Scenarios ...............................................................................................................75 Creating Distributed Builds ...............................................................................................................76

Concurrent Execution of Operations......................................................................................................82 USING VARIABLES AND CONSTANTS IN MACROS ...................................................................84

Variables and Constants – Overview .....................................................................................................84 Creating Variables and Constants and Modifying Their Attributes.......................................................86 Using Variables and Constants in Operation Properties ........................................................................88 Using Variables and Constants in Script Operations .............................................................................89 Initializing Variables via Command Line ..............................................................................................91

INTEGRATION WITH MICROSOFT VISUAL STUDIO AND MSBUILD ...................................92

Copyright © 2002-2007 AutomatedQA Corp. [email protected]

Table of Contents 4

Overview................................................................................................................................................92 Integration With Microsoft Visual Studio..............................................................................................92 Running Automated Build Studio Macros From MSBuild Projects......................................................94 Running Automated Build Studio Macros From Visual Studio Team Explorer ...................................95

AUTOMATED BUILD STUDIO CLIENT/SERVER AND WEB INTERFACE ...........................100 Overview..............................................................................................................................................100 Using the Client/Server Functionality..................................................................................................100 Automated Build Studio Client/Server – User Permissions ................................................................106 Connection Parameters ........................................................................................................................108 Automated Build Studio Client/Server Web Interface.........................................................................113 Automated Build Studio Gadget for Windows Sidebar .......................................................................114

CHARTS.................................................................................................................................................118 Charts – Overview ...............................................................................................................................118 Charts Panel .........................................................................................................................................118 Chart Types..........................................................................................................................................121 Viewing Charts Data Stored on Another Computer ............................................................................122 Moving Charts Data From One Computer to Another.........................................................................122

DEBUGGING MACROS......................................................................................................................124 Debugging Macros in Automated Build Studio...................................................................................124 Stepping Through the Macro ...............................................................................................................126 Running to the Cursor ..........................................................................................................................126 Using Breakpoints................................................................................................................................127 Conditional Breakpoints ......................................................................................................................127 Watches Panel ......................................................................................................................................128 Breakpoints Panel ................................................................................................................................129 Evaluating Expressions ........................................................................................................................131

SCRIPT WRITING ...............................................................................................................................132 Script Writing – Basics ........................................................................................................................132 Object Model .......................................................................................................................................133 Handling Exceptions in Scripts............................................................................................................134 Working With Operations in Scripts....................................................................................................136

AUTOMATED BUILD STUDIO COMMAND-LINE INTERFACE...............................................141 Command-Line Arguments..................................................................................................................141 Exit Codes............................................................................................................................................143

MISCELLANEOUS ..............................................................................................................................145 Working With Source Control Systems...............................................................................................145 Working With Automated Build Studio via COM ..............................................................................147 Sounds for Automated Build Studio Events ........................................................................................154

OPERATIONS REFERENCE..............................................................................................................156 Operation Categories............................................................................................................................156 .NET Tools Category ...........................................................................................................................158 Archivers Category ..............................................................................................................................159 Authenticode Category ........................................................................................................................160 AutomatedQA Tools Category ............................................................................................................160

www.automatedqa.com Automated Build Studio by AutomatedQA Corporation

Table of Contents 5

Borland Compilers Category ...............................................................................................................161 Build Tools Category ...........................................................................................................................162 Burn CD/DVD Category......................................................................................................................162 Communication Category ....................................................................................................................162 Concurrent Versions System Category ................................................................................................163 Execute Category .................................................................................................................................164 Files and Directories Category.............................................................................................................164 Frequently Used Category ...................................................................................................................165 FTP Category .......................................................................................................................................165 Help Compilers Category.....................................................................................................................166 HTTP Category....................................................................................................................................166 Installers Category ...............................................................................................................................167 Interactive Category.............................................................................................................................168 Internet Information Services (IIS) Category ......................................................................................168 Issue Tracking Category ......................................................................................................................169 JediVCS Category................................................................................................................................170 Logging Category ................................................................................................................................170 Microsoft Compilers Category.............................................................................................................171 Microsoft Compilers for Smart Device Category ................................................................................171 Microsoft Virtual Server Category ......................................................................................................172 Microsoft Visual SourceSafe Category................................................................................................173 Misc Category......................................................................................................................................173 Oracle Category ...................................................................................................................................174 Other Compilers Category ...................................................................................................................174 Patch Management Category ...............................................................................................................175 Perforce Category ................................................................................................................................175 Prepare Code Category ........................................................................................................................175 PsTools Category .................................................................................................................................176 PVCS Category ....................................................................................................................................177 Rational ClearCase Category ...............................................................................................................177 Read/Write Category............................................................................................................................178 Remote Macro Execution Category.....................................................................................................178 Source Code Tools Category ...............................................................................................................179 SourceGear Vault Category .................................................................................................................179 SourceOffSite Category .......................................................................................................................180 SQL Category ......................................................................................................................................181 Standard Category................................................................................................................................181 StarTeam Category ..............................................................................................................................182 Subversion Category ............................................................................................................................183 Surround SCM Category......................................................................................................................184 Team Coherence Category...................................................................................................................184 Team Foundation Version Control Category.......................................................................................185 Unit Tests Category .............................................................................................................................186 Wait Category ......................................................................................................................................186 WMI Category .....................................................................................................................................187

INDEX.....................................................................................................................................................189


Introduction 6

Introduction

Overview

Automated Build Studio by AutomatedQA Corp. Automated Build Studio is a powerful build and release management system that provides an easy

way to automate the build, test and release processes of software projects. Its intuitive interface and unprecedented flexibility allows even inexperienced users to create complex visual macros which can automate repetitive or day-to-day tasks with the single click of a button.

This topic is devoted to the main functions of Automated Build Studio. It provides you with a simple conceptual map of the product. To learn how to use these functions, see Getting Started. A good way to learn how to use the product is to explore samples that come with Build Studio. See Automated Build Studio Samples for more information on them.

Why Automated Builds? In the current state of software development, with projects becoming more and more complex, building,

testing and releasing of software projects consumes an ever-increasing amount of time and resources. Building the application manually quite often becomes tedious, prone to errors and inefficient both in terms of time and money. A typical build process includes a number of steps:

• Getting latest versions of source files from a version control system, • Specifying build options, • Recompiling libraries and packages that are used by the application, • Building the application, • Building the installation, • Notifying co-workers that a new build is available, • Starting the testing process, and so forth.

It is quite easy to make a mistake when performing these steps. For example, you may specify wrong build version number or compile the application using inappropriate options.

Automated Build Studio lets you optimize the build, test and release processes and allows you to focus on more important issues. Using Build Studio, you spend a certain amount of time on a task only once: on creating a macro for that task. A macro unifies elementary operations, for example, Copy File(s), Get Latest Version From VSS, Compile Visual C# 2005 Project, Send E-Mail, etc., that let you perform each step of the process you are automating. After the macro is ready, you can run it either manually, or at certain points in time. That is, you commission Build Studio with all the work and responsibility: it will automatically run the macro whenever you need.


Overview 7

Major Features Among the many features that make Automated Build Studio the ultimate build and release management

tool are: • Visually constructed macros. As we have said above, a macro includes operations each of

which is responsible for a separate step of the process you want to automate. Even if you are not familiar with programming, you will find creating macros very easy with the visual macro designer of Automated Build Studio.

• Support of popular modern compilers, installation building tools, testing tools, version control systems, etc. See Supported Tools.

• Distributed builds. Automated Build Studio provides you with the ability to distribute the execution of macro operations among multiple computers. Using this feature, you can dramatically reduce the project build time, perform multi-platform builds, start automated tests on multiple computers in parallel and so on. See Distributed Builds - Overview.

• Concurrent execution of operations. Automated Build Studio lets you organize concurrent execution of macro operations and thus performs different tasks at the same time. This can greatly reduce the macro execution time, especially on computers with more than one CPU. For complete information, see Concurrent Execution of Operations.

• Remote Macro Execution Control. Automated Build Studio includes special features that let you easily run macros located on remote computers and monitor such macro runs. No other third-party tools needed to control macros located on remote computers. Using Automated Build Studio Web Interface you can control the remote macros through your web browser, even without installing Automated Build Studio on your workstation. See Automated Build Studio Client/Server for complete information.

You can also control remote builds from your macros. The Remote Macro Execution category provides operations that let you start, pause and stop macro runs on remote computers and control the state of remote macros directly from your macro.

• Wide range of available operations. Automated Build Studio includes over 450 built-in operations that let you automate almost any task. You can extend the functionality available with the standard operations by writing scripts or by creating new custom operations (see Creating Custom Operations in on-line help).

• Charts. Automated Build Studio collects information about macro runs performed on your computer or other computers within your network, and displays this information in a graphical form within the Charts panel. Charts can help you analyze the ratio of successful and failed runs, the duration of macro runs and the frequency of macro runs over a desired period of time (day, week, month or other). For more information, see Charts - Overview.

• Scripts in VBScript, JScript and DelphiScript. Even though the built-in Automated Build Studio operations are enough to perform most of the steps for building your applications, you may need to perform some specific actions, which cannot be accomplished using the standard operations. Automated Build Studio includes a Script operation that allows you to create powerful custom script routines using one of the supported scripting languages - VBScript, JScript or DelphiScript. You can use custom scripts to perform actions that can not be performed using the existing standard operations. For more information on creating scripts, see Script Writing - Basics.

• Macro debugger. Automated Build Studio includes a macro debugger that supports breakpoints, stepping over operations, watches, expression evaluation and other debugging features. Using the macro debugger you can trace errors in your macros and fix them. See Debugging Macros.


Introduction 8

• Access to operation properties from scripts. Using scripts you can read and change operation properties. For instance, you can write a script that will increase the build version number in options of a Compile Delphi Project operation. See Working With Operations in Scripts.

• Macro configurations. Quite often, it is needed to build several versions of an application from the same sources; for example, the debug, demo and release versions of the product. Using macro configurations, you can have a single macro that will generate all the desired versions. There is no need to create three macros. You can create only one macro and choose the desired configuration before the run. See Using Macro Configurations.

• Scheduled macro runs. Automated Build Studio includes the Task Scheduler that lets you schedule macro runs at your desire. This is a key feature for creation of automated daily builds. With the Task Scheduler you can schedule and control macro runs not only on your computer, but also on other computers in your local network.

• Event-triggered macro runs (continuous integration support). You can configure Build Studio so that it automatically runs an appropriate macro (say, the macro that builds your project and tests it) not only at specified time, but also when a definite event occurs, for instance, when a source file of your project is changed under source code control (Visual SourceSafe, CVS, etc.). This will ensure that you always have a thoroughly tested build that is compiled with the latest versions of source files and decrease the number of errors that may arise upon integrating source code modifications made by different team members. See Continuous Integration Support.

• Advanced monitoring of macro runs. Automated Build Studio generates detailed logs of macro runs. These logs help you isolate errors that occur during the macro execution. Automated Build Studio automatically compares results of the current macro run with the last successful run, thus letting you know if something is going wrong. See Logging Macro Runs.

• Automatic notifications. Your macros can automatically notify you about the results of their execution. Automated Build Studio offers several operations that can be used for sending notifications. These operations let you send messages via the “net send” command, Windows Messenger, MSN Messenger, Windows Live Messenger, ICQ or e-mail. You can also e-mail reports with attached execution logs. See Sending Notifications.

• Tight integration with TestComplete, AQtime, AQtime .NET Edition and AQdevTeam. Imagine if you could take your project source files from a version control system, build the project and its installation package, test it for memory leaks and performance bottlenecks, perform a comprehensive regression test across the entire application, log all defects and issues, and send an e-mail notification to all relevant teams within your company in relation to new issues discovered since the previous build. Sounds outrageous? It is not - with Automated Build Studio you can. Build Studio offers native integration with AutomatedQA’s Testing, Profiling and Team Collaboration products, including AQtime, AQtime .NET Edition, TestComplete, TestExecute and AQdevTeam, thus allowing you to fully automate your organization’s build, profile, test and deploy processes.

• Integration with Microsoft Visual Studio. For developers who use Microsoft Visual Studio .NET and Microsoft Visual Studio 2005, Automated Build Studio can be tightly integrated into the Microsoft Visual Studio IDE. This integration offers developers full control over Automated Build Studio from within the Visual Studio IDE. You can also run Build Studio macros directly from MSBuild projects and from Visual Studio 2005 Team Explorer.

• Assistant. Automated Build Studio includes a context-sensitive Assistant that displays commands, hints and links to help topics. If you are new to Build Studio and not quite sure how to get started, the Assistant is the perfect place to begin. If you are experienced with Automated Build Studio, the Assistant panel is still helpful since it groups important links in one easily accessible location.


System Requirements 9

• Source Code Control integration. Automated Build Studio is tightly integrated with any source control system that is compatible with the Microsoft Source Code Control API specification (for example, Microsoft Visual SourceSafe, CVS, Borland StarTeam, and many others). This lets you add the current macro to a source control system installed on your computer, check out or check in the macro, and so on, without leaving Automated Build Studio. See Working With Source Control Systems.

• Command-line arguments. A file that holds a macro can be specified on the command line when calling Automated Build Studio. By default, Build Studio will simply open on this macro, but other arguments can make the Studio run the macro, and close after that. Through the command line, Automated Build Studio can be executed in a completely hands-off fashion, inside a make file, a batch file, etc. In addition, the Automated Build Studio installation includes a console executable, AutomatedMacroPlayer.exe that simply runs macros constructed with the help of Build Studio’s user interface. When your macros are complete, you can play them back using this simple and resource efficient executable.

• Using as a COM server. Due to the fact that Automated Build Studio is an OLE server, you can run it and its macros via OLE/COM interfaces, for instance, from scripts defined in other AutomatedQA’s tools, thus making the integration between Build Studio and these tools even closer.

Plug-Ins Like other AutomatedQA products, Automated Build Studio has an open, COM-based architecture. Most

of the features you see in the product are supported through plug-ins. When the plug-in is meant to remain for the life of the current version, it is made an internal part of the product executable. When it is possible that the plug-in could be updated, it is left external (such as the database-access plug-ins). Others will be added to AutomatedQA Web site (http://www.automatedqa.com), and users can write their own plug-ins using the supplied interface documentation and libraries (for instance, user can create plug-ins that will add certain operations to Build Studio).

System Requirements

Minimal System Requirements • Intel Pentium II 450 MHz or higher (Pentium III 800 MHz recommended). • Microsoft Windows Vista, Windows XP, Windows Server 2003, Windows 2000 with Service

Pack 4 or later, or Windows NT 4.0 with Service Pack 6 or later. • Microsoft Internet Explorer 5.0 or later. • 128 MB of RAM (256 MB or more recommended). • 100MB hard disk space. • VGA or higher resolution monitor. • Mouse or other pointing device.

Web Interface Requirements To install Automated Build Studio Web Interface, the following software need to be installed on the

computer:


http://www.automatedqa.com/

Introduction 10

• Microsoft Windows 2000 Professional with Service Pack 4, Microsoft Windows 2000 Server with Service Pack 3, Microsoft Windows XP Professional, Microsoft Windows Server 2003 or Microsoft Windows Vista.

• Microsoft Internet Information Services ver. 5.0 or later. • Microsoft Data Access Components 2.8 or later. • Microsoft .NET Framework 2.0. • Adobe Flash Player 8 or later. Microsoft Internet Information Services should be installed prior to Microsoft .NET Framework 2.0.

The demo version of Automated Build Studio includes all the features available in the registered version but has a 30 operations per macro limit and can be used only during a 30 day trial period.

Supported Tools Automated Build Studio supports the most popular modern compilers, installation building tools, testing

tools, version control systems, etc.

Supported compilers • All compilers that are included in Microsoft Visual Studio 2008, Microsoft Visual Studio 2005

and Microsoft Visual Studio .NET 7.x: Visual C# .NET Visual Basic .NET Visual C++ (both managed and unmanaged projects and modules) Visual J# .NET

Compiler operations for Smart Devices are also supported. • ASP.NET compiler • Microsoft Visual C++ 6.0 • Microsoft Visual Basic 6.0 • CodeGear Delphi 2007 for Microsoft Windows • Borland Developer Studio 2006 (Borland Delphi 2006, Borland C# 2006, Borland VB.NET

2006) • Borland Developer Studio 2005 (Borland Delphi 2005, Borland C# 2005, Borland VB.NET

2005) • Borland Delphi 8 for Microsoft .NET Framework • Borland Delphi ver. 3 - 7 • Borland C++Builder ver. 3 - 6, 2006 • Borland JBuilder ver. 6.0 and later • GCC • Intel C++ Compiler ver. 7.0 - 9.1 for Windows • Intel C++ Compiler ver. 2.0 for Windows CE • Intel Fortran Compiler ver. 8.0 and later for Windows


Supported Tools 11

• Java Compiler • MSIL Assembler • RemObjects Software Chrome

Supported installation building tools • Advanced Installer by Caphyon Ltd. • Ghost Installer Studio • Inno Setup • InstallAnywhere.Net by Zero G Software, Inc • InstallAnywhere Enterprise by Zero G Software, Inc • InstallAware Studio 2005 by InstallAware Software Corporation • InstallShield ver. 7 – 2008 of Professional, Enterprise or Express edition • InstallShield Express Borland Limited Edition ver. 3.0 or later • InstallShield Professional ver. 6.1 - 7.x • InstallShield Universal • Microsoft Setup Project (from Visual Studio 7.0, 7.1 and 2005) • Nullsoft Scriptable Install System 2.0 or later • Installation authoring tools by Wise Solutions, Inc.:

Wise Installation System ver. 9.0 or higher Wise for Windows Installer ver. 5.0 and higher Wise Package Studio ver. 5.0 and higher

• WiX Compiler • WiX Decompiler • WiX Linker

Supported version control systems • Borland StarTeam • Concurrent Versions System (open-source network-transparent version control system) • Jedi Version Control System • Merant PVCS Version Manager • Microsoft Visual SourceSafe v. 6.x, 8.0 • Microsoft Team Foundation Version Control • Perforce by Perforce Software Inc. • Rational ClearCase ver. 2002.05.00 or later • Seapine Surround SCM • SourceGear Vault • SourceOffSite by SourceGear • Subversion by Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato • Team Coherence by Quality Software Components


Introduction 12

Supported help compilers • Doc-O-Matic ver. 4-5 by ToolsFactory Software, Inc. • Help & Manual 3, 4 by EC Software • Microsoft Help Compiler • Microsoft HTML Help Compiler • NDoc • RoboHelp ver. 7 and later • Sandcastle by Microsoft

Supported testing, profiling and issue-tracking tools • Aivosto Project Analyzer • AQdevTeam ver. 1.x by AutomatedQA • AQtime .NET Edition ver. 1.x by AutomatedQA • AQtime ver. 3 - 5 by AutomatedQA • Borland CaliberRM ver. 5.0 or later • Borland StarTeam • CodeHealer by SOCK Software • JUnit • Microsoft Application Center Test scripts • Microsoft Visual Studio 2005 Team System • MSTest • NUnit (James W. Newkirk and others) • Peganza Pascal Analyzer ver. 3.0 or later • Perforce by Perforce Software Inc. • Team Coherence by Quality Software Components • TestComplete ver. 2 - 6 by AutomatedQA • TestExecute ver. 2 - 6 by AutomatedQA

Supported build tools • Apache Ant • IncrediBuild by Xoreax Software Ltd. • Microsoft MSBuild • NAnt (Gerry Shaw and others)

.NET-specific tools • ASP.NET IIS Registration Tool (aspenet_regiis.exe) by Microsoft • Assembly Linker (al.exe) by Microsoft • Assembly Registration Tool (regasm.exe) by Microsoft • CLRxLint by Software4net, Inc. • Demeanor by WiseOwl, Inc.


Supported Tools 13

• Dotfuscator by PreEmptive Solutions • FxCop by Microsoft • Global Assembly Cache Tool (gacutil.exe) by Microsoft • ILMerge by Microsoft • Installer Tool (installutil.exe) by Microsoft • Manifest Generation and Editing Tool (mage.exe) by Microsoft • Native Image Generator (ngen.exe) by Microsoft • Resource File Generator (resgen.exe) by Microsoft • Strong Name Tool (sn.exe) by Microsoft • XenoCode by Code Systems Corporation

Other supported tools • Armadillo by Silicon Realms Toolworks • ASPack • ASProtect • Beyond Compare 2.0 or later by Scooter Software • EurekaLog ver. 4 - 6 by Fabio Dell'Aria • ICQ by Mirabilis Software • IncUpdate Builder ver. 2.53 and later by Sunisoft • madExcept ver. 2 and 3 by Mathias Rauen • Microsoft Robust File Copy (Robocopy) • Microsoft SQL Server • Microsoft SQL Server Best Practices Analyzer • Microsoft Virtual Server 2005 • MSN Messenger by Microsoft • PsTools utilities by Mark Russinovich & Bryce Cogswell • Smart device emulators by Microsoft • SQLMaint • Themida ver. 1.0 or later by Oreands Technologies • UPX by Markus F.X.J. Oberhumer & László Molnár • Visual Patch 2.0 and later by Indigo Rose Corp. • Windows Messenger by Microsoft • Windows Live Messenger by Microsoft • WinLicense ver. 1.0 or later by Oreands Technologies • WinRAR by Eugene Roshal • XCopy by Microsoft

Automated Build Studio can also compress files and extract them from ZIP archives. To work with such archives, no external tools are needed.


Introduction 14

What’s New in Automated Build Studio 4 Version 4 of Automated Build Studio includes a lot of new operations, functionality and support for

more software tools. Below is a list of major changes.

Overall Improvements • Distributed builds. The Remote Macro Execution category of Automated Build Studio version

4 includes new Remote Group and Remote Execution Stack operations that let you distribute the macro workload among several remote computers. Using this feature, you can dramatically reduce the project build time, perform multi-platform builds, start automated tests on multiple computers in parallel and so on. For more information, see Distributed Builds - Overview.

• Support for Microsoft Visual Studio 2008. Automated Build Studio 4 introduces support for Microsoft Visual Studio 2008. The Microsoft Compilers category includes new operations - Compile Visual Basic 2008 Project, Compile Visual C# 2008 Project and Compile Visual C++ 2008 Project that let you compile projects created in Visual Studio 2008. The Compile Visual Studio Solution can now be used to compile Visual Studio 2008 solutions. In addition, operations and triggers that work with Team Foundation now support Visual Studio 2008 Team Foundation.

• Support for CodeGear Delphi 2007. Automated Build Studio now supports CodeGear Delphi 2007 for Microsoft Windows. The Borland Compilers category provides new Compile Delphi 2007 for Win32 Project and Compile Delphi 2007 for Win32 Project Group operations that let you compile your Delphi 2007 projects and project groups from macros.

• MSBuild project editor. Automated Build Studio 4 lets you create, view and modify MSBuild projects. You can create and edit MSBuild projects the same way you work with macros -- by dragging available project elements from the Operations panel to the project and configuring their properties visually. For complete information about working with MSBuild projects in Automated Build Studio, see the Working With MSBuild Projects document or the Working With MSBuild Projects section in on-line help.

• Support for TestComplete 6 and TestExecute 6. Version 4 supports the next version of AutomatedQA’s software testing utilities - TestComplete and TestExecute. The AutomatedQA Tools category includes 2 new operations that let you run tests created with TestComplete and TestExecute version 6. For more information on this, see TestComplete 4-6 and TestExecute 4-6 Operations in the Testing, Profiling and Issue-Tracking Operations document or in on-line help.

• Retrieve and modify EXE and DLL file version information. Using the new Get Version Info and Set Version Info operations, you can retrieve version information (such as product name, manufacturer name, version and so on) from executable files and dynamic link libraries and modify this information.

• Support for JEDI Version Control System. A new JediVCS operation category includes 11 operations that enable you to interact with JediVCS. Using these operations, you can check files in to and out of the repository, get the latest version of files, iterate through project modules, and so on. The new version also includes a special trigger that traces changes in files stored in the JediVCS repository.

• Support for Internet Information Services (IIS). Using the new IIS (Internet Information Services) category you can easily manage IIS from your macros. You can create, delete, start and stop IIS web and FTP sites, manage application pools, save and restore the IIS metabase and perform many other actions.

• Better management of remote macros. Now you can group and filter remote macros displayed in the Client panel of Automated Build Studio and Automated Build Studio Web Interface. A


What’s New in Automated Build Studio 4 15

new Group macros setting in the Client Panel Options Dialog lets you specify whether or not the macros are grouped in the panel. Another new option, Hide non-available macros, let you quickly filter macros displayed in the Client panel and hide the ones that the current user cannot launch due to insufficient permissions.

• Search and replace text in variable values. In Automated Build Studio 4, you can find and replace text not only in operation properties, but also in macro variables' values. For more information, see Find/Replace All dialog in on-line help.

• Automated Build Studio Gadget. Automated Build Studio includes a special gadget that can be added to Windows Vista Sidebar. Using this gadget you can monitor the macro execution state on local and remote workstations. Read the Automated Build Studio Gadget for Windows Sidebar topic for details.

Improved Support for Compilers • The Borland Compilers category includes seven new operations for compiling Delphi,

C++Builder and JBuilder project groups: Compile Delphi 2007 for Win32 Project Group Compile Borland Developer Studio 2006 Project Group Compile Borland Developer Studio 2005 Project Group Compile Delphi 8 for .NET Project Group Compile Delphi 4-7 Project Group Compile C++Builder 3-6 Project Group Compile JBuilder Project Group

• A new Compile Visual Basic 6.0 Project Group operation has been added to the Microsoft Compilers category. You can use this operation to compile a group of Visual Basic 6.0 projects from macros.

• The Compile Visual Studio .NET Solution operation has been improved. Now it lets you specify the projects to be built and select their build configurations.

• The Help Compilers category now includes three operations for working with the Sandcastle help compiler: Sandcastle HTML Generator, Sandcastle XSL Transformer and Sandcastle Reflection Generator.

• The Help Compilers category includes the NDoc 1.31 Help Compiler operation that supports the latest version of the NDoc compiler.

Improved Support for .NET Technologies The .NET Tools category includes eight new operations for working with popular .NET tools:

• The Configure ASP.NET operation provides a visual interface for the .NET Framework aspnet_regiis.exe tool. This operation enables you to configure ASP.NET on the current computer: install or uninstall a specific ASP.NET version, install and update script maps, create client-script directories and so on.

• Using the new Edit Assembly Information operation, you can modify assembly attributes in assembly information source files.

• The Fix COM References operation allows you to fix references to COM interop assemblies in Microsoft Visual Studio .NET projects.


Introduction 16

• The Manifest Generation and Editing operation provides an interface to the .NET Framework mage.exe tool. You can use this operation to generate, update and sign manifests for ClickOnce applications.

• Using the Native Image Generator operation, which is a wrapper for the .NET Framework ngen.exe tool, you can manage the native image cache for .NET assemblies.

• The Resources Generator operation, which provides an interface for the resgen.exe tool, lets you convert between various types of assembly resource files.

• The Run AL.EXE and Run SN.EXE operations let you run the Assembly Linker (al.exe) and Strong Name (sn.exe) tools with the specified parameters.

Enhanced Support for Source Control Systems • A new JediVCS category provides operations that let you work with JEDI Version Control

System: check files in and out of the JEDI VCS repository, get the latest version of files, iterate through files in a project and so on.

• Support for Microsoft Visual Studio 2008 Team Foundation Version Control has been added. All operations of the Team Foundation Version Control category and the Team Foundation Version Control File Change trigger now contain the MS VS Version property that specifies which Team Foundation version should be used.

• The Concurrent Versions System category includes new operations: The CVS Login and CVS Logout operations enable you to log in to and out of a CVS

repository. After calling CVS Login in your macro, you may skip specifying the authentication information for other CVS operations. CVS Logout cancels this mode.

Using the Get Changes From CVS operation you can get a list of modified, added and removed files from a CVS repository.

• Operations of the Concurrent Versions System category now support the server access method. The Access method property now has the corresponding server option that you can use to access the remote repository.

• A new StarTeam Remove operation in the StarTeam category lets you remove files from both the StarTeam repository and the local working folder.

Enhanced Working With Files The Read/Write category contains six new operations that make it easier to work with text, INI and XML

files from macros: • The Read From File and Write To File operations let you read the text file contents to a macro

variable and write text to a file. • The File Content Enumerator operation allows you to iterate through lines in a text file and

perform specific actions on each line. • Using the Get XML Value and Set XML Value operations, you can obtain and modify data

stored in an XML file. • Using the new INI File Enumerator operation, you can perform a set of operations over each

section or value of an INI file.

Other Changes in Operations • The Installers category includes seven new operations:


What’s New in Automated Build Studio 4 17

Using the Advanced Installer operation, you can build your installation packages with Advanced Installer.

The InstallShield Standalone Build operation allows you to compile your installation program using the InstallShield Standalone Build module.

The MSI Generic, MSI Merge, MSI Transform, MSI Update Properties and MSI Validation operations let you work directly with Windows Installer (MSI) packages, for example, execute SQL queries with databases, update their property values, and so on.

In addition, the InstallShield 7-2008 operation contains a new Additional action property, which enables or disables the -e command-line parameter usage for the IsCmdBld.exe tool.

• The Prepare Code category includes a new EurekaLog 6 operation that introduces support for EurekaLog version 6. You can use this operation to debug your Win32 projects that were created with Borland Delphi 3-7, 2005, 2006, CodeGear Delphi 2007 and C++Builder 5-6, 2006. To do this, add the EurekaLog 6 operation as a child for the corresponding Compile operation.

• The WMI category includes three new operations: Install Application (WMI), Upgrade Application (WMI) and Uninstall/Reinstall Application (WMI). These operation let you install, advertise, uprgade, reinstall and uninstall applications on local and remote computers.

• The FTP category includes a new Synchronize Directories operation that allows you to synchronize directory contents on the local computer and the FTP server.

• The Files and Directories category contains the following new operations: Get File Attribures - Lets you obtain file attributes. Set Manifest - Enables you to incorporate a manifest into executable files or DLLS. Set Resource Language - Lets you specify the language of resources stored in executables

or DLLs. • A new Wait category provides eight operations that let you delay the macro execution until a

specific event occurs: a particular date and time, a file’s contents changes, a process is launched, a remote computer responds, and so on.

• A new Misc category has been added. It contains the following operations: The Create GUID operation can be used to generate a GUID string in various formats. The If COM Class Registered operation lets you check whether a specific COM class is

registered on the current computer. Using the Get Free Disk Space operation, you can determine the amount of free space

available on a local disk drive. The If Window Exists operation enables you to check whether a particular window is

displayed on the screen. Also, the Comment and Delay operations were moved from the Standard category to the Misc category.

• A new If Registry Key or Value Exists operation enables you to check whether a specific key or a value entry exists in the the system registry.

• A new List Enumerator operation allows you to iterate through a list of arbitrary items and perform specific actions over them.

• The Team Foundation Create Work Issue and Team Foundation Edit Work Issue operations now support Microsoft Visual Studio 2008 Team Foundation.

• The If Remote Macro State Is ... operation has been improved. Now it lets you specify several states that the remote macro will be checked against.


Introduction 18

• The TestComplete 4-5 and TestExecute 4-5 operations now let you specify a project test item to be run.

• The Execute Macro operation has been enhanced. Now it lets you specify input as well as output variables for the macro to be run.

• The Validate XML File operation contains a new MS XML Version property that specifies which version of the Microsoft XML parser should be used.

• The Extract Files From ZIP File and Extract Files From RAR File operations now allow you to only extract some of the files out of the archive. The operations’ properties dialog contains the new Files To Extract tabbed page where you specify the list of files to extract.

• The Timeout parameter is now required for all operations of the Interactive category. This way, Automated Build Studio automatically closes the dialogs dispalyed by these operations after the specified timeout period elapses.

• The Set Variable operation was renamed to Set/Reset Variable Value. Now this operation lets you not only modify variable values and stored variables, but also restores their default values.

• The Demeanor operation has been renamed to WiseOwl Demeanor. • The Star Team Delete operation has been renamed to StarTeam Delete Local.

Macro Variables and Constants Enhancements • In earlier versions, the values of stored variables were saved to the macro’s file. In version 4,

these values can now be saved to an individual file. This feature allows you to have computer-dependent stored variable values. To enable the feature, check the Store values in separate file check box in the Stored Variables dialog.

• Ordinary macro variables can now have default values. You can specify this value in the Variables dialog.

• Macro variables now have a new Thread-relative attribute. It is useful if your macro contains concurrent operations and controls whether the variable should have separate values for each execution thread. For example, Submacro variables have this attribute set by default.

• It is now possible to specify descriptions for macro variables, stored variables and constants. This way, you can document variables and constants used in your macros. The descriptions can also be displayed in the Variables and Constants dialog that is used to specify variables and constants in operation properties, if the Show description option is checked.

• Now you can find and replace text in default values of macro variables and values of stored variables and constants.

• It is now possible to sort the list of variables and constants in the Variables, Stored Variables, Environment Variables, Constants and System Constants dialogs.

• The following system constants have been added: TESTCOMPLETE6, TESTCOMPLETE6DIR, TESTEXECUTE6 and TESTEXECUTE6DIR. These constants provide information about TestComplete 6 and TestExecute 6.

Miscellaneous • A new Log variables changing setting has been added to macro properties. This option specifies

whether Automated Build Studio should post log messages when macro variable values have been changed.

• Automated Build Studio includes a new Default project format option that lets you specify the files' format created when Build Studio starts.


Getting Support 19

• Now the Operation Properties dialog can be invoked right after adding the operation to your macro. You can enable or disable this behavior using the new Show Properties dialog when adding a new item option. The option also works for MSBuild projects.

• The XML schema used for creating custom operations has been enhanced. The syntax attribute of the property element, which defines the operation property type, can now have the EncryptedString value. This new type corresponds to string properties whose values are encrypted when stored in the macro file. For more information, see Creating XML Files That Define Operation Properties in on-line help.

Getting Support If you have questions, problems or just need help with Automated Build Studio, please contact our e-

mail support team at:

[email protected]

For information on our support policies, please visit our web site www.automatedqa.com/support.

You can also ask questions, search for answers, exchange comments and suggestions on our newsgroup and on the Community web site:

news://forums.automatedqa.com/automatedqa.public.automatedbuildstudio

http://www.automatedqa.com/community

All your comments and suggestions will be greatly appreciated.

You may find answers to your question in the list of the frequently asked questions which is available at:

http://www.automatedqa.com/products/abs_faq.asp

Make sure you regularly visit the AutomatedQA Web site, http://www.automatedqa.com, where you will find:

• News • More recent support options including frequently asked questions on our products • Technical papers from AutomatedQA • Downloads, such as plug-ins and free tools, from AutomatedQA • Hot Stuff contributed by experienced users and the AQA team (hands-on solutions, code, plug-

ins, etc.)

Automated Build Studio Samples A good way to get started using Automated Build Studio is to explore sample macros that are included

with the Build Studio installation. Here is a list of all samples:

CompileDelphiProject.bxp

<Automated Build Studio>\Samples\Macros\CompileDelphiProject


mailto:[email protected]

http://www.automatedqa.com/support

news://forums.automatedqa.com/automatedqa.public.automatedbuildstudio

http://www.automatedqa.com/community

http://www.automatedqa.com/products/abs_faq.asp

http://www.automatedqa.com/

Introduction 20

Demonstrates how you can perform typical major steps when building an application (in this instance, it is a Delphi application):

• Getting source files from a version control system (in this macro it is Visual SourceSafe) • Opening the project in the development tool • Compiling the project • Incrementing the version number (it will be used for the further builds) • Sending notifications that the application has build successfully

In addition, the sample macro demonstrates how to handle errors in the macro.

CompileCPPProject.bxp

<Automated Build Studio>\Samples\Macros\CompileCPPProject Does the same as CompileDelphiProject.bxp, though it builds a Visual C++ .NET application.

Integration.bxp

<Automated Build Studio>\Samples\Macros\Integration

Resembles the CompileDelphiProject.bxp macro but upon compiling the Delphi project it also runs the VCL Class profiler of AQtime 3 for the compiled application and then runs a TestComplete script to simulate user action in the application.

BuildLogic.bxp

<Automated Build Studio>\Samples\Macros\BuildLogic

Is similar to CompileDelphiProject.bxp but its main purpose is to demonstrate how you can control the logic of macro execution by initializing macro variables via the command line.

Notifications.bxp

<Automated Build Studio>\Samples\Macros\Notifications

Demonstrates how you can send a notification if an operation failed to execute successfully. To send notifications, the macro uses submacros which run when an operation fails.

ReadWriteFile.bxp

<Automated Build Studio>\Samples\Macros\ReadWriteFile

Demonstres how you can write and read data to or from text files using Windows File System Object (FSO).

ReadWriteXMLFile.bxp <Automated Build Studio>\Samples\Macros\ReadWriteXMLFile

Demonstrates how you can write and read data to or from XML files using MS XML.

ABS_RSS_Demo.bxp <Automated Build Studio>\Samples\Macros\RSS

Demonstrates how you can create an RSS feed from ABS log summaries.

MakeSample.bxp and DelphiSamples.bxp


Automated Build Studio and Windows Firewall 21

<Automated Build Studio>\Samples\Operations\Delphi The first of these macros compiles a sample Build Studio operation written in Delphi. The second macro

demonstrates how to use this operation, Text File Iterator (Delphi), in macros. For more information on how to create custom operations for Automated Build Studio, see Creating Custom Operations in on-line help.

MakeSample.bxp and DotNetSamples.bxp <Automated Build Studio>\Samples\Operations\DotNet

The first of these macros compiles a sample Build Studio operation written in Visual C# .NET. The second macro demonstrates how to use this operation, Text File Iterator (.NET), in macros. For more information on how to create custom operations for Automated Build Studio, see Creating Custom Operations in on-line help.

Automated Build Studio and Windows Firewall The latest versions of the Windows operating system (Windows XP Service Pack 2, Windows Server

2003 and Windows Vista) include a Windows Firewall. It is special software that controls data transfers between your computer and other computers. Using Windows Firewall you can allow only certain programs and services to exchange data with certain computers only; requests that are sent by other applications or to other computers will be blocked.

There are several operations in Automated Build Studio that require that your computer be connected to the network. For instance, operations that work with source control systems or operations that send e-mail messages. In order for these operations to execute successfully, you may need to modify Windows Firewall settings.

To modify Windows Firewall settings: • Open Control Panel and select Windows Firewall there. This will open the following dialog:


Introduction 22

• If the Off setting is selected, Windows Firewall is inactive and it does not block any network

requests. In this case, Automated Build Studio will be able to connect to the network. • If the On setting is selected, Windows Firewall is active and it controls data transfers. In this

case, you should modify Windows Firewall settings to enable Automated Build Studio to connect to the network. Namely, you should add Automated Build Studio to the list of application that will not be blocked by Windows Firewall. To do this: Uncheck the Don’t allow exceptions box. In this case, Windows Firewall will block any

network requests from all the programs and services except for those that are mentioned on the Exceptions tabbed page.

Switch to the Exceptions tabbed page. Press Add Program. This will call the Add a Program dialog in which you can specify the

application to be added to the exceptions list. Use this dialog to add Automated Build Studio.exe (<AutomatedBuildStudio>\bin\AutomatedBuildStudio.exe) to the exceptions list. If you use Automated Macro Player, add it to the exceptions list as well (<AutomatedBuildStudio>\bin\AutomatedMacroPlayer.exe).

In the Add a Program dialog, you can also specify IP addresses of computers, with which Automated Build Studio can exchange data. To do this, press Change scope and use the subsequent dialog.


Automated Build Studio and Windows Firewall 23

Automated Build Studio can run applications from macros. If the application launched from a macro receives data from other computers in the network, you should modify Windows Firewall settings for this application. You can do this in the same manner as you would for Automated Build Studio.


Getting Started 24

Getting Started The Getting Started topics describe actions you may need to perform to create macros with Automated

Build Studio.

General Information Basic Concepts User Interface - Overview

Creating Macros Creating a Macro

Adding, Removing and Arranging Operations in a Macro

Modifying Operation Properties

Saving and Loading Macros

Using Macro Configurations

Running Macros

Logging Macro Runs

Analyzing Results of Macro Runs

Further Steps Sending Notifications Exporting Results of Macro Runs Handling Errors in Macros

Incrementing the Build Version Number Scheduling Macro Runs

Basic Concepts Automated Build Studio is a tool that is used to create macros. A macro includes a sequence of

operations to be executed as well as variables and constants that can be used by operations. A macro is an analogue of a project in development tools like Microsoft Visual Studio or Borland Delphi. You can save and load macros into Automated Build Studio, insert one macro into another, run macros, debug them, check the results and perform other actions.

Note: Besides editing macros, you can also use Automated Build Studio to modify MSBuild projects. When you open an MSBuild project in Automated Build Studio, the latter switches into a special edit mode. This mode only supports MSBuild-related features; it disables all other features. This special mode is used because the differences between the tools are significant, and some of the Automated Build Studio features cannot be implemented in MSBuild projects. For information on editing MSBuild projects, see the Working With MSBuild Projects


Basic Concepts 25

document or the Working With MSBuild Projects section in on-line help.

Automated Build Studio – Basic Concepts

Automated Build Studio macros consist of operations.An operation performs an elementary action, such as copying files or compiling a project. We use the word “operation” as a general term. For some operations, it would be better to use the term “statement”, for others – the term “function” or “procedure”. All the operations that you can use in your scripts are displayed in the Operations panel. (In Build Studio running as a standalone application, this panel is displayed on the left of Automated Build Studio’s main window by default. In Build Studio integrated into Visual Studio .NET, this panel is docked to Visual Studio’s Toolbox panel by default. If Toolbox is auto-hidden, the Operations panel is also hidden. To make it visible, press the

button.)

Automated Build Studio standalone


Getting Started 26

Automated Build Studio integrated into Visual Studio .NET

All of the operations displayed in the Operations panel are organized into categories. For instance, the Microsoft Visual SourceSafe, PVCS and Concurrent Version System categories include operations that deal with version control systems. Among operation categories, there is a special Frequently Used category that holds the top 20 operations that you have most frequently used when creating your macros. For more information about categories and operations they hold, see List of Operations.

Build Studio includes a lot of operations, so some categories can be invisible within the Operations panel. You can reach them by scrolling the panel or by using the Categories item at the top of the Operations panel. You can hide or display operations and categories in the Operations panel, change the categories order, move operations between categories, create custom categories and perform other


Basic Concepts 27

customizing actions over operations in the Operations panel. For more information on this, see Customize Operations Palette Dialog.

Note: We would like to point out the Script operation of the Standard category. This operation allows you to create custom script routines in one of the supported scripting languages - VBScript, JScript or DelphiScript. Custom scripts extend the functionality provided by standard operations. They can perform certain actions that could not be done by existing operations. For more information on creating scripts, see Script Writing - Basics.

To find an operation quickly, you can type the operation name in the edit box at the top of the Operation panel. Automated Build Studio will search for the operation while you are typing and display operations that match the search criterion in the Operation panel. To cancel the search, select the Cancel Search item at the panel toolbar.

Besides Operations, Build Studio’s main window holds six more panels: Macro, Log, Summary, Charts, Client and Assistant (Build Studio Assistant in Visual Studio).

• The top-right panel, Macro, holds operations that you added to the macro. For each operation, it displays the operation name, description and two check boxes: the left box specifies if Build Studio will execute the operation; the right check box specifies whether the macro stops running if an error occurs during execution of this operation. Some operations can have child operations. For example, child operations of the For Loop operation will be executed as the loop “body”. Child operations are displayed as child nodes of their parent operation. Child operations can also have child operations, which, in turn, can also have their child operations, etc. That is, the operation list in the macro has a tree-like structure. When running a macro, Automated Build Studio executes the operations in the order of their appearance in the Macro panel, from top to bottom. For more information on how to add, remove and arrange operations in the macro, see Adding, Removing and Arranging Operations in a Macro. By default, Automated Build Studio executes the operations in the same order as they appear in the Macro panel, from top to bottom. This is called serial execution. But you can also configure the macro so that Build Studio executes some operations or groups of operations concurrently. This lets you perform different tasks at the same time (for example, one group of operations uploads files to an FTP server, whereas at the same time another group of operations cleans working folders). For more information on how to run macro operations concurrently, see Concurrent Operations Execution.

• The Log panel displays results of the macro execution. Automated Build Studio monitors every macro run and logs the name of every operation that was executed (the Message column) as well as the time spent on executing each operation along with all of its child operations (the Time with Children column). Besides the results of the operation execution, the log can also contain custom messages. The Standard category includes the Log Message operation that lets you post a custom message to the log. See Logging Macro Runs for more information.

• Like the Log panel, the Summary panel displays results of the macro execution but in the comparative form: you can simultaneously view results both of the current macro run and of the previous run that was finished without failures in the macro. Thus if the macro fails or an error (warning) occurs in an operation, you can quickly see what caused this malfunction in comparison with the run where there were no such problems.

• The Charts panel displays statistics on macro runs performed on your computer. For more information on this, see Charts - Overview.


Getting Started 28

• The Client panel is used to control the macro run on remote computers. See Automated Build Studio Client/Server – Overview for more information on this.

• The Assistant panel (in Visual Studio .NET, this panel is called Build Studio Assistant) helps you get started with Build Studio's user interface and provides a quick way to perform common tasks that arise when you are working with Build Studio.

As we have said above, a macro can also hold variables and constants that you can use to set values for operations properties. Variables, for instance, can store values that should be shared between several operations: one of the operations can store its result to a variable and another operation can use this variable as a parameter. This topic contains only brief overview of variables and constants. For complete information, see Using Variables and Constants in Macros.

To create or check values of variables and constants, use items of the Variables menu.

Automated Build Studio standalone

Automated Build Studio integrated into Visual Studio .NET

There are two types of macro variables: ordinary variables and stored variables. Ordinary variables are reset once the macro run is over. Stored variables store their values between subsequent macro runs. A common task for stored variables, for example, is to store the build version number.

Both ordinary and stored variables have the environment attribute. If it is set for a variable, this variable becomes an environment variable for the processes launched by the macro. For instance, such variables are passed as environment variables to the process that is started by the Execute Program operation.

Automated Build Studio also provides easy access to the operating system’s environment variables. However, these variables cannot be changed in macros. They are used as constants.


User Interface – Overview 29

As for constants, they can be used in macros similarly to variables. A constant can be user-defined or system. User-defined constants are ordinary constants, which you create and which value you specify. System constants hold predefined values such as paths to compilers, archivers, etc.

Note that both variables and constants can be used in scripts. For more information on this, see Using Variables and Constants in Macros.

Editing MSBuild Projects You can use Automated Build Studio to modify MSBuild projects. The MSBuild editing feature only

works if you use Automated Build Studio as a stand-alone application. It does not work when Automated Build Studio is integrated into Microsoft Visual Studio.

Editing MSBuild projects is similar to editing macros. When you are editing MSBuild projects, the Operations panel displays the elements that can be added to

the project. Note that since there are not a lot of elements, the panel’s search functionality is turned off. You add an element to your project by selecting this element in the Operations panel and then clicking

on the element that you would like to be its parent, in the Macro panel. The Macro panel displays the project elements in the same order, in which they are in the project file.

You can change the order, if needed, by using the , , and toolbar items. These items can be disabled if the element’s position cannot be changed.

The Macro panel contains two columns that specify the element’s name and the contents of the element’s Condition property. If the Show Details item in the context menu of the Macro panel is checked, the panel also displays elements’ properties under the elements’ names.

To modify an element's properties, right-click this element in the Macro panel and select Properties from the context menu, or double-click the element in the Macro panel. This displays the Properties dialog, where you can modify the properties of the element. For more information on properties, see MSBuild Project Elements Reference in the Working With MSBuild Projects document or in on-line help.

When you are editing MSBuild projects, many Automated Build Studio features are turned off. This happens because the differences between the tools are significant, and some Build Studio features cannot be used in MSBuild projects. For instance, the concept of configurations and stored variables does not work for MSBuild, so the appropriate Build Studio dialogs are disabled. Also, Automated Build Studio does not allow running and debugging of MSBuild projects, so all of the run and debug specific menu items are disabled.

Note that Automated Build Studio only turns off those features that cannot be used in MSBuild projects. Non-specific features are available. For instance, you can use the Client panel to manage remote macro runs and you can use the Charts panel to view build statistics.

For more information on editing MSBuild projects, see the Working With MSBuild Projects document or the Working With MSBuild Projects section in on-line help.

User Interface – Overview

Automated Build Studio Standalone The user interface of Automated Build Studio consists of panels, the main menu and toolbars. The

general layout is as follows:


Getting Started 30

Most of Build Studio’s screen area is occupied by panels: Operations, Macro, Log, Summary and

Assistant. Each panel serves a separate purpose in your work with Build Studio. The purpose of panels and how they work together is explained in a separate topic which you should read: Basic Concepts.

The size and layout of panels are not fixed. You can change panel sizes by dragging the separator between them. But the most important point about handling panels is how they can be moved around - docking. Panels are where you do your actual work and get your results in Automated Build Studio. Docking is our way of providing you with the most flexible workspace for the particular task you are interested in. It means that the entire work area can be reconfigured at will, even beyond what is possible with toolbars (moving, hiding, etc.). Docking of panels in Build Studio is similar to docking windows in Microsoft Visual Studio. For instance, you can hide panels by clicking the button in the panel caption. This will minimize the panel along one of the sides of Build Studio's window, so only the panel caption remains visible:



The panel pops up when you move the mouse over the caption. For more information on auto-hiding and

docking panels, see Docking in on-line help.

In the Macro, Log and Summary panels, you can -- • Resize columns by dragging the separator between column headers. • Swap columns by dragging their headers from one location to another. • Add and remove columns to the panel:

Select the Field Chooser menu item from the panel's context menu. The Columns dialog will appear. To add a column, drag it from the Columns dialog onto the panel. To remove a column from the panel, drag it from the panel and drop onto the Columns dialog:

The Macro, Log, Summary and Assistant panels have a number of options that can be modified via the

Options dialog. The general view and behavior of panels can be modified in the User Interface dialog. To save the current panel layout to a file, select Options | Desktop | Save Docking to File from Build

Studio’s main menu (by default, these files have the .qtdock extension). To load the panel layout from a file, select Options | Desktop | Load Docking from File. To restore the default panel layout, select Options |


Getting Started 32

Desktop | Restore Default Docking. The Save Desktop As and Load Desktop items of the Options | Desktop submenu will save and load the panel layout along with the toolbar settings.

The Automated Build Studio interface receives commands in four ways: • through menus • through popup menus (right-click, context-dependent) • through toolbars • through keyboard shortcuts

Keyboard shortcuts can be customized via the Customize Keyboard dialog. You can define your own shortcuts or select one of the predefined key mapping schemes: MS Visual Studio IDE or Borland IDE.

As in Microsoft Word or Excel, menus are a type of toolbar, and both can be customized at will. You can also create your own toolbars. By default, toolbars are docked at the top of Build Studio’s window. You can easily dock them to any other edge by dragging them to the left, right or bottom edge of the window. To remove or add buttons, you can either call the Toolbar Customization window or use the Quick Customization feature. For complete overview, see Toolbars Customization in on-line help.

To save or load the current layout of toolbars and toolbar items, use the Options | Desktop | Save Toolbars to File and Options | Desktop | Load Toolbars from File menu items. To restore the default toolbar layout, select Options | Desktop | Restore Default Toolbars. To save and load the layout of panels, menus and toolbars, use the Options | Desktop | Save Desktop As and Options | Desktop | Load Desktop menu items.

Automated Build Studio Integrated Into Visual Studio .NET Build Studio’s user interface consists of panels, the main menu and toolbars. Once Build Studio has been

integrated into Visual Studio, the Build Studio project node appears in the Solution Explorer under the solution node; the Automated Build Studio panels - Macro, Operations, Log, Summary and Assistant - become components of Visual Studio (the Assistant panel is called Build Studio Assistant in Visual Studio):



Panels are where you do your actual work in Build Studio. Every panel serves a different purpose. For

more detailed information on the different purposes and on how the panels work together, see Basic Concepts.

You can change the panel size and location in the same way you do other Visual Studio windows. To bring up a panel, select Build Studio | Panel List from Visual Studio’s menu and then choose the panel from the ensuing Select Panel dialog.

Panels have a number of options that can be modified via the Options dialog. The Build Studio panels have a toolbar at the top. The toolbar items allow you to perform certain

operations over data displayed in panels. For instance, the Show Operation Details item of the Macro toolbar let you preview the operation properties directly in the Macro panel:


Getting Started 34

Even more operations are available in the context menu for each panel. For instance, the context menu of

the Log panel holds the Export item that can be used for exporting the results of a macro run to text, html or xml files:

You can dock a “panel” toolbar to any side of the panel that holds this toolbar. There is also a way to

hide or display items of these toolbars. For more information, see Toolbars Customization in on-line help. Unlike toolbars, the panel’s context menu is not customizable.

Besides the “panel” toolbars, Automated Build Studio also adds a toolbar, Automated Build Studio, to Visual Studio. You can display this toolbar by right-clicking somewhere in the toolbar area and checking the Automated Build Studio item in the subsequent context menu. The toolbar holds the following items:

The toolbar items are displayed or hidden depending on the current context. For instance, the Stop item will not be visible until you start the macro execution.

Automated Build Studio also adds the Build Studio item to Visual Studio’s main menu:


Creating a Macro 35

The menu holds the same items as the Automated Build Studio toolbar does plus the following extra

items: Batch Run, Append Macro From, Options, Tasks (Windows Scheduler), Tasks (Continuous Integration) and Tools. Batch Run lets you run the macro using several macro configurations at once. Using the Append Macro From item, you can add operations stored in another macro to your macro. The Options item provides access to Build Studio options, to the Install Extensions dialog and to the properties of the Build Studio project. The Tasks (Windows Scheduler) item allows you to schedule the macro execution. The Tasks (Continuous Integration) lets you create time- and event-triggered tasks that run your macro; an example of such a task is running a macro that builds your project when the project files are modified under source code control. The Tools item provides access to the Tools dialog.

You can manage the Build Studio menu and the Automated Build Studio toolbar in the same manner as you manage other Visual Studio menus and toolbars.

Creating a Macro Your macro is simply your current “work site” in Automated Build Studio. It unifies operations to be

executed and variables and constants that will be used by the operations. Automated Build Studio supports creating and editing of two types of files:

• Automated Build Studio macros • MSBuild projects

If you use Automated Build Studio as a standalone application, then to create a new macro or an MSBUild project, simply use the corresponding command of the File | New:


Getting Started 36

If you want to modify a file that already exists, you should open it in Automated Build Studio first. To do

this, select File | Open from the main menu. This will call the standard Open File dialog where you can select the desired file.

After the macro is created (opened), you can add operations to it and modify their properties, and create and modify macro constants and variables, and so on. You can edit MSBuild projects in a similar way, by adding targets, tasks and other elements and configuring their properties.

In Build Studio integrated into Visual Studio .NET, you can only work with Build Studio macros – the integrated version does not support editing of MSBuild projects.

You can create a new macro in the same way as you create new projects in Visual Studio: • Select File | New | Project from Visual Studio’s menu or press the New Project button on the

Start page.

This will call the New Project dialog.

• In the dialog:


Creating a Macro 37

Select Automated Build Studio Projects from the list on the left of the dialog and then select Automated Build Studio Project or Automated Build Studio Project (XML Format) on the right.

Note: The difference between these options is the format the macro file will have. (A macro can be stored either in binary or xml format. For more information, see Saving and Loading Macros).

Specify the project name, location and solution. Press OK. Also, the New Project dialog appears when you select Build Studio | Add ABS Project from Visual Studio's menu, or press the Add ABS Project from the Solution Explorer:

If a solution is open in Visual Studio .NET when you select Add ABS Project, upon pressing OK in the

New Project dialog the new Automated Build Studio project will be added to the solution. In addition, you


Getting Started 38

will also be asked for which of the solution's projects you want to add the corresponding Compile operations to the macro. To do this, the Add Projects to ABS Project dialog is used.

A macro added to a Visual Studio solution should not contain the Compile Visual Studio .NET Solution operation that compiles the parent solution itself. Such an operation causes a circular reference and leads to an error.

You can open an existing Automated Build Studio macro in the Visual Studio .NET in the same manner as you open any other Visual Studio project: just select File | Open Project.

After the macro is created (opened), you can add operations to it and create and modify constants and variables.

Adding, Removing and Arranging Operations in a Macro Before adding an operation to the macro, locate that operation in the Operations panel (by default, this

panel is on the left side of the Automated Build Studio window). The contents of the Operation panel depend on whether you are editing an Automated Build Studio macro or an MSBuild project:

• If you are editing an Automated Build Studio macro, the Operations panel displays a list of available operations grouped by their categories.

• If you are editing an MSBuild project, the Operations panel displays a list of elements that can be used in MSBuild projects. For information on these elements and modifying MSBuild projects in Automated Build Studio, see the Working With MSBuild Projects document or the Working With MSBuild Projects section in on-line help.

This topic explains how you can work with macros’ operations in the Operations panel. Working with MSBuild project elements in the panel is similar to working with operations. For information on adding elements to and removing them from MSBuild projects, see the Working With MSBuild Projects document or the Working With MSBuild Projects section in on-line help.

Automated Build Studio offers a lot of operations that can be used in macros. Before adding an operation to a macro, you should locate that operation in the Operations panel. You can do this in either of the following ways:

• Expand the category holding the desired operation in the Operations panel. Some categories may be invisible within the panel, so to reach them, you should scroll the panel or press the Categories item from the toolbar of the Operations panel and then select the category from the ensuing popup list.

– or – • Search for the operation by typing the operation name in the edit box at the top of the Operations

panel. Automated Build Studio will search for the operation while you are typing and display operation that match the search pattern in the Operations panel. For instance, the following image illustrates the situation when a user has typed Set and Automated Build Studio has displayed all operations, which names include the substring Set:


Adding, Removing and Arranging Operations in a Macro 39

To stop the search and restore normal categories display, select Cancel Search from

the panel toolbar.

Note: The search functionality is off when you are editing MSBuild projects. There are not a lot of MSBuild project elements, so you can quickly find the desired element within the Operations panel.

Once you have located the desired operation in the Operation panel, you can add it to the macro in any of the following ways:

• Double-click the desired operation in the Operations panel. The new operation will be added to the macro below the currently selected operation.

• Click the desired operation in the Operations panel, then switch to the Macro panel. If you place the mouse cursor over an operation in the macro, the cursor will include an arrow that points upwards or downwards depending upon over which part (upper or lower) of that operation the mouse cursor is currently located. If you click that operation, the new operation will be added before or after it according to the arrow direction in the mouse cursor. If you click below the list of operations, the new operation will be added to the end of the macro.

Once you have added an operation to the macro, you can modify the operation’s properties. Property values are defined via the Operation Properties dialog. If the Show Properties dialog when adding a new item option is enabled in the macro options, this dialog is called automatically upon adding an operation. Otherwise you should call the dialog manually. To do this, either right-click the desired operation and select Properties from the context menu, or simply double-click the operation in the Macro panel, or press Enter


Getting Started 40

when that operation is selected in the Macro panel. For instructions on how to specify operation properties see Modifying Operation Properties.

Some operations may have child operations. For instance, While Loop, For Loop or If … Then. For loop operations it means that child operations will be run within the loop “body”. For If … Then, it means that child operations will be executed provided that the if condition is True. To make an operation a child one, simply drag the operation from the left (or right) panel and drop it over another operation you want to be the “parent”. To change operations’ “relationships”, you can also use the Indent and Un-Indent items of Build Studio’s Edit toolbar or Edit menu or of Visual Studio’s Macro panel toolbar. In addition, you can press Ctrl-Right or Ctrl-Left in Build Studio running as a standalone application (these shortcuts can be customized in the Customize Keyboard dialog).

You can select operations within the macro and drag them along the tree: move the selected operation to another place, copy the operation, or make one operation a child of another.

Once you have added an operation to the macro, you can modify the operation’s properties. To do this, either right-click the desired operation and select Properties from the context menu, or simply double-click the operation in the Macro panel, or press Enter when that operation is selected in the Macro panel. This will open the Operation Properties dialog where you can specify the property values. For more information about this, see Modifying Operation Properties.

Note that by default, operations are executed in the same order they are displayed in the Macro panel of Build Studio -- from top to bottom (except for Initialization, Finalization and Submacro operations). It is also possible to run certain operations or groups of operations concurrently. To learn more, see Concurrent Execution of Operations.

Note that operations are executed in the same order they are displayed in the Macro panel of Build Studio - from the top to bottom (the only exception is the Submacro operation). To change the order of operations in the macro, use the Move Up and Move Down items on Build Studio’s Edit toolbar or the Edit menu, press Ctrl-Up or Ctrl-Down (this is available only if Build Studio is running as a standalone application), on Visual Studio’s Macro panel toolbar or simply drag and drop an operation to the desired location. The operation being dragged is placed before or after the operation on which it is dropped: the exact new location of the dragged operation is indicated by an arrow in the mouse cursor which is displayed when you hover the cursor over an existing operation before dropping. You can copy the chosen operation to another location: just keep Ctrl pressed when dragging the operation.

To remove the chosen operation from the macro, either select Remove Operation from the context menu, from Build Studio’s Edit menu or from Visual Studio’s Macro panel toolbar, or press Del. To delete all the operations at once, select Clear All from the context menu or from Build Studio’s Edit menu.

To select several operations in the macro, hold down Shift or Ctrl when selecting the needed operations. If the selected operations meet all of the following conditions, you can change their position in the macro or remove them at once:

• The selected operations belong to the same level in the tree. • There are no unselected operations between them at the same level. • The selected operations do not belong to different parents.

You can copy or cut an operation to and paste it from the clipboard. To do this, use the Edit menu's Copy, Cut and Paste items of the Edit menu (or the Macro panel toolbar, if you use Automated Build Studio integrated into Microsoft Visual Studio). You can also copy, cut and paste several operations located at the same level.

To undo or redo changes you made in the macro or in operation properties, either use the Undo and Redo items of the Edit menu (the Macro panel toolbar in Visual Studio) or press Ctrl-Z or Ctrl-Y

respectively.


Modifying Operation Properties 41

You can also save the modified macro to a file and load it later (see Saving and Loading Macros).

Modifying Operation Properties Each operation or MSBuild project element has a number of properties that let you specify the actual

actions that the operation (or element) performs. For instance, if you want your macro to compile a C# project, you should at least specify the project name in the operation properties. Therefore, once you have added an operation (or element) to your macro (or MSBuild project) your next step is to modify the properties of this operation (or element).

Note that editing MSBuild projects is only supported in Automated Build Studio Standalone. Editing of these projects is not supported by Automated Build Studio integrated into Microsoft Visual Studio.

Modifying Properties of Automated Build Studio Macro Operations

You can modify operation properties via Automated Build Studio’s user interface or programmatically from scripts. In most cases you will change the operation properties via the user interface. For information on how to get or set property values in scripts, see Working With Operations in Scripts.

The operation’s properties are set in the Operation Properties dialog. To call the dialog, do one of the following:

• Right-click the desired operation in your macro and then select Properties from the context menu • Double-click the operation in the Macro panel. • Select the desired operation and press Enter. • If the Show Properties dialog when adding a new item option is enabled, Automated Build

Studio automatically displays the dialog once you have added a new operation to your macro.


Getting Started 42

The dialog holds several tabbed pages. The first page holds properties common for all operations; other

pages hold properties specific to the selected operation. The common properties are: Property Description Description Description of the operation. This property has no effect on macro

execution. It is used for notes. This property is required if the Begin a progress group property is enabled.

Automated Build Studio stores and displays descriptions using regional settings that are currently selected on your computer. If the description includes non-Latin characters, for instance, characters with diacritical marks, the description may be displayed incorrectly on other computers, which regional settings differ from regional settings selected on your machine.

You can also comment the macro using the Comment operation. Enabled Specifies if the chosen operation is run when the macro is run using the

active configuration. Otherwise, the operation is excluded from macro execution.

Run submacro if operation fails Specifies the submacro which runs if an error occurs when executing the operation. You can either set the submacro specific for the operation, or use the default submacro, which is common for all operations (the latter can be set in the Macro Properties dialog). See Handling Errors in Macros.


Modifying Operation Properties 43

Stop execution if operation fails Allows you to stop execution of parent operations or the entire macro if an error occurs during the execution of the operation or its child operations. For more information on this, see Handling Errors in Macros. If the Run submacro if operation fails property is not set to None, Automated Build Studio runs the submacro first and then handles an error according to the Stop execution if operation fails property.

Unique name Identifier of the operation. This identifier is used to address the operation from scripts. See Working With Operations in Scripts for more information on this. In addition, Unique Name cannot be empty for the Submacro and Label operations, because it is used by other operations to call these operations. The Unique Name must start with a letter or an underscore character and contain only alphanumeric characters and underscores.

Begin a progress group Sets whether the operation is the first operation of a new progress group in the current macro. Progress groups let you organize your macros logically. A progress group is just a logical unit that includes several operations in the macro hierarchy, starting from the one for which this property is on. In other words, using progress groups you can divide your macros into several logical parts. For instance, if your macro is intended to build an installation, you can create one progress group for operations that prepare files for your build, another progress group for operations that compile these files, and the third for operations that compile your installation program. A progress group's name is the value of the Description property of the first operation in this group. Currently, progress groups are used to indicate the macro execution progress: when running the macro, Build Studio's status bar displays the name of the progress group that is currently being executed. Therefore, you are informed which part of your macro is currently running.

Log to summary Sets whether to collect statistics on this operation for the Summary panel. Timeout This property is common for operations that run a program (for instance,

operations of the Execute category) or that use third-party applications (for example, operations of the Compilers or Installers categories). It specifies the maximum allowed execution time (in seconds) for the operation. The timeout purpose is to stop the operation if the application which that operation has launched executes too long and probably hung: if the application execution time exceeds the timeout limit, Automated Build Studio terminates this application. You can either set the timeout specific for the operation, or use the default timeout, which is common for all operations (the latter can be set in the Macro Properties dialog). If the timeout is 0, it will be ignored (as when the Don’t check timeout option is selected). By enabling the timeout for macro operations, you can handle errors that occur during the macro run. For more information, see Handling Errors in Macros.

For information on properties that are specific to an operation, see description of the desired operation. See also List of Operations.


Getting Started 44

You can modify the common properties on the Properties page of the Operation Properties dialog. Some of the common properties are displayed as columns of the Macro panel. As for the specific properties, if the

Show Operation Details menu item is checked in the context menu or on the toolbar of the Macro panel, Automated Build Studio displays them under each operation in the Macro panel. If this menu item is unchecked, the properties are not visible. However, you can display these properties in a hint, which is available if the Show details in hint option is enabled.

Note: When editing properties, you can either enter the property value or specify a constant or a variable as a value. If you use constants or variables, you should enclose the name of this constant (or variable) in the % signs. For instance, the file_name variable should be referred to as follows:

%file_name% Otherwise, Automated Build Studio will treat the name as an ordinary string. If a property requires that its value must be saved to a variable, you should specify the variable name without % signs. For complete information on macro variables and constants, see Using Variables and Constants in Macros.

The toolbar at the top of the Operation Properties dialog holds the Previous and Next items that let you quickly switch to the properties of the operation that follows or precedes the currently selected operation in the macro.

The toolbar also holds the Run Selected Operation and Run Selected Operation with Children items that let you execute the selected operation. For more information on this, see Running Macros.

Additionally, the toolbar includes the Macro Properties button which allows you to call the Macro Properties dialog directly from the Operation Properties dialog.

Whenever you change an operation's properties using either the Operation Properties dialog or the Macro panel, you apply the changes to the active macro configuration only. See Using Macro Configurations. The Operation Properties dialog lets you temporarily switch the active configuration of the current macro without leaving the dialog. To do this, use the Configuration dropdown list box at the top of the dialog. The active configuration will include all property values of the operation that is currently available in the dialog.

After you finish editing operation properties, you can select Run | Check from the main menu of Automated Build Studio (if it is running as a standalone application) or Build Studio | Check from Visual Studio’s main menu (if Build Studio is integrated into Visual Studio .NET) to verify that the properties are set correctly. Note that this command checks the macro using the data of the active configuration only. To check the macro in a different configuration, you should first switch to that configuration. See Using Macro Configurations.

Modifying Properties of MSBuild Project Elements You modify properties of MSBuild project elements via the special Properties dialog. To call it, do any

of the following: • Right-click the desired element in your macro and then select Properties from the context menu. • Double-click the element in the Macro panel. • Select the desired element in the Macro panel and press Enter. • If the Show Properties dialog when adding a new item option is enabled, Automated Build

Studio automatically displays the dialog once you have added a new element to your MSBuild project.


Saving and Loading Macros 45

The Properties dialog displays the properties of the selected element, so the dialog’s contents depend on the selected element. For information on elements and their properties, see MSBuild Project Elements Reference in the Working With MSBuild Projects document or in on-line help.

To specify elements’ properties, you can refer to the Property, Item and Item Metadata elements of your MSBuild project as well as to MSBuild reserved properties and the operating system’s environment variables. For information on how to refer to them, see Specifying Element Properties in the Working With MSBuild Projects document or in on-line help.

Saving and Loading Macros In Build Studio running as a standalone application, to save changes made to your macro, select File |

Save from Build Studio’s main menu or press Ctrl-S (this shortcut can be changed via the Customize Keyboard dialog). To save the macro under another name, select File | Save As. In Build Studio integrated into Visual Studio .NET, you can save changes made to your macro in the same manner as you would save any other project in Visual Studio: select the File | Save <project_name> menu item or press Ctrl-S. To save the macro under another name, select File | Save <project _name> As. Automated Build Studio can save macros in one of the following formats:

Format Description .bbp The Automated Build Studio project file. Stores data in binary form. .bxp The Automated Build Studio project file. Stores data in XML format.

The MSBuild project files are stored in the XML format and typically have one of the following extensions: .proj, .msbuild, .targets and .tasks.

Note that Automated Build Studio macros cannot be saved in the MSBuild project format and vice versa (that is, conversion of these files is impossible).

To open a macro or MSBuild project that you have previously saved, select the File | Recentitem in the main menu of Automated Build Studio (if it is running as a standalone application) or the File | Open | Project item in Visual Studio’s main menu (if Build Studio is integrated into Visual Studio). This will bring up the standard Open File dialog where you can select the desired file. After you have selected the file, Automated Build Studio will replace the currently edited macro or MSBuild project with that file. To append an Automated Build Studio macro from a file to the currently open macro, use File | Append item in the main menu of Automated Build Studio (if it is running as a standalone application) or the Build Studio | Append Macro From item in Visual Studio’s main menu (if Build Studio is integrated into Visual Studio)..Operations of the chosen macro will be added to the end of the current macro. Note that you may not append a macro to the currently open macro, but run it using the Execute Macro operation.

In addition to .bbp and .bxp macro files, and MSBuild projects, Automated Build Studio can also open .vmp files. The .vmp format is used by Visual Macro Builder to store macros (The Visual Macro Builder is part of AQdevTeam Client – AutomatedQA’s bug tracking system). .vmp is an obsolete format. If you command Automated Build Studio to open a .vmp file, it will convert that file to a macro format that is currently used.

Using Macro Configurations Often when you make a build or an installation by using Automated Build Studio, you need to create

different versions of the same build (installation): for instance, a debug (checked) version, a demo version or


Getting Started 46

a release version. Typically, macros that generate these versions slightly differ from each other: just some changes in the logic, operation properties and values of constants and stored variables. For example, when using the Compile Visual C++ 6.0 Project operation you may want to enable properties that will generate debug information and disable all optimizations for the debug version, but turn on all the needed optimizations and not generate debug info for the release version. You can create an individual macro to generate each version independently, but this is not an efficient approach because in these macros you will have lots of identical parts. Of course, you could separate the reusable logic parts into submacros or external macros. But in this case, you would still have to manage several macros, which is not convenient either. Since all of these versions pertain to the same product, it would be reasonable to have a single macro that would generate all of the versions. However, this macro will inevitably have multiple conditional branches that are needed to ensure that your reusable macro parts are utilized as efficiently as possible.

Use of macro configurations allows you to create a single macro and reuse it multiple times, changing its nature by simply selecting a different configuration. A configuration includes the following:

• property values of all operations that exist in the macro; • values of all custom constants and stored variables that are defined in the macro (see Using

Variables and Constants in Macros); • the Environment attributes of all custom constants and variables (including stored variables)

that are defined in the macro.

Note: The concept of macro configurations is used for Automated Build Studio macros. It cannot be applied to MSBuild projects.

A configuration (all the settings that are unified by a configuration) is part of a macro. By default, a macro holds at least one configuration. Each macro can have any number of configurations. Therefore, if a macro has N configurations, this means that the macro has N sets of operation properties and variable (constant) values and attributes. Using multiple configurations lets you have a single logic for all datasets. In our example with multiple build or installation versions, you can create as many configurations as the number of versions you want to get while the macro logic and the set of constants and variables will be the same for all versions. This is like passing different parameters to a function to get different results.

As it was said above, the set of operations and their hierarchy as well as the set of variables and custom constants in a macro is identical for all configurations. Therefore, if you add an operation to or remove an operation from the macro in one configuration, this operation will appear or disappear in all the other configurations as well. Likewise, if you add a variable or a custom constant to or remove it from the macro in one configuration, this constant (variable) will also appear or disappear in all the other configurations. Therefore, you can also compare the macro with the class declaration, while each configuration resembles a class instance: a copy of the class structure populated with unique data.


Using Macro Configurations 47

As a result, you create the operation hierarchy and the set of variables and custom constants only once

and then, using individual configurations, work with data specific to a particular configuration. Using operation properties you can even change the operation hierarchy to some extent, without adding

or removing operations. How is this possible? You can use the Enabled property to simply switch on or off a definite operation in the operation flow. For instance, in the Debug configuration you may need a specific check of assertions, which is not required in the Release configuration; so you can enable the corresponding operation branch in the Debug configuration and disable it in Release. To see in which configurations the given operation is enabled, refer to the Enabled in Configurations column that is displayed in the Macro panel. If the operation is enabled in all the configurations of the current macro, this column shows <All>.

If you need to set the needed value to a variable in all configurations, you can use either Set\Reset Variable Value, or Script operation and enable it in all configurations as described above. For stored variables, you can set their initial value in all configurations via the Stored Variables dialog. Alternatively, you can use the Set\Reset Variable Value operation that is enabled in at least one configuration and whose Set Value for All Configurations property is on. This is typically used to change the value of a stored variable in all configurations at once.

Automated Build Studio Standalone To manage configurations that belong to the given macro, use the Edit Macro Configurations dialog. To

call it, press the Edit Configurations button on the Configurations toolbar. By default, a newly created macro holds one configuration called Release. The dialog lets you create new configurations as well as rename and delete existing ones. You cannot delete all the configurations from the macro; at least one configuration must always be present in the macro. Each configuration must have a unique name within the macro. When adding a new configuration to the macro (press Add in the Edit Macro Configurations dialog), you can copy all of the data of an existing configuration to the new one. This will save you from having to populating all the necessary properties as well as values and attributes of constants and variables in the new configuration if these two configurations do not differ too much. To do this, in the Copy data from box of the New Configuration dialog, select the desired configuration whose data needs to be copied. If you select <None>, no properties of the new configuration will be specified or set to their default values.

All of the configurations that belong to the current macro are displayed in the Select Active Configuration dropdown list box on the Configurations toolbar.


Getting Started 48

When you select a configuration in this box, you make the chosen configuration the active configuration

in the macro. This means that all of the changes you made in the operation properties will be applied to the active configuration only. When you save the macro to a file, the active configuration is also saved there. A similar dropdown list box, Configuration, is available in the Operation Properties, Constants, Variables and Stored Variables dialogs, in order to let you switch between configurations without leaving the dialog. Note however that the selection of the active configuration you make in any of these dialogs is temporary; it only has effect while the dialog is open. In other words, if using the dialog you switch the active configuration, when closing the dialog the active configuration selection will return to the configuration that was active before calling the dialog.

If you want to see if the properties of the given operation have different or identical values in different configurations of the current macro, see if there is a tick in the Different Configuration Settings column of the Macro panel. As a result, you can quickly see which of your operations have configuration specific property values and which operations have the same property values in all the configurations.

The <All Configurations> item that is available in the Select Active Configuration or Configuration box lets you apply changes you made in the operation properties to all the available configurations at once. For instance, if you want to set the unique name of the operation, which should be the same in all the configurations, you can enter the desired name directly in the Macro panel grid or using the Operation Properties dialog. At that, only the properties whose values you are modifying when <All Configurations> is selected will be applied to all configurations; the same concerns values and attributes of constants and variables. To illustrate this, imagine that you have the Get Latest Version From VSS operation where the property that specifies location of the working folder (Working Folder) has different values for the Release and Debug configurations, while the other properties (Login, Password, etc.) have the same values in all configurations. If you select <All Configurations>, change the value of the Login property in this operation and then revert to a named configuration, only this property will be changed in all configurations. The other properties will stay untouched. Therefore, the Working Folder property will still have different values in different configurations.

Automated Build Studio Integrated Into Visual Studio .NET In Visual Studio, there are two types of configurations: project configurations and solution build

configurations. A project configuration is a set of project properties that are specific for a particular build and possibly platform. Since an Automated Build Studio macro is a special case of a Visual Studio project, a macro configuration is a project configuration too. A solution build configuration determines which configurations of the projects that are included in the solution should be used when building the entire solution. A solution's build configuration holds only references to configurations of its projects, while configuration settings themselves are stored within projects.

To manage configurations that belong to the given macro, use Visual Studio's Configuration Manager dialog. To call it, select Configuration Manager from the Build menu. Alternatively, you can select Configuration Manager from the Solution Configurations dropdown list box that is displayed on the Standard toolbar.



The Configuration Manager dialog lists all the projects that are included in the current solution. The

Active Solution Configuration dropdown list box displays all the build configurations stored in the solution. The configuration that is currently selected in the list is the active build configuration of the given solution. This is the configuration that will be used when you build or re-build the solution. You can also select the active solution build configuration from the Solution Configurations dropdown list box on the Standard toolbar.

For each project listed in the Solution Manager dialog, you can specify the active project configuration.

To do this, locate the desired project in the Configuration column, press the down arrow button and in the resulting dropdown list box select the needed configuration. The active project configuration is the configuration that will be used when you run or build the project. You can also specify the platform for which the project should be built and designate whether to build or deploy the project when using the given solution configuration. For Automated Build Studio macros, the active project configuration is the active macro configuration. This means that all the changes you make in the operation properties will be applied to the active macro configuration only. The active macro configuration also determines which dataset will be used in the given macro run. Macros cannot be built, they can only be run. That's why there is no need to specify the target platform for the macro configuration.


Getting Started 50

When you save the macro to a file, the active macro configuration is also saved there. The Operation

Properties, Constants, Variables and Stored Variables dialogs include the Configuration dropdown list box which lets you switch between macro configurations without leaving the dialog. Note however that the selection of the active macro configuration you make in any of these dialogs is temporary; it has effect only while the dialog is open. In other words, if using the dialog you switch the active macro configuration, when closing the dialog the active macro configuration selection will return to the macro configuration which was active before calling the dialog.

If you want to learn whether the properties of the given operation has different or identical values in different configurations of the current macro, check whether there is a tick in the Different Configuration Settings column of the Macro panel. As a result, you can quickly see which of your operations have configuration specific property values and which operations have the same property values in all the configurations.

The <All Configurations> item that is available in the Configuration box lets you apply changes you made in the operation properties to all the available macro configurations at once. For instance, if you want to set the unique name of the operation, which should be the same in all the macro configurations, you can enter the desired name directly in the Macro panel grid or using the Operation Properties dialog. At that, only the properties whose values you are modifying when <All Configurations> is selected will be applied to all macro configurations; the same concerns values and attributes of constants and variables. To illustrate these words, imagine that you have the Get Latest Version From VSS operation where the property that specifies location of the working folder (Working Folder) has different values for the Release and Debug configurations, while the other properties (Login, Password, etc.) have the same values in all macro configurations. If you select <All Configurations>, change the value of the Login property in this operation and then revert to a named configuration, only this property will be changed in all macro configurations. The other properties will stay untouched; thus, the Working Folder property will still have different values in different macro configurations.

By default, a newly created solution holds only one solution build configuration whose name is Release. To create a new solution build configuration, open the Configuration Manager dialog and select <New...>



from the Active Solution Configuration dropdown list box. This will call the New Solution Configuration dialog, where you can specify the configuration name. In addition, you can set whether to copy all data of an existing solution configuration to the new one. To do this, in the Copy Settings from box of the New Solution Configuration dialog, select the desired configuration whose data should be copied. If you select <Empty>, all properties of the new configuration will be set to their default values. If you enable Also create new project configuration(s), the new configuration under the same name will become available for all projects that belong to the given solution. Otherwise, this configuration will be added to the solution only.

To rename or remove an existing solution configuration, select <Edit...> from the Active Solution

Configuration dropdown list box of the Configuration Manager dialog. This will call the Edit Solution Configurations dialog. In the dialog, select the configuration you want to rename or delete and press the Rename or Remove button correspondingly. Each configuration must have a unique name within the solution. You cannot delete all the configurations from the solution; at least one configuration must always be present in the solution.

By default, a newly created macro holds the only macro configuration whose name is Release. To create

a new macro configuration, open the Configuration Manager dialog, locate the desired macro in the Configuration column, press the down arrow button and select <New...> from the subsequent dropdown list box. This will call the New Project Configuration dialog, where you can specify the configuration name. In addition, you can set whether to copy all data of an existing macro configuration to the new one. This will save you populating all the necessary properties as well as values and attributes of constants and variables in the new configuration if these two configurations do not differ seriously. To do this, in the Copy Settings from box of the New Project Configuration dialog, select the desired configuration whose data should be copied. If you select <Empty>, all properties of the new macro configuration will be not specified or set to


Getting Started 52

their default values. If you enable Also create new solution configuration(s), the new configuration under the same name will become available for the solution to which the given macro belongs. Otherwise, this configuration will be added to the macro only.

To rename of remove an existing macro configuration, open the Configuration Manager dialog, locate

the desired macro in the Configuration column, press the down arrow button and select <Edit...> from the subsequent dropdown list box. This will call the Edit Project Configurations dialog. In the dialog, select the configuration you want to rename or delete and press the Rename or Remove button correspondingly. Each configuration must have a unique name within the macro. You cannot delete all the configurations from the macro; at least one configuration must always be present in the macro.

Running a Macro with the Needed Configuration When you run the macro or some of its operations, or check the macro, you only run or check the macro

in the active macro configuration. Therefore, if you need to run the macro in another configuration, first make this configuration active. However, if you have a long list of configurations within a macro, running them one by one is tedious. As you may recall, the idea of integrating multiple configurations within a macro implies that you must have the capability to run the macro in several configurations quickly. Of course, you can do this in Automated Build Studio: simply select Batch Run from Build Studio’s Run menu or from Visual Studio’s Build Studio menu and in the resulting Edit Batch Run dialog designate in which configurations you want to run the macro.

Among the system constants that Build Studio adds to the system (see System Constants Dialog in on-line help), there are the RUNCONFIGURATIONCOUNT, RUNNINGCONFIGURATIONINDEX and RUNNINGCONFIGURATIONNAME constants. When running a macro, Build Studio dynamically changes


Running Macros 53

values of these constants. The RUNCONFIGURATIONCOUNT constant will hold the total number of configurations for which the macro has been run, while the RUNNINGCONFIGURATIONNAME and RUNNINGCONFIGURATIONINDEX constants will correspondingly hold the name and zero-based index of the configuration for which the macro is currently running.

Running Macros Once you have created a macro, you can run it:

• You can launch a macro at certain points in time by passing the macro name to Automated Build Studio via the command line. See Scheduling Macro Runs for more information.

• You can run your macro using the Automated Macro Player - a command-line utility that was specifically designed for running macros. See Command-Line Arguments.

• You can run your macro right in Automated Build Studio (if it is running as a standalone application).

• You can run your macro right in Visual Studio .NET (if Build Studio is integrated into it). This topic describes how to run a macro from Automated Build Studio or from Visual Studio .NET.

Automated Build Studio does not support running and debugging MSBuild projects. You can execute MSBuild projects from Microsoft Visual Studio Team System, or using the MSBuildoperation from your Automated Build Studio macro.

Before running your macro, you may need to specify the options that affect the whole macro run. To modify them, select File | Properties from the main menu of Automated Build Studio (if it is running as a standalone application) or right-click the Build Studio project node in the Solution Explorer and select Properties from the context menu (if Build Studio is integrated into Visual Studio). This will open the Macro Properties dialog. The options are on the General tabbed page of the dialog:

• Common Timeout - Specifies the timeout (in seconds) for operations that run external applications. An example of such operations is Execute Program, Pack Files with WinRAR or Compile Microsoft Visual C++ 6.0. If an operation is executed longer than the specified timeout, Automated Build Studio will close the application, which that operation launched, and stop the macro execution.

• Run submacro if macro fails - Specifies a submacro that runs if an error occurs during the macro execution.

For more information on these options, see Macro Properties Dialog in on-line help. You can run your macro in Automated Build Studio or in Visual Studio in one of the following manners:

Automated Build Studio standalone:

• Press Run on the Standard toolbar.

• Select Run from the Run menu.

• Right-click within the Macro panel and select Run from the context menu. • Press F5 (the shortcut for running macros can be changed via the Customize Keyboard dialog).

Automated Build Studio integrated into Visual Studio .NET:

• Press Run on the Macro panel toolbar.

• Select Run from the Build Studio menu.


Getting Started 54

After that Automated Build Studio will start executing the macro. Note that it will execute only those operations that are checked in the Macro panel. Unchecked operations will not be executed. If you uncheck a parent operation, its child operations will not be executed either.

If the Highlight Operation option of the Macro panel is enabled, the operation that is being executed at that moment will be selected in the Macro panel.

Sometimes you may want to run only a part of macro rather that the whole macro. This may be useful, for instance, for testing or debugging purposes.

To run your macro from the selected operation to the end of the macro, select Run From Selected from the context menu of the Macro panel, from Build Studio’s Run menu or from Visual Studio’s Macro panel toolbar, or press Ctrl-F5 (this shortcut can be changed with the Customize Keyboard dialog). We would like to note once again, that Automated Build Studio will run only checked operations. Unchecked operations will be skipped. If the selected operation has a parent operation, you can run the macro only if the parent is either a Group or If … Then operation.

You can also run only the operation currently selected in the Macro panel: choose Run Selected Operation from the context menu, from Build Studio’s Run menu or from Visual Studio’s Macro panel toolbar, or press Alt-F5 (this shortcut can be changed with the Customize Keyboard dialog). If in addition to the selected operation itself, you also would like to run its checked child operations, press Shift-F5 or choose

Run Selected Operation with Children from the context menu, from Build Studio’s Run menu or from Visual Studio’s Macro panel toolbar. Note that these commands will execute the selected operation even if it is unchecked.

You can also run the selected operation using the Run Selected Operation and Run Selected Operation with Children items on the toolbar at the top of the Operation Properties dialog.

Note: Note that if you run a macro or its operations, they will use the data of the active configuration only. To run the macro or its operations in a different configuration, you should switch to that configuration first. To run the macro in several configurations, select Batch Run from Build Studio’s Run menu or Visual Studio’s Automated Build Studio toolbar or Build Studio menu, and in the subsequent Edit Batch Run dialog, select the configurations that should be used during the run. See Using Macro Configurations.

To pause the macro execution, select Pause from Build Studio’s Standard toolbar or Run menu or from Visual Studio’s Macro panel toolbar or Build Studio menu. Pressing Stop will stop the macro execution. If you stop the macro run by pressing this button, the Summary panel "assumes" that the run is successful.

You can stop execution from the macro. To do this either use the Stop Macro Execution operation or call the ABSUtils.AbortMacroExecution function in a script.

Automated Build Studio logs each macro run and displays the results in the Log and Summary panels. For more information on this, see Logging Macro Runs.

Logging Macro Runs Automated Build Studio generates full-detail logs of macro runs. These logs help you isolate the errors

that might arise during the macro execution.

Note: The logging concept is only used for macros. It does not work for MSBuild projects since these projects cannot be launched from within Automated Build Studio’s IDE.


Analyzing Results of Macro Runs 55

By default, when Automated Build Studio is executing a macro, it shows the name of each operation being executed in the Log panel. If an operation has child operations, they are logged as child nodes of their parent operation’s node. If an operation fails to execute, Automated Build Studio will log information about the error that has occurred.

You can disable the default logging, by adding the Disable Logging operation to your macro. A macro will not post messages to the log after it executed this operation. To enable the logging, use the Enable Logging operation. Note that error messages are posted to the Log panel even if the logging is disabled.

You can post your custom messages to the log. To do this, use the Log Message operation. The operation’s properties let you specify what kind of message you would like to post: error, warning or an informative message (default).

You can also post messages from the scripts. To do this, use methods of the Log object: [VBScript]

Log.Message "Message text" ' Posts an informative message

Log.Warning "Warning text" ' Posts a warning

Log.Error "Error text" ' Posts an error

[JScript]

Log.Message("Message text"); // Posts an informative message

Log.Warning("Warning text"); // Posts a warning

Log.Error("Error text"); // Posts an error

[DelphiScript]

Log.Message('Message text'); // Posts an informative message

Log.Warning('Warning text'); // Posts a warning

Log.Error('Error text'); // Posts an error

To save the currently displayed log to a text, HTML or XML file, select Export from the context menu and specify the name, location and format of the resulting file.

Build Studio can also post messages about execution of particular operations to the Summary panel: simply enable the Log to summary property for all the operations you want to trace. The panel is used to compare logs. For this purpose, it displays the logs of two macro runs (the current run and the previous run during which the macro didn’t fail) and displays the differences between the two logs. In addition, this panel always logs all the errors and warnings that occur during the macro run. This lets you quickly find the cause of the problem.

You can save the contents of the Summary panel to an HTML file like you do this in the Log panel. For this purpose, select Export from the context menu or from the Summary panel’s toolbar and specify the name and location of the resulting file. You can also configure whether the file will include the log of the current run with or without the log of the previous successful run.

Analyzing Results of Macro Runs When you run a macro in Automated Build Studio, the results of the macro run are shown in the Log

panel at runtime and after the run is over. The Number of recent logs to keep option determines how many logs of the recent macro runs (including

the latest one) the Log panel stores. These logs are displayed in the Recent Logs list, which is displayed when the Show History button is pressed on the Log toolbar the Log panel toolbar. Once the Recent


Getting Started 56

Logs list is displayed, you can switch between different logs. To load the contents of the focused log to the panel, select Load from the context menu, or simply double-click the log. Other items of the context menu let you rename the focused log (Rename), delete the selected logs (Remove) as well as remove all the logs at once (the Clear menu item). If you hide the Recent Logs list, the Log panel will display the log you have loaded last.

You can save the currently displayed log to a text, HTML or XML file. To do this, select Export from the context menu and in the resulting dialog specify where to save the export file, under what name and in which format.

By default, the Log panel shows all messages that were posted to the log during the given run. To view only messages of certain categories, use the Message Filter dialog. To call it, select Message Filter from the context menu or from the Log toolbar the Log panel toolbar.

Using the Log Navigation toolbar the Log panel toolbar you can quickly locate messages of a particular type in the Log panel. This can be useful when the macro is complex and its log is extremely large. To do this, first select the desired type of messages in the Select Message dropdown list box on the toolbar (you can select among errors, warnings, informative messages or messages from operations of a particular type).

Then, using the Go to First Message, Go to Previous Message, Go to Next Message and

Go to Last Message buttons on the toolbar, navigate through messages of the chosen type until you find the message you need.

Instead of investigating the contents of one log in the Log panel you can use a different approach when analyzing macro runs. To do this, switch to the Summary panel which displays logs on two different runs at the same time. The first run is the current run where the macro might fail or an operation might be executed with an error or warning. The second run displayed is the previous run of the same macro where there were no failures. Build Studio automatically compares the contents of the two logs and highlights the differences between them in the Summary panel. This lets you quickly find out why something went wrong in the macro.

Getting Started – Further Steps

Sending Notifications Quite often it is desirable to get notification of whether a macro run was successful or not. Notifications

are especially useful if a macro is run automatically as a scheduled task. Automated Build Studio includes three operations that can be used to send notifications: Send Message

via ICQ, Send Message via Windows Messenger and Send E-mail. Note that since Automated Build Studio can run external programs, you can also use these programs to send notifications, for instance, you can use the Execute DOS Command or Execute Program operations to send notifications via net send:


Sending Notifications 57

To generate notifications, add the “send” operations at the end of you macro or insert them into a group

of operations that handle errors. Note that you can attach macro execution logs to your e-mail messages in order to make notifications

more informative. To do this: • Save the execution log to a file using the Export Log or Export Errors From Log operation. To

save the contents of the Summary panel to a file, use the Export Summary operation. • Set up properties of the Send E-mail operation, so that the file is attached to the e-mail message

to be sent. Automated Build Studio includes a sample macro that demonstrates how you can send notification

messages: <Automated Build Studio>\Samples\Macros\Notifications\Notifications.bxp

Exporting Results of Macro Runs After running a macro, you can export the macro run results to a file. You can export the contents of both

Log or Summary panels. To do this: • Open the Log or Summary panel. • Right-click somewhere within the panel and choose Export from the context menu. • In the ensuing Save File dialog, specify the file's location and name. • If you export the contents of the Summary panel, the dialog also let you specify whether

Automated Build Studio should export results of the last run or results of the last run along with results of the last successful run.

• After you specified the file name, location and export type, press Save. Built Studio will save results to the specified file.

Note: Contents of the Log panel can be exported to a TXT, HTML or XML file. Contents of the Summary panel can be exported to an HTML file only.

You can also export the log and summary data during the macro run. To do this, use the Export Log, Export Errors from Log and Export Summary operations.

• The Export Log and Export Errors from Log operations save the contents of the Log panel to a file or variable specified by the operations' Export to property. The difference between these operations is that Export Log stores all messages posted to the log along with their execution time, while Export Errors From Log only stores information about errors. Both operations export only those messages that were posted before these operations are executed. You can


Getting Started 58

export either the entire log or part of the log. Exporting the entire log does not need special preparation. If you want to export part of the log, follow these steps: Mark the part of the log you want to export by adding the Set Log Marker operation before

and after the desired operations in the macro. Open the Operation Properties dialog for the Export Log (or Export Errors From Log)

operation and specify the names of the marker operations in the From position and To position properties of the Export Log (or Export Errors From Log) operation. By default, these properties are empty and the operation will export the entire log. If your macro sets the same marker several times (this is possible, if you set the marker in a loop or execute the Set Log Marker operation from a script), Automated Build Studio will use the last marker for the export.

• The Export Summary operation saves the contents of the Summary panel to a variable or a file specified by the operation's Export to operation property. Using the operation's Mode property you can specify whether Build Studio should export the summary of the current run with or without the summary of the last successful run.

All three operations can save results to the file or variable. After you save the log or summary contents, you can, for example, include them into a notification message sent by your macro: to do this, include the variable in the message body or attach the file to the message (see Sending Notifications).

Handling Errors in Macros During the macro run an error may occur. For instance, the Script operation may fail to execute

successfully because of an error in the script, or the Copy File(s) operation may fail because of an invalid file path specified in operation properties.

The way Automated Build Studio processes errors during the macro run depends on the properties of the macro operations and whether the macro contains error-handling operations. This topic describes how Automated Build Studio handles errors by default and explains how you can handle errors in a custom way:

Common Error-Handling Mechanism If an error occurs during the macro run, Automated Build Studio posts an error message to the Log

panel. Errors are posted to the log automatically. They are posted even if the logging was disabled by the Disable Logging operation.

If an error occurs in a child operation, Build Studio “thinks” that the parent operations also failed to execute successfully and posts an error message for the parent operations too. Then it walks up the operation tree and posts an error message for the grandparent operation, great-grandparent, etc. until it reaches the top-level operation.

Automated Build Studio continues or stops running the macro according to the state of the Stop execution if operation fails property of the operation that failed (This is a common property that each operation contains. You can modify it on the Properties page of the Operation Properties dialog).

Note: If you use an error-handling sub-macro (see below), it will be run before Build Studio analyzes the Stop execution if operation fails property.

Automated Build Studio handles errors in the following way: 1. It checks the value of the Stop execution if operation fails property of the current operation:

• If this property is enabled, Automated Build Studio reports that the current operation failed to execute correctly. Then it returns control to the parent operation of the current operation (step 2).



• If the property is disabled, Automated Build Studio reports that the current operation failed to execute successfully and then continues running the macro: it starts executing the next operation in the operation tree.

2. Automated Build Studio checks the value of the Stop execution… property of the parent operation. • If the property is enabled, Build Studio reports that the parent operation failed to execute

correctly and control goes up to the parent operation of the current parent operation (step 3). • If the property is disabled, Automated Build Studio reports that the current operation failed and

switches to the operation that follows the current parent operation in the operation tree. 3. The process continues until Automated Build Studio reaches the top-level operation. If the Stop

execution if operation fails property of this top-level operation is enabled, Automated Build Studio stops macro execution. Otherwise, it continues running the macro: it starts executing the operation that follows the top-level operation in your macro.

The following is an example for the described behavior. Suppose you have the following hierarchy of operations:

If the Delete File(s) operation fails, Automated Build Studio will post an error message to the log and

then it will switch to the If … Then operation. Since the Stop execution if operation fails property of this operation is on, Build Studio will also report

that the If … Then operation failed and will switch control to the For Loop operation. The Stop execution if operation fails property of the For Loop operation is disabled, so Automated Build

Studio will post a message to the log reporting that this operation failed to execute correctly and then will continue running the macro: it will start executing the operation that follows For Loop in the operation tree (in our example, this is the second Log Message operation).

Checking if Previous Operations Succeed or Fail If an error occurred and the macro was not stopped, Build Studio runs other operations of the macro in

the usual order. However, if these operations depend on the operation that failed (for instance, if they use data output of that operation) they may fail to execute successfully themselves.

To see if the previous operation was executed successfully, use the If Previous Operation Fails or If Previous Operation Succeeds operation. It checks the result of the previous operation and if that operation failed, it executes child operations. These child operations may perform various finalization actions and send a notification about the error to the macro developer via e-mail. You can also perform finalization actions and send a notification from an error-handling sub-macro (see below).


Getting Started 60

Using Try...Catch...Finally Blocks Automated Build Studio includes the Try, Catch and Finally operations that let you organize exception

handling blocks similar to the try...catch...finally blocks in C++ or Visual Basic code. Operations that can potentially produce an error should be placed under the Try operation. The Catch operation is used to specify operations that handle errors that can occur in the Try block. For example, the Catch block can contain operations that send notifications about an error to developers. The Finally operation is executed regardless of whether an error occurs within the Try block or not. Under the Finally operation, you would usually place clean-up operations, for example, operations that close a connection to an FTP server or remove temporary folders.

The Try operation must be followed by the Catch or Finally (or both) operations on the same level. This means that the following combinations are possible: Try...Catch, Try...Finally and Try...Catch...Finally. If a child operation of the Try operation raises an error, Automated Build Studio posts an error message to the log and proceeds to the next sibling of the Try operation (it can be either Catch or Finally). If the macro does not contain the Catch operation, further error processing depends on the Stop execution if operation fails property value of the Try operation (see the previous section).

Note: If an operation that has raised an error uses an error-handling sub-macro (see below), it is run before Automated Build Studio executes the Catch or Finally operations.

The image below demonstrates an example of using the Try, Catch and Finally operations in macros:

The execution flow of this macro depends on whether the operations under the Try operation execute

successfully or not: Try operation succeed, Automated Build Studio skips the Catch

peration of Try raises an error:

y. ild Export Errors From Log and

• If all child operations of the operation and proceeds to the Finally operation. That is, it will execute the Remove Directory operation.

• If a child o Automated Build Studio posts an error to the log and reports that the Try operation failed

to execute correctl Then the control goes to the Catch operation and its ch

Send E-mail operations.



After the Catch operation children have been executed, Automated Build Studio proceeds to the Finally operation.

It is ls blocks, so that you can organize sophisticated multi-level hand gthe error will be n

Running S -Each operation an error occurs. These

submacros can, developer via e- i

You can either specify an error-handling submacro for each operation, or use one error-handling sub

cify the que name of the desired submacro in the appropriate box.

main menu or select Build Studio | Options | Properties from Visual Studio’s main menu. This will call the Macro Properties dialog.

the General page, enable the Run submacro if fails option and specify the e of the desired submacro in the appropriate edit box.

Properties dialog for the desired operation, switch to the Properties page and enable the Global submacro option.

Simulating Errors During Macro Runs To check if the error-handling operations function properly (for example, for debugging purposes), you

may ne You can do this by submitting invalid parameters for the operatio g file name to the Execute Program operation. To make the

a o possible to create nested Try...Catch...Finally lin of exceptions in your macros. If a nested Try operation does not have a Catch operation, ha dled in an upper-level Catch block.

ub macros on Errors contains properties that specify submacros to be executed when

for example, export errors or the whole log to a file and send this file with a notification to a ma l.

macro common for all operations: • To specify an error-handling submacro for a single operation:

Right-click that operation in the Macro panel and select Properties from the context menu. This will call the Operation Properties dialog.

Switch to the Properties page, enable the Selected submacro option and speuni

• To specify a common error-handling submacro: Select File | Macro Properties from Build Studio’s

Switch to unique nam

Then open the Operation

ed to simulate an error in your macro. n. For instance, you can specify a non-existin

Script operation fail, you can throw an exception within the script code (see the example below). [VBScript] Sub Main Err.Description = "Error description" Err.Raise -1 End Sub

[JScript] function Main() { throw "Error description"; }

[DelphiScript] procedure Main; begin raise('Error description'); end;


Getting Started 62

You can also simulate failing a macro by using the Stop Macro Execution operation or by calling the ABSUt swill caus operatio w

(e.g. Ex cthat has bee . If the applicat successfully is specified by the operation properties (see above). An exception are ope o even if they are ter

You acommon for all operations.

a single operation:

in menu or select Build Studio | Options

the Macro Properties dialog. d timeout value in the Common timeout box.

Whe a bout this. To make the notification message more in m ild Studio includes two operations, Export Errors Fro r to a variable. The difference between these va b s only error messages while the second saves the whole log. Another operation, e. After you rm the message body. To send a message, use the Send E-mail operation.

ted Build Studio demonstrate how you can handle errors in the

uring each successive build session. In gen

il .AbortMacroExecution function from a script. Note however, that since both approaches e unconditional macro termination, the error-handling operations as well as the Finalization

n ill not will not be executed.

ing Timeout for Operations SpecifyOperations that run programs (e.g. Execute Program) and operations that use third-party applications

tra t Public Key) have the Timeout property. The purpose of this property is to close the application n launches by an operation if that application executes too long and is probably frozen

ion is closed due to the timeout, Automated Build Studio “thinks” that the operation failed to execute and processes the error as it

rati ns of the Interactive category - Automated Build Studio counts them as successfully executedminated after a timeout.

c n specify a timeout for every single operation that has the Timeout property or use the timeout

To specify the timeout for • Right-click that operation in the Macro panel and select Properties from context menu. This will

call the Operation Properties dialog. • Switch to the Properties page, choose the Set timeout for this operation option and then

specify the timeout value in the appropriate edit box. To specify the timeout common for all macro operations:

• Select File | Macro Properties from Build Studio’s ma| Properties from Visual Studio’s main menu. This will call the Macro Properties dialog.

• Select Build Studio | Options | Properties from the main menu of Visual Studio. This will call

• Switch to the General page and specify the desire• Then call the Operation Properties dialog for each desired operation, switch to the Properties

page and enable the Use common timeout option.

Exporting Error Logs n macro run fails, you may want to notify co-workers a

for ative, you can attach an error log to it. Automated Bum Log and Export Log, that can save the log to a file o

ria les is that the first operation saveExport Summary, can save the two logs displayed in the Summary panel to a fil

save the log you can attach the resultant file to a message or use the resultant variable to fo

Sample macros that are shipped with AutomaAutomated Build Studio macros.

Incrementing the Build Version Number The key point of incrementing the build version number of your product is to keep the current number

somewhere and to get the version number of the previous build deral, the process of incrementing the build version number consists of the following steps:

• Loading the version number into a macro variable.



• Specifying the version number for project modules. • Incrementing the version number stored in the variable. • Saving the new version number.

The sections below provide detailed information on implementing each step in your build macro.

you can read the version number from the file into a macro variable. Alternatively, you can read each version number part (major version number, minor version number, release vers o read the text file contents, you can use the Read Fro

store your build version number in one or several stored variables (these variables preserv emacro r tvariable in athe resultindialog. In m

SpecifyThere a

project procompilationnot dep

SpecifyThe pla

on the comp

version and file version as well as the product version. To set the

• c 6.0 projects, the version number is also part of the project properties. To set the version number in your macro, use the Version Number property on the Make property page of

called for the Compile Visual Basic 6.0 Project operation. This

Choosing the Version Number Source We recommend that you keep the current version number in an external file. This can be a sample INI

file, or a text file, in which individual parts of the version number are separated with commas or new line (CRLF) characters. At run time,

ion and build version) into an individual variable. Tm File operation, to read INI files - the Get INI Value operation. Alternatively, you can

e th ir current values after the macro run). However, this approach is not as safe because if your ese s the value of the stored variable somehow, you will lose your version number. To create a stored

macro, select Variables | Stored Variables from Automated Build Studio’s main menu and use g Stored Variables dialog. You can set the initial value of the stored variable directly in the acros, you can work with stored variables like you would with ordinary variables.

ing Product Build Version re two ways to specify the version number for the project being built - you can either modify the perties before compilation, or you can set the version number for each built module after . The former approach is compiler-specific (see below). The latter approach is universal and does

end on the compiler used.

ing Version Number in Project Properties ce where the current build version number is stored within the project you are building depends iler you use:

• In Delphi and C++Builder projects, the version number is part of project options. You can separately set the moduleneeded version number in your macro, you can use the Module version number, FileVersion or ProductVersion property that resides on the Version Info property page of the Operation Properties dialog called for the corresponding Compile operation. For instance, if you have the VER_MAJOR, VER_MINOR, VER_RELEASE and VER_BUILD variables that hold the corresponding version number parts, you can set the %VER_MAJOR%, %VER_MINOR%, %VER_RELEASE% and %VER_BUILD% values to the Major version, Minor version, Release and Build properties correspondingly (they are parts of the Module version number property). See the sample macro <Automated Build Studio>\Samples\Macros\CompileDelphiProject\CompileDelphiProject.bxp. In Visual Basi

the Operation Properties dialog property includes three subproperties used to keep individual parts of the version number (Major, Minor and Revision). You can populate them using the way described above.

Note, that you can also get and set the version-related properties of the Compile operations via script (see Working With Operations In Scripts).

• In Visual C++ 6.0 projects, as well as in .NET-connected projects, the version number is kept in a resource file that is part of the project. To learn how to generate such a file, see the sample


Getting Started 64

macro <Automated Build Studio>\Samples\Macros\CompileCPPProject\CompileCPPProject.bxp. In short, the technique is as follows. If you have the VER_MAJOR, VER_MINOR, VER_RELEASE and VER_BUILD variables that hold the corresponding version number parts, you can post the #define directives that define constants with the names and values of these variables to a text file. Next, you can concatenate these constants into the integrated version number of the file or

umber is to use the Set File Version Info operation after the

nd File Rev product version - the Major Product Version, Minor Product Version, Pro Product Version keys. To specify the value for a key, check this key in the

%VER_REVISION%values to the Major File Version, Min

ion Info operation on each of them.

Sav gIf you s ying the version number you should

write it thINI file n

If you variables arthe Stored V cro file, so you should save the a

ScheduOnce you h a

the common tasks for m perform this task in any

of the product. Finally, you can specify an appropriate version number constant in the project’s resource file.

Using the Set File Version Operation An alternative way to specify the build version nCompile operation. This way, you can set the version number for one or multiple built modules right after

compilation, without modifying project settings. You can specify the module version and product version separately: to set the module version use the Major File Version, Minor File Version, File Build a

ision, File Version keys; to set theduct Build, Product Revision and list and enter the desired value in the Value field. For example, if you have the VER_MAJOR, VER_MINOR,

VER_BUILD and VER_REVISION variables that hold the corresponding version number parts, you can set the %VER_MAJOR%, %VER_MINOR%, %VER_BUILD% and

or File Version, File Build and File Revision keys and the %VER_MAJOR%.%VER_MINOR%.%VER_BUILD%.%VER_REVISION% value to the File Version key.

If you need to modify the version information for multiple files (for example, all product modules), you can use the File Enumerator operation to iterate through the desired files and execute the Set File Vers

Incrementing the Version Number Value After setting the product build version, your macro should increment values of variables that hold

version number parts. For this purpose, you can use the Script or Set/Reset Variable Value operation.

in the Version Number tore the version number in an external file, then after modif

to at file. For example, you can write to a text file using the Write to File operation, or modify the co tents using the Set INI Value operation.

use stored variables, you do not need to perform any additional actions - the values of these e automatically saved between macro runs. Note that if the Store values in separate file option in ariables dialog is unchecked, values of stored variables are kept in the ma

m cro after its execution is finished, otherwise changes made to the stored variables will be lost.

ling Macro Runs ave cre ted a macro and verified its functions properly, you can use it in your work. One of

acros is running at certain point in time, for example, every day at 8:00 p.m. You canof the following ways:

• You can run Automated Build Studio using any scheduling program and pass the appropriate command-line arguments to it (see Command-Line Arguments). For instance, you can run Automated Build Studio using Windows Scheduling Tasks.

• You can schedule macro runs on local or network computers using the Automated Build Studio Service. With the Edit Tasks dialog, you can configure tasks that this service will perform. Each task runs a macro. A task can be triggered at the specified time or by an event like changing files



of a project in a Visual SourceSafe repository. The latter lets you implement the continuous integration strategy in your projects. See Continuous Integration Support.

• You can schedule macro runs using the built-in Task Scheduler of Automated Build Studio. This Task Scheduler is similar to the Windows Scheduling Tasks component, but offers an extra useful feature: it lets you schedule macro runs on other computers in the local network.

Note: The Task Scheduler uses the Windows Scheduling Tasks component. Therefore, of the operating system

The resbefore we ng either Automa line res cline argume uires less memoryof macro ex our macro. If the m rcause of the your macro was executed by the Macro Player and if you wanted to obtain a log in case of an error, you should add some operations to the macro that will handle the error and export the log to a file. Later, you'll be able to analyze this file to find the cause ofcertain that

To schedule a macro run using the built-in Task Scheduler, follow these steps: • tomated Build Studio needs to know the macro file name. Therefore,

Ma heduled.

•

to use the Task Scheduler, you must have that component installed on your computer.

t of this topic explains how you can schedule macro runs using the built-in Task Scheduler. But describe how to do this, we would like to note that you can run your macros usi

ted Build Studio or Automated Macro Player. The Automated Macro Player is a small command-our e-friendly utility that was specifically designed for running macros. It uses the same command-

nts as Build Studio does. Since the Macro Player has no visual user interface, it req for running and executes macros faster. However, Build Studio may be more convenient for analysis

ecution results: suppose that an error (or a warning) occurred during the execution of yac o was executed in Build Studio, you can use Build Studio’s Log or Summary panel to find the

problem. The Macro Player does not have these panels, so if

the problem. Therefore, at first, you may use Build Studio to run your macro and after you make the macro works properly, you can start using the Macro Player.

To schedule macro runs, Aubefore scheduling macro runs, you should save your macro to a file. See Saving and Loading

cros for more information on how to do this. Unsaved macros cannot be sc

If Build Studio is running as a standalone application, select Tasks (Windows Scheduler) the Tasks toolbar of Automated Build Studio to call the Task from Scheduler dialog.

• If B u Scheduler)

• (Optional) B ave been created on your computer (th

uild St dio is integrated into Visual Studio .NET, Select Build Studio | Tasks (Windowsfrom the main menu of Visual Studio to call the Task Scheduler dialog. y default, the Task Scheduler dialog lists all the tasks that he computer name is shown in the dialog caption).

Before you create a new task, select the computer where the task will run. Note that selecting the computer is optional and if you are going to run the task on your computer, you can skip this step. To select the computer:


Getting Started 66

Pres Br

Afte the selected computer in the caption of the Task Scheduler dialog.

puter). Since the task you have created will run Automated Build Studio or Macro Player, Automated Build Studio must be installed on the remote computer. The Task Scheduler uses the Windows Scheduling Tasks component, so the remote computer must have this component installed.

• To create a new task, press Add in the Task Scheduler. This will call the Scheduled Task Wizard that will assist you in creating a new task.

• On the first page of the wizard, select which application you would like to use to run your macro: Automated Build Studio or Automated Macro Player. For information on the difference between them, see above.

• Specify the other parameters the wizard asks you about (the wizard pages are similar to the pages of the Windows Scheduling Tasks wizard).

• (Optional) At the last page of the wizard, you can check the “Open advanced properties for this task” box and press Finish. This will call the Advanced Task Properties dialog. Here you can modify command-line arguments for Build Studio (or Macro Player) and modify other task properties. For instance, you can specify whether the task should be deleted after it has been executed.

s the Connect To button in the Task Scheduler dialog. This will open the standardwse for Computer dialog where you can select the desired computer. r you have selected the computer, Automated Build Studio will display the name of

o

Note: To be able to manage scheduled tasks on a remote computer, you must have appropriate permissions on that computer (the easiest way to achieve this is to add you to the Administrators group on the remote com

If your task does not run on a remote computer, make sure that the path to the macro file is specific to that computer. To do this, open the Tasks tabbed page of the Advanced Task Properties dialog and specify the correct path in the Run edit box.

Now the task is ready for running. To modify properties of an existing task, double-click the desired task in the Task Scheduler dialog and

modify task properties in the ensuing Advanced Task Properties dialog.


Continuous Integration 67

Build Strategies

Continuous Integration

Continuous Integration Support When more than one developer is working on a software project, from time to time the team members

need to integrate their changes to the project's codebase and then run a build to see if the renewed code can be built and, if the build succeeds, and if it works without errors. These builds (they indicate the "health" status of the entire project) are called integrated builds. Normally, they are performed occasionally (e.g. right before the deadline) or regularly (for instance, weekly or daily). It is hard to locate errors that arise in integrated builds that are performed rarely, since the number of changes introduced between the previous and current builds may be tremendous. To reduce the number of errors revealed in integrated builds and to make it is easier to find errors, you should perform these builds as often as possible. Ideally, builds should be performed right after the source code of your project has been modified. This will help you continuously maintain the integrity of your codebase - it will be much easier to find errors that appeared after modifying the source code, because you will always know which source files were changed for this build. It is also recommended that each build be tested and reported appropriately. By following this strategy, you will always be able to provide developers and users with a working build compiled using the latest versions of the source files. The strategy is called continuous integration (http://www.extremeprogramming.org/rules/integrateoften.html). It works well if:

• Your code is stored in a central location, preferably a source code control product like Visual SourceSafe. Build Studio macros can access different source control repositories. See Supported Tools.

• You have automated your build process, say, by writing an appropriate Build Studio macro. • You have included tests (unit, functional, regression, etc.) in the codebase as part of the project

(optional). These tests can be run as part of the build macro. • Notifications about the build and test results are sent to respective users automatically. You can

do this by including the appropriate operations in your macro. See Sending Notifications. As you can see, Automated Build Studio supports all of the prerequisites of continuous integration. In

addition, it includes facilities that allow you to practice continuous integration of your projects in full. The main facility is a dedicated Windows NT service called Automated Build Studio Service (<Automated Build Studio>\bin\AutomatedBuildService.exe). You can configure this service via Build Studio’s user interface to track all of the changes in files stored in a definite repository. This can be a folder on disk, a directory on an FTP server or a source code control repository. To reduce the amount of time spent on interaction between the service and the repository and to lower the use of resources, the service does not poll the repository constantly, it does this at certain time intervals.

The process of continuous integration provided by the Build Studio can be divided into several stages (we will illustrate this process using a Microsoft Visual SourceSafe repository):


http://www.extremeprogramming.org/rules/integrateoften.html

Build Strategies 68

Preliminary steps First, you need to perform the following preparations:

• Make sure that the Automated Build Studio Service is running. • Prepare an appropriate macro that will build the project out of the latest source files, run a set of

unit, functional, regression and other tests, and then report the build and test results to the respective users and to the log. This macro must be saved to a file. See Saving and Loading Macros for more information on how to do this. Unsaved macros cannot be used for continuous integration.

Creating a task If Build Studio is running as a standalone application, click Tasks (Continuous Integration) on the

Tasks toolbar of Automated Build Studio to call the Edit Tasks dialog. If Build Studio is integrated into Visual Studio .NET, select Build Studio | Tasks (Continuous Integration) from the main menu of the Visual Studio to do this. The dialog lets you create several tasks that the Automated Build Studio Service should perform. Each of these tasks is intended to run an existing macro in certain conditions. By default, the Edit Tasks dialog lists all the tasks that were created on your computer (the computer name is shown in the dialog caption).

Before creating a new task, select the computer where the task will run. Note that selecting the computer

is optional and if you are going to run the task on your computer, you can skip this step. To select the computer:

• Press the Connect To button in the Edit Tasks dialog. This will open the standard Browse for Computer dialog where you can select the desired computer.

• After you have selected the computer, Automated Build Studio will display the name of the selected computer in the caption of the Edit Tasks dialog.

To be able to manage time- and event-triggered tasks on a remote computer, you must have appropriate permissions on that computer (the easiest way to get hem is to add you to the Administrators group on the remote computer).

Since your task will run Automated Macro Player, Automated Build Studio must be installed on the remote computer.

Since your task will be performed by the Automated Build Studio Service, the service must be running on the remote computer.

Now let's create a new task: • Click Add in the Edit Tasks dialog. This will call the Edit Task dialog. • Choose the General Properties node on the left of the dialog and switch to the Details pane,

which is on the right.



• In the Name box, enter the name under which you want to save the task. • In the Macro file name box, specify the location of the existing macro file that the task will run.

If your task will run on a remote computer, make sure that the path to the macro file is specific to

• h configurations of the macro to use when

•

ters in the ents.

• abled

•

ssign the wait interval, started after a trigger firing, during

• ero value to it. This value should be larger than the average time

•

he following account checkbox is disabled) or some other account (the checkbox is enabled).

ed. Read the Tracing Task Triggers topic in on-line help to learn more about tr e

log and switch to the details pane.

• r fire the task when the files of a definite VSS project are changed (modified,

ad these triggers, refer to Tracing

ics in on-line help.

• ft of the Edit Task dialog, select the newly created trigger

• rror checkbox. This will deactivate the trigger if some parameters of the trigger are incorrect.

that computer.

In the Configuration dropdown list box, choose whicrunning the macro. See Using Macro Configurations. To run the macro defined in the task, the Automated Build Studio Service uses the command-line utility called Automated Macro Player. Besides the macro file name and the configuration names, this utility accepts some other parameters. You can specify these parameAdditional options box. To learn more about them, see Command-Line Argum

• In the Description box, enter additional text that describes the task in detail. To make the Automated Build Studio Service trace the given task, turn on the Encheckbox. If you want to temporarily exclude the task from tracing, turn the checkbox off. If you know that triggers that you will define in the task (see below) can be fired too frequently, and you do not want each firing of a trigger to launch a task run, set an appropriate value to the Tolerance period property. This will awhich the task run will be postponed. If you want to terminate the task automatically in case it is running too long, enable the Use timeout property and set a non-zneeded to run the task’s macro.

• Choose the Identification node on the left of the Edit Task dialog and switch to the details pane. Here you can specify the user account under which the macro will run the task. This can be either the account under which the Automated Build Studio Service will be running on the target computer (the Run macro under t

Creating the task's triggers Now we are ready to specify triggers for our task. Each trigger defines conditions under which the task

that will run the macro will be launchigg rs and blocking triggers. • Choose the Triggers node on the left of the dia• Click Add to create a new trigger in the task. • In the resulting New Trigger dialog, enter a name for the trigger in the Name box.

Select Microsoft Visual SourceSafe File Change from the Trigger Type dropdown list box. This will make the trigge

ded or deleted). For list of triggers and for information on the properties ofTask Triggers and Trigger Properties top

• Click OK to close the New Trigger dialog. Expand the Triggers node on the lethere and switch to the details pane.

• Turn on the Enabled checkbox. This will activate the trigger. Turn on the Disable on E


Build Strategies 70

• In the VSS INI path property, specify the path to the srcsafe.ini file of the desired Visual SourceSafe database.

• In the Login and Password boxes, specify the user name and password used to authenticate you in the VSS database.

The VSS user name must be given in the DOMAINNAME\USERNAME format, for instance, CEDAR\SMITH.

• In the Project or file box, enter the path to the VSS project or to the VSS file whose changes the trigger will trace. If you specify a VSS project, the trigger will track changes in all of its files.

• If you want the trigger to track changes of all subproject's of the specified VSS project, enable the Recursive checkbox.

• In the Query interval box, enter a period that will define how often the trigger will poll the VSS database.

• In the Delay after change box, enter a period that will define how long the trigger will wait after detecting a change to start the task. If any changes happen during the waiting period, the timer will start again. This is done in order not to trigger partial builds if the check-in operation consists of several steps.

Note: The values you use for Query interval and Delay after change will depend on several factors. First, they depend on how big your builds are. If a single build takes only 30 seconds or so to complete, then you can safely have a low number for Query interval, since your build machine will easily be able to keep up. If builds take hours to complete, you will want a relatively well-spaced out value to give the machine a chance to complete everything before another build is set to begin. Notice that the poll period is a regular timed interval, not an absolute time/date stamp. To configure Automated Build Studio to run your build, for instance, daily at midnight, you should use other strategies rather than continuous integration: you can schedule your macro runs using the Windows Scheduling Tasks component or using triggers of the Specified Time type (see above). Similarly, the waiting period is useful if you have several developers coordinating a check-in to the Visual SourceSafe repository. If one developer happens to complete his/her check-in right as the poll period fires, while the second developer is still checking in, then the resulting build will be based on incomplete code. With an appropriate wait period, once the poll period fires and sees changes, it provides a window for other check-ins to come in before the build actually begins. This value should be relatively short (60 seconds or less), since check-ins to the database ought to be relatively atomic and not spread out over hours or even minutes.

Creating the task's blockers If you want to block the task execution in some cases (for instance, at night, when your developers do

not change the files under Visual SourceSafe), add appropriate blockers (blocking triggers) to the task. To work with the task's blockers, first select the Blockers node on the left of the Edit Task dialog. You can manage blockers (create, delete and modify their properties) in the same way you do this with triggers. In fact, blockers are blocking triggers.

When a blocker is fired, all triggers defined for the task are ignored.

Final steps Upon configuring the task properties:

• Click OK to close the Edit Task dialog. • The new task will appear in the Edit Tasks dialog. Click Close to close the dialog.



Information about each task you create via the Edit Tasks dialog is saved to a .task file (the name of the file is the task name) in the <Automated Build Studio>\bin\Tasks folder. This is actually an .xml file with a definite structure. Thus, you can modify the list of tasks and their properties by creating, deleting and modifying these .task files (provided that you keep the valid structure of each file).

To be able to run the prepared tasks, the Automated Build Studio Service must be running. In this instance, Build Studio's executable (<Automated Build Studio>\bin\AutomatedBuildStudio.exe) is not needed until you wish to configure the task list again.

Upon running a task, you can view the status of this run in Windows Event Viewer. To do this: • Open the Control Panel | Administrative Tools | Event Viewer console. • (Optional.) If the task was run on a remote computer, select Connect to another computer from

the Action menu, specify the desired computer in the subsequent Select Computer dialog and click OK.

• Select Application under the Event Viewer node on the left of the console window. • Select Filter from the View menu. • In the resulting Application Properties dialog, switch to the Filter page. • Set the Event source property value to Automated Build Studio Service. • Click OK to close the dialog. • In the details pane of the console window (it is on the right), click the header of the Date

column. Depending on the sorting order, the last event posted by the service will appear either at the top or at the bottom of the event list. This is the event of the last task run. To view its properties, simply double-click the event.

Note: Windows Event Viewer will display those tasks that were executed. If a task is fired by a trigger, it will be only displayed if the trigger fired.

Additionally, the Automated Build Studio Service can be configured via the command-line. A full list of

arguments that a service can accept is given in the Command-Line Arguments topic. Only those arguments that relate to task execution are mentioned below:

• /trace:on and /trace:off - Enables or disables the logging of resource usage for the Microsoft Visual SourceSafe File Change, PVCS File Change, StarTeam File Change, Subversion File Change, Surround SCM File Change, Team Coherence File Change and Vault File Change trigger types. Generally the logs contain the command line of the launched process (it is used to check the state of the traced resource), the process response, the request date and time and the latest date and time of the traced resource obtained during the check.

• /poolsize:N - Defines a number of tasks that can run simultaneously. The N value must range within the 1 - 30 interval, the defaul value is 5.

• /exit - Closes the AutomatedBuildService.exe when it is launched as a stand-alone process and stores the values of the /poolsize and /trace arguments to the registry.

Tracing Task Triggers A task performs a macro run with the specified parameters. A task can be started automatically, it is not

required that Automated Build Studio is running to begin a task execution. A conception of a tasks allows to implement a continuous integration strategy that improves an integrity and consistency of an application’s codebase. There are several ways to start a task automatically:


Build Strategies 72

• Via the Windows Scheduling Tasks component that launches Automated Build Studio or Automated Macro Player along with the appropriate command-line arguments.

• Via the Automated Build Studio’s built-in Task Scheduler, that is using Windows Scheduler, but provides additional abilities for macro runs, for example allows you to start a macro on a remote computer.

• Via the Automated Build Studio Service - a Windows NT service that traces task triggers and starts a task when trigger conditions are met.

This topic describes the third way to start a task, for information about the first two ways read the Command-Line Arguments and Scheduling Macro Runs topics correspondingly.

A trigger is a pre-defined set of conditions or events that should comply to perform a task. A blocking trigger, or blocker, is a set of conditions or events that cancels the task execution. When a blocker is fired, all triggers defined for the task are ignored.

Various types of triggers and blockers are available in Automated Build Studio, so that you can choose those triggers and blockers that best suit your needs. The tables below lists the available types of triggers and blockers and gives their descriptions.

Trigger Type Description CVS File Change Fires the task when certain files stored in a Concurrent Versions

System (CVS) repository are changed (modified, added or deleted). File Change Fires the task when certain files are changed. Such triggers may help

you build your project automatically if you work on it alone and do not use any source code controls.

FTP File Change Fires the task when certain files stored on an FTP server are changed. Such triggers may help you build your project automatically if you share its source files with other developers via an FTP server and do not use any source code controls.

JediVCS File Change Fires the task when certain files stored in a JEDI version control system are changed (modified, added or deleted).

Low Disk Space Fires the task when the free space size of a particular folder or logical drive falls below the given threshold. You may need such triggers to run a macro that cleans up unnecessary files in order to free some space on disk.

Microsoft Visual SourceSafe File Change

Fires the task when files of a particular Visual SourceSafe project are changed (modified, added or deleted).

Perforce File Change Fires the task when certain files stored in a Perforce repository are changed (modified, added or deleted).

PVCS File Change Fires the task when certain files stored in a PVCS repository are changed (modified, added or deleted).

Rational ClearCase File Change Fires the task when certain files stored in a ClearCase repository are changed (modified, added or deleted).

SourceOffSite File Change Fires the task when one or more files stored in a SourceOffSite repository are changed (modified, added or deleted).

Specified Time Fires the task at the specified time at certain week days. You can limit the week days when the task should be fired. If the task is not fired at specified time for some reason, you can specify a waiting period



during which you allow to run the task. Using such triggers is an alternative to the tasks you run via the Windows Scheduling Tasks component.

StarTeam File Change Fires the task when certain files stored in a StarTeam repository are changed (modified, added or deleted).

Subversion File Change Fires the task when certain files stored in a Subversion repository are changed (modified, added or deleted).

Surround SCM File Change Fires the task when certain files stored in a Surround SCM repository are changed (modified, added or deleted).

Team Coherence File Change Fires the task when certain files stored in a Team Coherence repository are changed (modified, added or deleted).

Team Foundation Version Control File Change

Fires the task when certain files stored in a Team Foundation repository are changed (modified, added or deleted).

Time Period Fires the task periodically every time the specified time interval elapses.

Vault File Change Fires the task when certain files stored in a SourceGear Vault repository are changed (modified, added or deleted).

Blocker Type Description Date Range Blocks the task execution during the specified date range. Days of Week Blocks the task execution at the specified week days. Low Disk Space Blocks the task execution when the free space size of the needed

folder or logical drive falls below the given threshold. Time Range Blocks the task execution daily during the specified time range.

Each task does not depend on other tasks. This means that when the Automated Build Studio Service is

running a task, it does not stop checking the other tasks and can run several or even all the tasks at once. However, when an individual task is running, all of its triggers and blockers are ignored. That is, the task cannot be run anew until it stops. The task properties as well as its triggers and blockers are specified in the Edit Task dialog. The triggers' and blockers' properties are described in the Trigger Properties on-line help topic.

To detect changes in a new resource, a trigger must have at least one access to that resource. This is needed to get the trigger's initial timestamp. An attempt to get this timestamp is made right after the trigger is enabled or re-enabled.

If the Disable on Error property is off, the trigger will keep trying to get the resource's timestamp with the same query and delay intervals even if there are connection or other problems. If Disable on Error is on, the trigger will be disabled as soon as the first error occurs and thus it will stop querying the resource. To activate the trigger again, turn on the trigger's Enabled property.

Changing a trigger's query and delay intervals does not affect the trigger's capability of detecting changes. This means that you can edit the Query interval and Delay after properties of the trigger are changed while it is active. After you click OK in the Edit Task dialog, all time counters of all enabled triggers of the given task will be reset, and then, right after that, they will start measuring their time anew. At that, the changes made to the files during property editing will not be omitted.


Build Strategies 74

However, when you modify any of the trigger's properties except for Query interval and Delay after change, the trigger will reset its stored date of the last successful access to the resource, "thinking" that the user has selected another resource to monitor. As a result, the changes made to the files during property editing will be omitted.

Distributed Builds

Distributed Builds – Overview A process of building an application includes several tasks, such as getting the latest version of source

files from a version control system, compiling the source files, creating the installation package and others. Some of these tasks (mostly, compilation of source files) can be divided into smaller tasks, each of which can be run on a separate computer at the same time as other tasks. For example, an application may consist of a number of independent modules, so these modules can be built independently on different computers simultaneously. These build processes, whose workload is distributed among several cooperative computers within the network, are called distributed builds.

Distributed builds essentially reduce the project build time due to the fact that the build tasks are executed simultaneously on several computers. Using distributed builds, you can expect the build performance to speed up depending on the number of computers you use in the build. In this way, you can run your builds faster and more often, which is an essential part of the continuous integration strategy.

Some third-party build tools supported by Automated Build Studio, such as IncrediBuild or NAnt, can distribute compilation among assigned network computers themselves. If you do not use these tools or if you need to distribute tasks other than compilation, you can make use of distributed build capabilities provided by Automated Build Studio.

In Build Studio, distributed builds can be organized by using special operations in the Remote Macro Execution category:

• Remote Group – Executes a group of operations on a specific remote computer. • Remote Execution Stack – Executes its child operations in parallel, on the specified remote

computers that are available at that time. • Remote Macro Command – Lets you execute a specific macro on a remote computer.

In addition to running operations on remote computers, you can take advantage of the standard Group operation that can execute its children asynchronously (in parallel). For example, you can place several Remote Group operations into an asynchronous Group so that they will run simultaneously. For more information on executing operations in parallel, see Concurrent Execution of Operations.

Within the Remote Group and Remote Execution Stack operations, you can use the same operations that are used in typical macros. The only difference is that the properties of these operations (such as file names and paths) must be specified with regard to the remote computer on which they will be run. In properties of these operations, you can also use variables and constants. In this case, macro variables act like parameters that are passed by reference. That is, before executing remote operations Automated Build Studio initializes macro variables on the remote computer with their current values on the host computer. Changes made to variable values in remote operations are applied to variables in the main macro once the execution returns to it.

The remote operations’ logs are also transferred to the main computer once the execution returns to the main macro. They are included in the macro log, which is displayed in the Log panel, and taken into account in the macro summary.


Distributed Builds 75

Distributed Build Scenarios The typical build process consists of several steps, including obtaining the latest version of source files,

building the application, creating the installation package, and so on. Some of these steps for example, the compile process, can be split into several independent tasks that can be carried out in parallel by multiple computers.

In this topic, we suggest some distributed build scenarios that you can use to improve the performance of your build process. To learn how you can create Automated Build Studio macros to implement these scenarios, see Creating Distributed Builds.

Reduce Build Time One of the main advantages of the distributed build strategy is that it dramatically reduces the project

build time, comparing to the builds run on a single build server. The most speedup is achieved by distributing compilation tasks among build servers specified in macro operation properties. However, this requires you to determine the project parts (for example, sets of libraries) that can be built independently on several machines. Once you have decided that, you can create and configure the corresponding build projects on individual build servers. Note that unless you are building a multi-platform project (see the following section), all build servers must have the same configuration.

Each set of built modules can be copied to a shared network drive. After the project modules are collected, you can create the installation package and perform additional tasks (for example, deploy the product on test machines).

By using the distributed build strategy, you can build your projects faster and more often, which is an essential part of the continuous integration strategy.

Build Multi-Platform Products You can take advantage of distributed builds to build multi-platform products. These are products that

have several versions built for different platforms (for example, versions for 32-bit and 64-bit platforms, for different versions of the Microsoft .NET Framework, and so on) as well as products that provide different versions of a set of libraries for different platforms or environments. The key point in this scenario is that you need to create several sets of modules from the same source files in different environments.

Usually, you would implement this scenario by having a number of preconfigured build servers and running an individual build macro on each of them. With the distributed build feature provided by Automated Build Studio, it is a lot easier to maintain builds. You can have a single build macro running on the host computer that will execute specific tasks on remote build servers. These tasks can include, for example, getting the latest version of source files from a particular location on each machine and compiling the sources. The remote tasks can be run serially (that is, one build server after another), or on all build servers in parallel.

Like in the previous scenario, the built modules can be copied to a shared network disk, after which you can create the installation packages. However, it is also possible to distinguish a number of common tasks, for example, sending notifications at the end of the build. These tasks can be carried out by the build macro on the host computer.

Run Builds and Tests on Different Machines It's a common practice to run functional, regression and other kinds of tests on the newly built product

version to ensure its quality. Automated Build Studio supports many third-party testing tools, so that you can run automated tests as a part of your build macro. However, usually this assumes that builds and tests are run on the same machine, which is often inconvenient.


Build Strategies 76

Using the distributed build feature, you no longer have to use the same machine as a build and test server. You can build a project on one machine and test it on another one. Furthermore, it is possible to use several test servers to test the product behavior in different environments. The Build Studio macro can also be configured so that the tests will be run in parallel.

This scenario requires a build macro that will build the project and then deploy it on test servers. The test servers can be either preconfigured, or configured by the corresponding macro operations (for example, you can use operations of the Microsoft Virtual Server category to manage a virtual machine on the test server). Results of automated tests will be transferred from remote machines to the host computer. Automated Build Studio can parse the test tool’s output so that you can easily determine whether the tests passed or failed and, based on this, mark the build as successful or broken.

Creating Distributed Builds Macros that perform distributed builds are similar to other build macros, with the difference that some of

their tasks are split into smaller tasks that are distributed for running on multiple remote computers. The key point in creating distributed build macros is to specify a set of computers that can participate in distributed builds and to divide a single build task into several independent tasks.

This topic explains how to configure remote computers and create distributed build macros:

Configuring Remote Computers Connecting to Remote Computers From Macros Distributing Operations Among Remote Computers

Running Operations on a Specific Remote Computer Running Operations on Several Remote Computers Concurrently Running Macros on a Remote Computer

Running Distributed Build Macros Possible Problems

Configuring Remote Computers The computers that participate in the distributed build must be configured in a special way. First, the

remote computers must have all of the needed software (such as compilers, build tools and helper utilities) installed and properly configured. For instance, if you are going to distribute the compilation of a Microsoft Visual Studio .NET project among several computers, this IDE must be installed and configured on that computer.

Also, Automated Build Studio must be installed on these computers and the Automated Build Studio Service must be running on them (this service is used to transmit data between the host computer where the build macro is running and the remote computers where the individual macro tasks are executed).

To connect to remote computers from the host computer, Automated Build Studio can use the DCOM or SOAP (Web service) protocol. DCOM is typically used to connect to local computers that belong to the same domain. In general, it works faster than SOAP and, since it is an integral part of the Windows operating system, it does not require any additional software on remote computers. However, SOAP lets you connect to computers that do not belong to the domain containing the host computer. Whichever connection type you choose to use to connect to a specific remote computer, you should configure it on that computer, as described in the Connection Parameters topic.



Connecting to Remote Computers From Macros Automated Build Studio provides a special Setup Connections operation that can be used to specify a set

of remote computers for the distributed build and to adjust the connections to these computers. To configure connections, follow these steps:

4. Add the Setup Connections operation to your macro. To learn how to add operations to the macro, see Adding, Removing and Arranging Operations in a Macro.

5. Double-click the Setup Connections operation, or right-click it and select Properties from the context menu. This will open the Setup Connections Operation Properties dialog.

6. In the Operation Properties dialog, switch to the Connections page. 7. Click the Add button under the Connections list box and enter the name for the connection of the

remote computer. This can be the remote computer name (for example, JohnSmithComp) as well as an arbitrary name (for example, Connection1).

8. In the panel on the left, select the connection type that is used to connect to the remote computer: SOAP or DCOM. If you select the DCOM connection, specify the name of the remote computer (for example, JohnSmithComp) in the Server name field. If you select the SOAP connection, specify the URL of the Automated Build Studio Server on the remote computer in the Server URL field. The Build Studio Server URL has the http://ComputerName_or_IP/VirtualFolderName format, where ComputerName_or_IP is the name of the remote computer or its IP address, and VirtualFolderName is the name of the virtual folder on the remote computer where the Automated Build Studio modules reside (the default name is AutomatedBuildStudio). Examples of Server URLs are: http://JohnSmithComp/AutomatedBuildStudio and http://192.168.1.103/AutomatedBuildStudio.

9. If you want to use a specific account when connecting to the remote computer, make sure that the Authenticate as the currently logged on Windows user option is disabled and fill in the Username and Password fields. To connect using the account of the user currently logged into Windows, enable the Authenticate as the currently logged on Windows user option.

10. Repeat steps 4-6 to specify connections to other remote computers you want to use in the build process.

11. Press OK to close the Setup Connections operation properties dialog and save the changes.

Distributing Operations Among Remote Computers An essential part of creating distributed build macros is to decide which build tasks should be split into

smaller ones and to distribute them among remote computers. For example, if your project consists of multiple independent modules, you can split the project build process into building each project module. The process of building an individual module includes the same steps as building the whole project, that is, getting the latest version of source files, compiling the project, copying the build modules to a shared network disk, and so on.

Automated Build Studio does not automatically distribute the compile process among remote computers. If you need to distribute the compile process, you should manually create andconfigure individual projects for building each project module.

You can distribute the remote build tasks among specific computers, or among those specified computers that are available at that time. Again, these computers must have all of the needed software for performing the corresponding operations. For example, if you want to distribute the compile process among several computers, the compiler must be installed on all of them.


Build Strategies 78

Running Operations on a Specific Remote Computer If you wish to execute a group of operations on a specific remote computer, use the Remote Group

operation: • Add the Remote Group operation to your macro. • Double-click the Remote Group operation, or right-click it and select Properties from the

context menu. This will open the Remote Group Operation Properties dialog. • In the Operation Properties dialog, switch to the Remote Group Details page. • Check the Run child operations on remote computer property. • In the Connection field, enter the name of the connection to the desired remote computer that

you have previously configured in the Setup Connection operation. For example, Connection1. You can also press the ellipsis button and choose the desired connection from the list.

• In the Working folder filed, specify the path to a folder on the remote computer where you want to upload the macro. For example, D:\Work.

• By default, the remote instance of Automated Build Studio (or Automated Macro Player) is launched under the same account as the Automated Build Studio service (usually, the SYSTEM account). However, operations that will be executed remotely may require specific account data in order to run successfully (for example, the operation that checks out files from the version control system). You can either specify this account in the operation properties, or make the remote instance of Automated Build Studio (Automated Macro Player) run under that account. To do the latter, check the Run under the following account property and specify the needed user name and password in the Username and Password fields.

• Press OK to save changes and close the Operation Properties dialog. • Add the operations that you want to execute on the remote computer as a child of the Remote

Group operation and configure their properties.

When specifying properties of operations that are executed on a remote computer, remember that file names and paths must be specified relative to that computer.

Running Operations on Several Remote Computers Concurrently If you want to execute several operations or groups of operations on multiple remote computers in

parallel, you can place several Remote Group operations under a concurrent Group operation (see Concurrent Execution of Operations). In this case, the Remote Group operations are run simultaneously on the corresponding remote computers.

However, you may also want to execute an operation or group of operations on any of the computers available for this purpose. This can be achieved by using the Remote Execution Stack operation:

• Add the Remote Execution Stack operation to your macro. • Double-click the Remote Execution Stack operation, or right-click it and select Properties from

the context menu. This will open the Remote Execution Stack Operation Properties dialog. • In the Operation Properties dialog, switch to the Remote Execution Stack Details page. • Check the Run child operations asynchronously on remote computers property. • The Computers list specifies the network computers available for the remote build. During the

macro run, Automated Build Studio distributes child operations of the Remote Execution Stack operation between those specified computers that are available at that time.



To add a new computer to the list: Press the Add button. The Computer dialog appears. In the Connection field, enter the name of the connection to the desired remote

computer that you have previously configured in the Setup Connection operation. For example, Connection1. You can also press the ellipsis button and choose the desired connection from the list.

In the Working folder field, specify the path of the folder on the remote computer where you want to upload the macro. For example, D:\Work.

If you need the remote instance of Automated Build Studio (or Automated Macro Player) to be run under a specific account, check the Run under the following account property and specify the needed user name and password in the Username and Password fields.

Press OK to save the changes and add a new computer to the list. You can add other remote computers to the list in a similar way.

• Press OK to save the changes and close the Operation Properties dialog. • Add the operations that you want to execute on the remote computer as a child of the Remote

Execution Stack operation and configure their properties.

When specifying properties of operations that are executed on a remote computer, remember that file names and paths must be specified relative to that computer.

Note that when executing the Remote Execution Stack, Build Studio will distribute its direct child operations among the available computers. If you need to execute a group of operations rather than a single operation on a remote computer, you should first add the Group operation as a child of the Remote Execution Stack operation and then add the desired operations as children of the Group operation, like on the image below:


Build Strategies 80

Running Macros on a Remote Computer Besides executing a group of operations on a remote computer, you can also run a whole macro

remotely. For this purpose, use the Remote Macro Command operation. Below is a step-by-step explanation of how to configure this operation in your macro:

• If a macro that you wish to run on a remote computer has yet to be uploaded to that computer, you should first upload it. In macros, you can do this using the Upload Macro operation:

Add the Upload Macro operation to the macro. Double-click the Upload Macro operation, or right-click it and select Properties from

the context menu. This will open the Upload Macro Operation Properties dialog. In the Operation Properties dialog, switch to the Upload Macro Details page. In the Connection field, enter the name of the connection to the desired remote

computer that you have previously configured in the Setup Connection operation. For example, Connection1. You can also press the ellipsis button and choose the desired connection from the list.

In the Macro file name field, specify the name of the macro to be executed on a remote computer. You can press the ellipsis button and browse for the desired macro file.

In the Remote folder field, specify the path to the folder on the remote computer to which the macro will be uploaded. For example, D:\Work.

Press OK to save the changes and close the Operation Properties dialog. • Add the Remote Macro Command operation to your macro. • Double-click the Remote Macro Command operation, or right-click it and select Properties

from the context menu. This will open the Remote Macro Command Operation Properties dialog.

• In the Connection field, enter the name of the connection to the desired remote computer that you have previously configured in the Setup Connection operation. For example, Connection1. You can also press the ellipsis button and choose the desired connection from the list.

• In the Macro file name field, specify the path to the desired macro file on the remote computer. You can press the ellipsis button and browse for the desired macro file.

• In the Command property, select Start macro. • If you want Automated Build Studio to wait until the remote macro is executed, enable the

Check the command to complete check box. Otherwise, if this property is unchecked, the remote macro will be run in parallel with the rest of the local macros. (In this case, you can check for macro completion by using the If Remote Macro State Is... operation.)

• In the Run macro in box, specify which tool, Automated Build Studio or Automated Macro Player, should be used to run the macro.

• (Optional). Specify the command-line parameters to be passed to the remote instance of Automated Build Studio or Automated Macro Player (see Command-Line Arguments).

• If you need the remote instance of Automated Build Studio (or Automated Macro Player) to be run under a specific account, check the Run under the following account property and specify the needed user name and password in the Username and Password fields.

• Press OK to save the changes and close the operation properties dialog.

Note: The logs of remote macro runs are kept on the remote computer.



Running Distributed Build Macros Once you have configured the build servers that will participate in the distributed build and the computer

that will host the build, you can run the build macro. Automated Build Studio macros can be run in several ways:

• You can run Automated Build Studio on the host computer and start the macro directly from Build Studio (see Running Macros).

• You can run the macro on the host computer from the command line, using either Automated Build Studio or Automated Macro Player (see Command-Line Arguments).

• You can schedule the macro to run at specific times on the host computer (see Scheduling Macro Runs).

• You can start the macro on the host computer from another computer using the Automated Build Studio Client/Server functionality.

• You can run the macro on the host computer via the Automated Build Studio Web Interface.

Possible Problems There are a number of things that you should keep in mind when organizing a distributed build macro. Unless you are building a multi-platform project, make sure that the build servers used in the distributed

build have the same configuration (operating system, build tools, and so on). Differences in the build server configurations may cause issues with functioning and interoperation of compiled modules.

During the macro execution, issues can occur if child operations of the Remote Execution Stack operation use the same resources (for example, if they save results to the same file on a shared network disk or to the same Build Studio variable). In this case, a resource may be blocked, or it may be accidentally changed by another operation, which can cause errors during the operation’s execution. To avoid these errors, do not use and modify the same resources in child operations of the Remote Execution Stack. As a workaround, you can make a local copy of the resources and work with this copy.

Note that on remote computers, Automated Build Studio (or Automated Macro Player) is launched in the non-interactive mode. This means that they do not display any windows or dialogs that would be shown if the corresponding macro operations were executed on the local computer. So, if your macro includes operations that display dialogs or launch third-party tools that require user input, these operations will hang.

You can only remotely execute those UI operations that have a timeout limit specified and a default resulting value when the user does not respond during the timeout period. For example, operations of the Interactive category meet both conditions, so they can be successfully run on remote computers.

If the remote macro hangs for some obscure reason, you can sort out and handle problematic operations by specifying the timeout limit for them. You can either set the specific timeout for each operation, or use the timeout common for all macro operations. If the operation’s timeout is enabled, the operation will be terminated when its execution time exceeds the timeout value, and Automated Build Studio (Automated Macro Player) will proceed to the next operation. For more information, see Handling Errors in Macros.

Another way to handle hanging of remotely executed macros or macro parts is to specify the timeout for the Remote Macro Command, Remote Group and Remote Execution Stack operations. Automated Build Studio (or Automated Macro Player) runs the main macro and tracks the total run time of the remote macro or macro part(s) and terminates it after the timeout limit.


Build Strategies 82

Concurrent Execution of Operations Automated Build Studio includes a lot of operations that you can use in your macros. By having a variety

of operations at your disposal, you can create complex macros that perform several tasks that will be executed simultaneously. With Automated Build Studio, you can organize concurrent execution of macro operations and thus perform different tasks at the same time.

Concurrent (or multithreading) execution lets you improve the performance of Automated Build Studio macros and reduce the macro execution time. When macro operations are run in a series, they are executed within the same thread, so the next operation only starts after the previous operation is finished. When a group of operations are run concurrently, Automated Build Studio starts the next operation in a separate thread, without waiting for the previous operation to complete. As a result, the CPU is used more effectively and less time is needed to execute macros.

Concurrent execution of operations can greatly improve performance in the following cases: • A macro is executed on a multiprocessor computer. A processor can only execute one thread at a

time. So, on a computer with a single processor, only one thread can be executed at a time; whereas a computer with ten processors can execute ten threads at a time.

• A macro contains operations that require a lot of time (for example, the Get Latest Version operations for large projects, file uploads and downloads, database queries and so on). When this type of an operation is being executed, other operations cannot be started until that operation is finished. Putting an operation in a concurrently running group will allow other operations to run simultaneously with this operation, and it will not block them.

• A macro contains operations that perform data transmission over a network (for example, operations of the FTP, HTTP and other groups). When running concurrently, each operation uses a separate connection so that the overall bandwidth is greater than the serial operation's execution, when all operations use the same connection.

• Many others. Generally, almost all operations provided by Automated Build Studio can be run concurrently (however,

there are technical and logical restrictions described below). Here are some examples of the operations that should be run concurrently:

• To split long-running tasks into smaller tasks. For example, an operation that obtains source files from a Source Control System (SCS) can be divided into several same operations, each obtaining a certain part of the source files. Running concurrently, these operations will take less time than a single operation that performs the whole task.

• Run the operations, that do not depend on each other and do not use the same resources, concurrently. For example, if your macro contains the Remove Directory operation that cleans temporary folders and the Upload File(s) to FTP operation that uploads one or several files to an FTP server, you can group them so that they run concurrently.

Organizing Concurrent Execution of Operations Operations, as well as groups of operations that you wish to run concurrently, should be children of the

Group operation: 1. Add the Group operation to your macro. 2. Move the operations that you wish to run concurrently to the children of this Group operation.

For more information on how to change operations’ “relationship”, see Adding, Removing and Arranging Operations in a Macro.

3. Double-click the Group operation, or right-click it and select Properties from the context menu. This will open the Group Operation Properties dialog.


Concurrent Execution of Operations 83

4. In the Operation Properties dialog, switch to the Group Details page. 5. Enable the Run child operations asynchronously check box. 6. If the operations in the group are of the same kind, use the Delay before start new thread

property to specify the time interval for Automated Build Studio to wait before starting the next child operation in a new thread. This delay lets you avoid issues caused by simultaneous execution of the same actions by similar or identical operations (such as issues with accessing the same resources, and others).

7. In order to prevent Automated Build Studio from creating too many threads for the given group of operations, you can limit the number of threads using the Max thread count property. (Possible issues with a large number of threads are described below). If this property is set to 0, the number of threads is unlimited.

8. Click OK to close the dialog. Note again that you can organize concurrent execution of both single operations and groups of

operations. In this case, you have to make the parent Group operation of each group a child of the common parent Group operation. In their turn, operations in each group can be executed in a series or concurrently. If child operations of the Group operation are executed concurrently, the Time with Child values in the log indicates the longest execution time of a child operation, not the sum of operation execution times.

Possible Issues with Concurrent Execution of Operations There are a number of things that you should keep in mind when organizing concurrent execution of

operations in your macro. Reasoning from the macro execution logic, you should not run concurrently those operations that depend

on each other. For example, an operation that prepares resources for a certain task and an operation that performs this task should not be run concurrently, because when the latter operation starts, it may turn out that the resources are not prepared for it.

Issues may occur if you have concurrent operations that use the same resources (for example, if the operations save their results to the same file or Build Studio variable). In this case, a resource may be blocked, or it may be accidentally changed by another operation. This can cause errors during the operation’s execution. To avoid these errors, do not concurrently run those operations that use and modify the same resources. Another solution is to use “thread-relative” variables. These variables allow you to have different values for different threads.

The issue described above, results in another restriction: if an operation’s API requires exclusive access to a resource, then the operations implemented via the same API cannot run concurrently. Currently this restriction applies to Team Coherence operations from the Issue Tracking and Team Coherence categories. These operations should not be executed concurrently, otherwise an error may occur.

Also, a great number of concurrently running operations require a lot of operating system resources in order to keep track of all threads. When switching between the threads, the system saves the context of the current thread and restores the context of the next thread. These actions can take a significant part of the processor’s time, which will eliminate the benefits of concurrent operation execution. Automated Build Studio lets you limit the number of threads that can be started for a group of operations. An optimal number of concurrent operations depends on the configuration of your computer.


Using Variables and Constants in Macros 84

Using Variables and Constants in Macros

Variables and Constants – Overview Variables and constants make macros more flexible and powerful. They can be used in almost all

operation properties (for example, in properties that specify file names and paths). During the macro run, variable values can be modified using the Set/Reset Variable Value operation or from scripts. In addition, some operation can store their results in a variable so that it can be further used in the macro.

An example of variables’ usage is iterating through files in a folder. Without variables, it would be difficult to do this: you would have to create as many operations as the number of files in the folder. With variables, this is much easier: Automated Build Studio includes the File Enumerator operation that obtains a list of files in a folder and iterates through this list. At each iteration, this operation saves the name of the current file to a variable so that the child operations can work with this file.

Note: The concept of macro variables and constants are not applied to MSBuild projects. It is only used for Automated Build Studio macros.

Description of Variables Variables are accessible in any operation of the macro where they were created. You can use variables to

set or get values of operation properties. You can address variables in scripts. There are three types of macro variables:

• Ordinary variables • Stored variables • Environment variables

Ordinary and stored variables can be created and changed in Automated Build Studio macros. Environment variables specify values that are used in Windows. They cannot be created within Automated Build Studio. You can change their values, but these changes are only “visible” for Automated Build Studio (or Automated Macro Player) and for applications started by your macro.

Ordinary and stored variables are managed via different dialogs: Variables or Stored Variables dialogs. To call these dialogs, select Variables | Variables or Variables | Stored Variables from the main menu of Build Studio (if it is running as a standalone application), or select Build Studio | Variables | Variables or Build Studio | Variables | Stored Variables from Visual Studio’s main menu (if Build Studio is integrated into Visual Studio .NET), or select Variables | Variables or Variables | Stored Variables from the main menu of Build Studio’s Edit Script Form (in both cases). The difference between ordinary and stored variables is that the values of stored variables are saved between macro runs in the macro file. That is, if you assign a value to a stored variable and then stop the macro, the variable value will not change while an ordinary variable will be reset. Stored variables are useful, for instance, to keep the build number, which could easily be increased in any of the next runs.

All variables can have default values. The default values of ordinary and stored variables are specified in the Variables or Stored Variables dialogs. If the default value is not specified, it is considered to be an empty string. Note that besides specifying the default value explicitly, you can initialize stored and ordinary


Variables and Constants – Overview 85

variable using the Set/Reset Variable Value operation (see below). The default value of an environment variable in Automated Build Studio corresponds to the variable value in the operating system.

To set the value of a variable in your macro either use the Set/Reset Variable Value operation, or write a script (the ordinary and stored variables can also be changed between macro runs via the Variable and Stored Variables dialogs). Using the Set\Reset Variable Value operation is extremely simple and does not require explanation. Note that this operation gives you a way to assign the variable (usually, a stored variable) with the specified or default value in all configurations at once by enabling the Set/Reset for All Configurations property.

Since variable names are used to address variables in scripts, the variable name must match the naming rules used in the scripting language you chose for the script. To make the variable name suitable for any supported scripting language, follow this simple rule when naming a variable: a name can include only letters, digits and underscores and must begin with a letter.

Ordinary, stored and environment variables use the same namespace, so you cannot create an ordinary or a stored variable that has the same name as an environment variable.

Both stored and ordinary variables have the environment attribute. You can set it in the Variables and Stored Variables dialogs. This attribute determines how a variable is used. All variables that have the environment attribute enabled will be passed to the process launched by the macro. For instance, they will be passed to the process that is launched by the Execute Program operation. These variables will serve as environment variables of that process. Do not confuse these variables with environment variables that were described above. The latter return values of the environment variables and they are constants in fact.

The ordinary variables also have the thread-relative attribute. You can set it in the Variables dialog. This attribute is useful when several operations are executed concurrently (see Concurrent Execution of Operations). The variables that have this attribute have separate values for each executed thread, thus you can refer to the “same” variable name in different threads without causing a resource conflict. For instance, all variables declared in the Submacro operation have the thread-relative attribute enabled.

Neither ordinary, environment, nor stored variables can be used as loop variables.

Description of Constants Constants are very similar to variables. We would like to outline some things you should remember:

• Ordinary constants are those that you can create and modify using the Constants dialog. To call this dialog, select Variables | Constants from the main menu of Build Studio (if it is running as a standalone application) or select Build Studio | Variables | Constants from Visual Studio’s main menu (if Build Studio is integrated into Visual Studio .NET), or select Variables | Constants from the main menu of Build Studio’s Edit Script Form. Values of ordinary constants are stored in the macro file. They are not computer dependent. The values of system constants are defined by Automated Build Studio at startup. You cannot modify them. Values of system constants depend on what software is installed on the machine that runs the macro. The main purpose of these constants is to make macros easier and portable. For instance, if your macro works with TestComplete, you can use the TESTCOMPLETEDIR constant to obtain the path to TestComplete, so you do not need to change anything in your macro for it to be able to run on another machine. To view what system constants are available to you, use the System Constants dialog. To call this dialog, select Variables | System Constants from the main menu of Build Studio (if it is running as a standalone application) or select Build Studio | Variables | System Constants from Visual Studio’s main menu (if Build Studio is integrated into Visual Studio).



• Constants are read-only. Macros cannot change them. You can only change the value of ordinary constants in the Constants dialog before running your macro. You cannot change system constants.

• Like variables, ordinary constants also have an environment attribute, which specifies whether a constant is passed to the process launched by the macro (for more information of this attribute, see the section Description of Variables).

Creating Variables and Constants and Modifying Their Attributes

Creating an ordinary variable

• Select Variables | Variables from Build Studio’s main menu or Build Studio | Variables | Variables from Visual Studio’s main menu. If the Edit Script Form is currently opened, select Variables | Variables from its menu. The Variables dialog will appear:

• In the dialog:

Press the Add button. This will append an empty line to the variables list.

Enter the variable name into the Name column, specify the initial value in the Default Value column and check the Environment or Thread-Relative boxes to enable the corresponding attributes for the variable (if needed). For more information on these attributes, see Variables and Constants - Overview.

Optionally, you can supply a variable with a description. To do this press the Description button and enter the description in the ensuing dialog.

Press OK to save changes.

Using the Variables dialog you can also remove ordinary variables and modify their properties: just call the dialog and then press the Delete or Edit button.

Creating a stored variable

• Select Variables | Stored Variables from Build Studio’s main menu or Build Studio | Variables | Stored Variables from Visual Studio’s main menu. If the Edit Script Form is currently opened, select Variables | Stored Variables from its menu. The Stored Variables dialog will appear:

• In the dialog:


Enter the variable name into the Name column, specify the default value in the Value column and check the Environment box to set the variable’s environment attribute (if needed). For more information on this attribute, see Variables and Constants - Overview.

Optionally, you can supply a variable with a description. To do this press the Description button and enter the description in the ensuing dialog.



Creating Variables and Constants and Modifying Their Attributes 87

Using the Stored Variables dialog you can also remove stored variables and modify their properties: just call the dialog and then press the Delete or Edit button.

Note: The ordinary, environment and stored variables share the same namespace, so you are not allowed to create an ordinary or stored variable, whose name coincides with the name of another stored or ordinary variable or environment variable.

We would like to note that since variables can be used in scripts, the variable name must be a valid identifier for the selected scripting language. To make the variable name suitable for any supported scripting language, follow this simple rule: a variable name can include only letters, digits and underscores and must begin with a letter.

Checking an environment variable The environment variables cannot be created or deleted. To check what environment variables exist and

to check their values, use the Environment Variables dialog. To call this dialog, select Variables | Environment Variables from the main menu of Build Studio (if it is running as a standalone application) or select Build Studio | Variables | Environment Variables from Visual Studio’s main menu (if Build Studio is integrated into Visual Studio).

Creating an ordinary constant

• Select Variables | Constants from Build Studio’s main menu or Build Studio | Variables | Constants from Visual Studio’s main menu. If the Edit Script Form is currently opened, select Variables | Constants from its menu. The Constants dialog will appear:

• In the dialog:


Enter the variable name into the Name column, specify the constant value in the Value column and check the Environment box to set the constant’s environment attribute (if needed). For more information on this attribute, see Variables and Constants - Overview.

Optionally, you can supply a constant with a description. To do this press the Description button and enter the description in the ensuing dialog.


Note: Ordinary constants, system constants and environment variables share the same namespace, so you cannot create an ordinary constant which name coincides with the name of another ordinary or system constant or with the name of an environment variable.

We would like to note that since constants can be used in scripts, the constant name must be a valid identifier for the selected scripting language. To make the variable name suitable for any supported scripting language, follow this simple rule: a variable name can include only letters, digits and underscores and must begin with a letter.

Checking a system constant System constants cannot be created or deleted. To check what system constants exist and to check their

values, use the System Constants dialog. To call this dialog, select Variables | System Constants from the main menu of Build Studio (if it is running as a standalone application) or select Build Studio | Variables | System Constants from Visual Studio’s main menu (if Build Studio is integrated into Visual Studio).



Using Variables and Constants in Operation Properties You can use variables and constants in almost any operation property. One of the common tasks for them

is to store the file name, build number or specify the file path. The way you specify a variable or constant name depends on the purpose of the variable (constant).

If you use a variable or constant to specify a property value, you should enclose the variable (constant) name with the % signs. Otherwise, Automated Build Studio will treat the variable (constant) name as a string value. For instance, on the following figure we use the MyProjectName variable to specify the Visual Basic project to be compiled:

Note: To specify the % character in the property value, use the %%% string. For instance, if you specify %%%temp%%%, Automated Build Studio will use the string %temp%, but not the value of the temp variable. Note that you need to replace the % character with %%% only in those cases, when the string value can be considered as a variable name. Otherwise, you can use a single % character. For instance, in the string Use % to separate values you can use the single percent character since % is surrounded by spaces.

If you use a variable to save an operation result (for example, to save a file name returned by the File Enumerator operation), you should not use the % signs:


Using Variables and Constants in Script Operations 89

To concatenate values of two or m r constants, simply put theore variables o

, if one variable holds the file name and another onm one after another. For

instance e holds the file path, the following string will retu

path, enter the follo

, you must use pluses, of course. You an so

concatenate c

operation in y y writing a script (the stored variables can also be changed in the Stored Variables dial is simple and does not require explanations. Changing vari t, that is why we will tell you more about this.

e mac

s.variable_name = value

rn the entire file name: %File_Path_Var%%File_Name_Var%

If you need to specify a slash between the path and file name, and the disk name before the wing:

c:\%File_Path_Var%\%File_Name_Var%

Note that we do not use pluses to concatenate variables (constants) and strings and do not specify spaces: Automated Build Studio treats pluses and spaces as characters, so we would obtain an invalid path. If you concatenate variables and strings in scripts

c concatenate two or more constants in the same way you concatenate variables. You can alonstants with variables and strings.

Using Variables and Constants in Script Operations variable in your macro either by using the Set\Reset Variable ValueYou can set the value of a

our macro, or bog). Using the Set\Reset Variable Value operationables from scripts is also simple, but it is not evidenFrom the script’s point of view, macro variables are public variables that are visible within the entirro. To address an ordinary, environment or a stored variable, use the following simple syntax:

Variable



Using the Variables.variable_name format when referring to the macro’s variables allows you to a al variables that are declared using the same names.

LocalVar = Constants.constant_name

address environment variables through the Constants object (see below). This feat recommend that you address environment variables thro

void confusing variable names if your script holds locTo address an ordinary or a system constant, use the Constants object:

Note that you can also ure is supported for backward compatibility only. Weugh the Variables object.

LocalVar = Constants.environment_variable_name

We would like to note once again that since variables and constants can be used in scripts, their names must comply with the naming rules of the selected scripting language. To make the name suitable for any supported scripting language, follow this simple rule: a variable name can include only letters, digits and underscores and must begin with a letter.

Macro variables cannot be used as loop variables. A loop variable should be a local variable. store object references. They can only store ordinary

e-specific syntax. For oncatenated from the path to t folder and the name of the file, which are also stored in variables.

Also, macro variables cannot be used to values: numbers, strings, dates and so on.

To concatenate values of two or more variables or constants in scripts, use the languag instance, the following script assigns the full path to a file to a variable. The path is c

he file's[VBScript]

Variables.FolderPath = "C:\Work"

Variables.FileName = "myfile.txt"

Variables.FilePath = Variables.FolderPath & "\" & Variables.FileName

[JScript]

Variables.FolderPath = "C:\\Work";

Variables.FileName = "myfile.txt";

Variables.FilePath = Variables.FolderPath + "\\" + Variables.FileName;

[DelphiScript]

Variables.FolderPath := 'C:\Work';

Variables.FileName := 'myfile.txt';

Variables.FilePath := Variables.FolderPath + '\' + Variables.FileName;

If you want to concatenate values of variables and constants using the syntax that is acceptable when specifying operation property values via the Operation Properties dialog, use the ABSUtils.TranslateExpression method in your scripts. For example:

[VBScript]



Variables.FilePath =

ABSUtils.TranslateExpression("%FolderPath%\%FileName%")

[JScript]


Initializing Variables via Command Line 91



Variables.FilePath =

ABSUtils.TranslateExpression("%FolderPath%\\%FileName%");

[DelphiScript]



Variables.FilePath :=

ABSUtils.TranslateExpression('%FolderPath%\%FileName%');

Initializing Variables via Command Line Using the command line interface of Automated Build Studio, you can not only run a macro but also set

appropriate values to custom variables that exist in this macro (See Command-Line Arguments). To do the latter, use the / or - argument. Its format is either /variable_name=variable_value or -variable_name=variable_value, where variable_name and variable_value correspond to the name of the desired variable and the value you wish to assign to it. Only variables that are created via the Variables or Stored Variables dialog can be initialized using Build Studio’s command line arguments. Another requirement for successful variable initialization is that the command line must include the /Run or /RunAndExit argument. For instance, the following command line sets 10 as the value of the IterationNum variable:

AutomatedBuildStudio.exe MyMacro.bbp /ns /RunAndExit /IterationNum=10

Since Build Studio’s command line interface admits several / (-) arguments in one line, you can initialize as many variables as you want. If the string you wish to pass as a value of the specified variable includes spaces, enclose this string in double-quotes, as shown in the example below:

AutomatedBuildStudio.exe MyMacro.bbp /RE /Version=1.0.1 -ReportFileDir="C:\My Projects\Temp"


Integration With Microsoft Visual Studio and MSBuild 92

Integration With Microsoft Visual Studio and MSBuild

Overview Microsoft Visual Studio includes tools and technologies for all members of software development teams:

project architects, developers, testers and managers. Automated Build Studio integrates with and supports these tools giving developers and project managers the possibility to –

• Create, configure and run Build Studio macros directly from Visual Studio’s user interface as you would in Automated Build Studio when it is running as a standalone application. For this purpose, Automated Build Studio panels and toolbars are incorporated into Visual Studio and the main menu of Visual Studio is extended with Automated Build Studio-specific items.

• Extend your Visual Studio projects and team system builds with Automated Build Studio macros.

• Run Build Studio macros directly from your MSBuild projects. You can also compile Visual Studio projects, run MSTest unit tests, work with files stored in Visual

SourceSafe and Team Foundation Source Control and manage Team Foundation work items as a part of your Build Studio macros using special macro operations. This way, you can take advantage of features provided by both Visual Studio and Automated Build Studio and make your build and release process flexible and powerful.

Note for Visual Studio Team System users: To work with Visual Studio Team System, Automated Build Studio uses a special assembly that is installed during the Automated Build Studio installation. The Automated Build Studio installation program automatically determines the Team System version you have and installs the assembly that works with this version. If you have both Team System 2005 and 2008, Build Studio will include the assembly that works with Team System 2005. The assembly that provides support for one Team System version does not work with other versions; for instance, the assembly for Team System 2005 does not support Team System 2008, and vice versa.

If you install or remove Visual Studio Team System or Team Explorer from your computer while having Automated Build Studio installed, you should reinstall Automated Build Studio as well. This will let Automated Build Studio determine the current Team System and Team Explorer version and install the appropriate assembly that works with this version.

Integration With Microsoft Visual Studio Automated Build Studio can be tightly integrated into in the Microsoft Visual Studio IDE. Currently,

Automated Build Studio extends Microsoft Visual Studio .NET 2002, Visual Studio .NET 2003 and Visual Studio 2005. This integration provides developers with full control over Automated Build Studio without leaving the IDE.


Integration With Microsoft Visual Studio 93

Note: Currently, Automated Build Studio does not integrate into Visual Studio 2008. However, Build Studio includes operations that let you compile Visual Studio 2008 projects, manage Team Foundation 2008 work items and work with files stored in Team Foundation 2008 Source Control from your build macros. See Operations Reference.

The integration with Visual Studio means: • Automated Build Studio panels (Macro, Summary, Operations and others) are integrated

into Visual Studio’s IDE. When you open an Automated Build Studio macro in Visual Studio, the layout of the Visual Studio panels and windows are extended with Automated Build Studio-specific panels. When an Automated Build Studio macro is closed, these panels are automatically hidden within Visual Studio.

• A new Automated Build Studio project type is added. You can create Automated Build Studio macros or add them to an existing Visual Studio solution the same way that you create or add other VS projects; by using the Create Project and Add New Project dialogs of Visual Studio. Automated Build Studio macros are displayed in the Solution Explorer along with other Visual Studio projects.

• Automated Build Studio integrates its menus and toolbars into the Visual Studio IDE. Automated Build Studio adds the following menu items and toolbars to Visual Studio’s menu and toolbar system: Automated Build Studio adds the Build Studio menu to Visual Studio’s main menu. This

menu contains commands to start, pause and resume macro runs, modify panel options, schedule macro runs, and so on.

Automated Build Studio also adds the Automated Build Studio toolbar to Visual Studio. This toolbar contains the most frequently used commands: Run, Check Macro, Task Scheduler, and others.

To enhance the functionality of Automated Build Studio and reduce the duplication of commands, shared commands are widely used. For example, most of the standard commands (Select All, Delete, Print, Find, and others) are also applicable to the Automated Build Studio panels.

• Automated Build Studio integrates into Microsoft Visual Studio 2005 Team System. Build Studio associates a macro with each team project. You can use this macro to build projects and solutions that make up your team project, or to perform any other actions. To manage the macro and macro runs, Automated Build Studio adds a new AutomatedBuildStudio node type to all team projects. For more information, see Running Automated Build Studio Macros From Visual Studio Team Explorer.

• Automated Build Studio contributes to the Automation Model. The automation model of Visual Studio provides users with the ability to create custom add-ins, wizards, and to work with macros. As a true VS-integrated product, Automated Build Studio provides program interfaces for its internals. This allows third-party developers to create Visual Studio add-ins, wizards and macros that use Build Studio’s object model.

• Automated Build Studio integrates into the Visual Studio Help system. F1 context-sensitive Help is provided for all Automated Build Studio panels, dialogs and project items. The Dynamic Help window provides a list of help topics specific to the current Automated Build Studio context or task you are currently working on.

• Further integration with Visual Studio. In addition to the core integration, Automated Build Studio supports advanced integration that displays product information in the About dialog box and on the splash screen, Properties window support, integration into Visual Studio’s Start Page, and more.


Running Automated Build Studio Macros From MSBuild Projects

The Automated Build Studio package for integration with Microsoft Visual Studio 2005 includes the MSBuildABSTask.dll assembly. This assembly lets you call Automated Build Studio macros from your MSBuild projects.

The package can be installed on the computer where Microsoft Visual Studio 2005 Team System is installed. To install the package, select Program Files | Automated Build Studio & Server | Integration into Microsoft Visual Studio | Visual Studio 2005 when installing Automated Build Studio on your computer. The installation program automatically registers the assembly in the global assembly cache (GAC).

Below is a typical example of executing an Automated Build Studio macro from an MSBuild project:

File: MSBUILD.proj  <Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

 <UsingTask TaskName="ABS.ExecuteMacro" AssemblyName="msbuildabstask, Version=1.1.0.0, Culture=neutral, PublicKeyToken=550bc1d712c881df"/>

 <Target Name="Build">

 <ExecuteMacro MacroFile="C:\Program Files\MyMacroFileName.bxp" Configuration="Release; Debug" StopIfFail="true" AdditionalOptions="" />

</Target>

</Project>

The example is simple, but it demonstrates two key points in calling an Automated Build Studio macro from an MSBuild project:

• Registration. In order to run Build Studio macros from sample MSBuild projects, you should register a special task type. The registration is done via the UsingTask element whose attributes specify the task name and the name of the assembly that will perform the task. You should always register the task type before using it in an MSBuild project. The registration string should always be the same as it is specified in the sample. You can copy the UsingTask string and paste it to your MSBuild project file. Do not modify this string in your MSBuild project file.

Running Automated Build Studio Macros From Visual Studio Team Explorer 95

• Execution. Upon registering the task type, you can use the ExecuteMacro element to initiate execution of the desired Automated Build Studio macro. To do this, use the ExecuteMacro element. The UsingTask element associates ExecuteMacro with the assembly that will perform the task. The attributes of ExecuteMacro specify the macro name and run parameters: Attribute Description MacroName [in] The full path and name of the macro file to be executed. Configuration [in] A string holding the configuration name(s) that will be used to

execute a macro. If you specify several configurations, the macro will be executed in series, one time for each specified configuration. To separate multiple configuration names, use semicolons.

StopIfFail [in] Indicates whether MSBuild run will fail if Automated Build Studio macro run fails.

AdditionalOptions [in] A string of command-line arguments that are passed to Automated Build Studio along with the macro file name. For more information on supported command-line arguments, see Command-Line Arguments.

Succeeded [out] Returns true if the macro execution was successful, or false otherwise. The following code demonstrates a typical use of this parameter:

<ExecuteMacro …> <Output TaskParameter="Succeeded" ItemName="MSBuild_variable_or_parameter"/> </ExecuteMacro>

For more information on using the [out] parameters, see MSBuild documentation.

Running Automated Build Studio Macros From Visual Studio Team Explorer

Automated Build Studio is tightly integrated with the Team Explorer panel of Microsoft Visual Studio 2005 allowing you to run macros directly from Team Explorer. This topic provides more information on the integration:

About Integration With Team Explorer Requirements Modifying Associated Macro Running the Macro Viewing Results

About Integration With Team Explorer Team Explorer provides an organized view of work items, documents, team builds and reports stored in

the Team Foundation database's project portal. Automated Build Studio associates a macro with each team project. You can use this macro to build projects and solutions that are included in your team project, or to perform any other task you need. To manage the macro and macro run, Build Studio adds a new node - AutomatedBuildStudio - to each team project node displayed in Team Explorer:



The AutomatedBuildStudio node holds two sub-nodes: Macro File and Macro Runs. The Macro File node provides access to the Build Studio macro associated with the project. You can run this macro directly from Team Explorer and view macro run results in Visual Studio. The Macro Runs node is used to initiate and monitor macro runs and to view the macro run results and history.

Requirements The Team Explorer integration package of Automated Build Studio consists of two parts: server and

client. The server includes special assemblies that are installed on the Team Foundation server computer. The client part contains assemblies that act on the computer, where you are working with Team Explorer.

To use the integration: • Install Automated Build Studio on the computer that has Microsoft Visual Studio 2005 Team

Foundation server installed. When installing Build Studio, select Program Files | Automated Build Studio & Server | Team Foundation Server Extension item in the installation wizard.

• Install Automated Build Studio on the computer that has Microsoft Visual Studio 2005 with Team Explorer installed. When installing, select Program Files | Automated Build Studio & Server | Integration into Microsoft Visual Studio | Visual Studio 2005 | Team Explorer Integration item in the Build Studio installation wizard.

We recommend that you install the server part before installing the client. This should be done because of the following Visual Studio 2005 peculiarity: the client part of Visual Studio stores information about available Team Foundation servers in special cache files located on the client computer. The server part of Automated Build Studio’s Team Explorer integration package is installed as a Team Foundation server add-on. If the cached files do not contain information about the add-on, Automated Build Studio will not be able to integrate into the Team Explorer.

If the cache is empty, Visual Studio will populate it with appropriate data upon starting. Build Studio’s installation program clears the cache thus providing automatic cache update upon Visual Studio starts. That is why we recommend that you install the client after the server. If the client is installed prior to the server, the clearing operation will have no effect.



Note that you can clear the client cache manually. To do this, perform the following operations on the client computer.

• Close Visual Studio 2005. • Delete the following folder:

%USERPROFILE%\Local Settings\Application Data\Microsoft\Team Foundation\1.0\Cache

• Launch Visual Studio and add the desired Team Foundation server to the list of available servers.

Modifying an Associated Macro Build Studio automatically creates and associates a macro with each team project. To view or modify

this macro: • Right-click the <team_project> | AutomatedBuildStudio | Macro File node in Team Explorer

and select Open from the context menu. -- or --

• Double-click the Macro File node in Team Explorer. Automated Build Studio will display the Macro Editor window holding operations of the associated

macro. You can add operations to this macro, modify operation properties and perform other actions as you would normally do.

Note: Note that the associated macros are executed on the server side, so specify the appropriate file paths in the operation properties and macro variables.

To save changes made to the macro, select File | Save from the Visual Studio menu or click Save on the Standard toolbar. This will automatically upload the macro to the server.

To upload an existing macro to the server: • Right-click the <team_project> | AutomatedBuildStudio | Macro File node in the Team Explorer. • Select Upload from the context menu. This will call the Open File dialog. • Select the desired macro file in the dialog and press OK. Automated Build Studio will upload

the selected macro to the server.

Running the Macro Macros associated with team projects are executed on the server side (that is, they are executed on the

computer where the Team Foundation Server is installed. You can start the associated macros in one of the following ways:

• Expand your project’s node in the Team Explorer. • Right-click the AutomatedBuildStudio node and select Run from the context menu. -- or -- • Open the Macro Run window (you can do this by right-clicking the <team_project> |

AutomatedBuildStudio | Macro Runs node in Team Explorer and selecting Open from the context menu, or by double-clicking this node in Team Explorer).

• Press Run on the toolbar of the Macro Run window. Automated Build Studio will run the macro and add results to the Macro Runs window after the run is

over (see the Viewing Results section below).



Note: The Macro Runs window is not updated automatically, so to check whether the macro run is over, click Refresh on the window's toolbar.

To stop the macro run, right-click the <team_project> | AutomatedBuildStudio node in Team Explorer and select Stop from the context menu.

Note: If you open the macro for editing (see the previous section) and run the macro from the editor by pressing Run, Run From Selected, Run Selected or Run SelectedWith Children on the editor’s toolbar, the macro will be ran on your computer, but not on the server side. The results of these runs are not added to the Macro Runs window.

Viewing Results Automated Build Studio keeps a log of all macro runs associated with team projects. To view macro run

results, right-click the <team_project> | AutomatedBuildStudio | Macro Runs node in the Team Explorer and select Open from the context menu, or double-click this node in Team Explorer. This will open the Macro Runs window in Visual Studio’s IDE:

This window displays information about macro runs in the following columns: Column Description



Name Name of the run (this name includes the team project name along with the date and time of the run).

Status Specifies the macro run status (Failed or Successfully Executed). Completed on Date and time when the run was finished.

To view the latest information about the runs, click Refresh on the toolbar.

Note: The Macro Runs window is not updated automatically after the macro execution is over. To check whether the macro run is finished, click Refresh on the window's toolbar.

Using the Filter dropdown list, you can filter the displayed runs by date. The Macro Runs window displays brief information about macro runs: name, result (passed/failed), date

and time of completion. To view detailed information about a macro run, right-click it in the Macro Runs window and select Open from the context menu, or double-click the desired run in the Macro Run window. This will bring up Automated Build Studio’s Log panel with messages posted to the log during the selected macro run:


Automated Build Studio Client/Server and Web Interface 100

Automated Build Studio Client/Server and Web Interface

Overview Automated Build Studio lets you start and monitor macros working on other computers in the network.

Typically, to initiate and control remote macro runs you need to use special software (for instance, Remote Desktop Connection) that provides the appropriate access to the remote computer. Features built into Automated Build Studio let you control the remote macro runs without installing any additional software. You can manage remote macros directly from Build Studio. You can even manage the runs without installing Automated Build Studio - the Automated Build Studio Web Interface installed on the remote computer lets you control the macro runs through your Web browser. Of course, Automated Build Studio includes special security settings to limit permissions of users who can view, run or administer the server computer. Note also, that besides controlling remote macros directly from Automated Build Studio or via the Web Interface, you can use the client/server functionality within your macros using operations of the Remote Macro Execution category (for more information on operations of this group see Remote Macro Execution Category in the General-Purpose Operations document or in on-line help).

The remote computers where the macro is running are called servers. The computers where you control the remote macro execution are called clients.

Automated Build Studio is not divided into Client and Server parts. Once you installed Build Studio on your workstation, it can function like a server and a client. The server provides information needed for remote macro runs and the client sends commands to the server. To transfer data and commands between the server and client computers, the Automated Build Studio Service is needed. This service is shipped with Build Studio and is installed by the Automated Build Studio installation program. So, after you installed Automated Build Studio on a computer, this computer automatically becomes a server, which can be controlled by a remote instance of Automated Build Studio.

Automated Build Studio also includes a special Gadget utility that monitors server macro runs from the desktop or Sidebar of Windows Vista. For more information, see Automated Build Studio Gadget for Windows Sidebar.

Using the Client/Server Functionality This topic explains how to run macros and monitor macro execution on a remote computer.

Preparing the Server Computer Connecting to the Server Registering Macros Running Macro and Monitoring the Run Viewing Results Using Server Settings


Using the Client/Server Functionality 101

Setting Permissions

Preparing the Server Computer In order for you to monitor macro runs that are performed on a remote computer (we call it a server), you

need to install Automated Build Studio on this computer. The Build Studio installation program will also install and launch the Automated Build Studio Service.

This service is used to exchange data between the client and server computers. In order to control macro runs on a remote computer, the Automated Build Studio Service should be running on this computer. You can check whether the service is running using the Control Panel | Administrative Tools | Services window.

If the server computer has Windows XP Service Pack 2, Windows Server 2003 or Windows Vista, you may need to turn off the Windows Firewall, or add Automated Build Studio’s service (<Automated Build Studio>\Bin\AutomatedBuildService.exe) to the Exceptions list. For more information, see Automated Build Studio and Windows Firewall.

Connecting to the Server To run a macro on a remote computer, you have to first connect to this computer. To do this:

• Switch to the Client panel. If it is hidden, choose View | Client from Build Studio’s main menu to display the panel (if you use Automated Build Studio integrated into Visual Studio, select Build Studio | Panel List from Visual Studio’s main menu and then choose Client from the ensuing Select Panel dialog).

• In the Location box displayed on the Macro page, specify the the connection which you will use. You can either select an existing connection from the dropdown list, or create a new connection by clicking the Location box's ellipsis button and using the subsequent Connections dialog. In this dialog you can choose the desired connection type and specify the user name, domain and password for the connection. For more information on connection settings, see Connection Parameters.

Registering Macros After you have connected to a server, you can choose the macro, which you will run on the remote

computer. To do this:

• Click Add Macro on the toolbar or the Client panel, or right-click somewhere within the panel’s Macro page and choose Add Macro from the context menu. This will call the Add Macro dialog.

• On the General tabbed page of the dialog, you can specify the macro file name, description, the utility to be used to execute the macro (you can choose either Automated Build Studio or Automated Macro Player) and the command-line arguments for the utility. The macro description specified in the dialog is used to identify the macro in the Client page, that is, it is used as a macro alias. The macro file name is specified in terms of the remote computer, that is, if you specify C:\MyMacros\Macro1.bxp, this will mean that the macro file name is Macro1.bxp and that this file is located on the C:\MyMacros folder on the remote computer. There is no need to share this folder in order to access the macro file. To specify configuration or variable values for the macro run, use the command line. See Command-Line Arguments for more information.

• On the Identification page you can specify the user name, domain and password that will be used to connect to the remote computer. If you do not specify this information, the macro will be



executed using the account, under which Automated Build Studio’s service is running on the server computer (by default, the SYSTEM account). When specifying the account, enter the user name and the domain name. For instance, MyDomain\JohnSmith. You can either type the desired user and domain names, or click Browse and choose the user with the ensuing standard Select User dialog. Note that the specified account must have permissions to run executables on the server computer.

The macro may include operations that use current user account data for functioning (for instance, the operation that checks out files from Visual SourceSafe may use the name and password specified by operation properties, or name and password of the current user account). So, if the login data that you specify in the Notification page does not match the data needed by the operation, the operation execution will fail.

• On the Permissions page you can specify users or user groups, which are allowed to execute the macro and monitor the macro run. These users and groups must be registered on the server with the Server Settings dialog. By default, any users registered on the server, can execute a macro and monitor its runs. If a user does not have the permission for a macro, he will not be able to run the corresponding macro. Depending on the Hide non-available macros option, the macros that users do not have the correct permissions for can be hidden or visible on the Client Panel.

• Click OK in the Add Macro dialog to save changes and add the macro to the Client panel. Using the described steps you can register several macros in the Client panel. If you add the same macro several times, Automated Build Studio will create macro presets and display

them as child nodes of the macro node. The presets differ from each other by the parameters specified in the Add Macro dialog. For instance, they can differ in command-line arguments passed to the macro player before the playback.

Note that Build Studio also supports auto-registering of macros. To enable the auto-registration:

e). • Create a new connection (see abov

Server Settings on the Client panel toolbar. • Click This will call the Server Settings dialog. Select the Automatical• ly register all macros that are run on the server check box on the

gister any macro that will be started on the remote computer. General page of the dialog and click OK to save changes.

Now Automated Build Studio will re



After you have added the macro to the panel, you can run it on the remote computer and monitor the macro run.

RTo run a

• C .

unning Macro and Monitoring the Run macro added to the Client panel:

hoose the desired macro in the Macro page of the panel

• Right-click the selected macro and select Run from the context menu or click the Run button on the panel's toolbar.

Automated Build Studio will start running the macro on the remote computer. The State column of the Macro page will indicate the run status.

To view detailed information on the macro’s execution progress, select the desired macro in the Macro page and switch to the Progress page. This page indicates the execution progress using progress group defined in the macro being run. If the macro does not contain progress groups, the page will be empty.

Note: The Client panel will monitor all macro runs: those that will be initiated from the Client panel and those that will be initiated outside of it. In other words, you will see macro runs that will be

user who will log on the remote computer.

lt, this number is 5. So, if Automated Build Studio is running 3 macros on the remote computer and you command to run 4 more macros from the Client panel, only 2 of these four macros will be run. The other two macros will be placed in a queue and will wait until the total number of running macros decreases.

Using the Maximum concurrent macro runs option lets you avoid too massive of a load on the server and provides a simple way to control the macro run order: if this option holds 1 and you run five macros from the Client panel, the macros will be executed one-by-one on the remote computer in the order of their run.

Viewing Results After the macro execution is over, the State column of the Macro page will indicate the macro run

results (Failed or Success). The Configuration column will show the configuration used to build the macro, Last run will indicate the date and time of the run start, Execution time - the run duration.

started by a

Note that Automated Build Studio lets you limit the number of macros running concurrently by setting the appropriate value to the Maximum concurrent macro runs server option. This option lets you specify the number of macros that can be started from the Client panel and run concurrently. By defau



To view detailed information on macro run results, click the word (Failed or Success) displayed in the State column. Automated Build Studio will load the run results to the Log and Summary panel.

To view the history of macro runs, choose the desired macro in the Macro page and then click Show in the History column of that page. Build Studio will retrieve the history of the macro runs from the remote computer and then it will display the History page with the retrieved data.

The Message column displays text describing the execution result. If the macro failed to execute

successfully, the column will display the error description. By clicking the Log column of the History page, you can view the log of the appropriate macro run.



SettingYou ca m

runs or adminis n” means users will be able or unab

To operate the server:

• Ope

• ic

Permissions n li it the number of users who are able to run macros on the remote computer, monitor macro

ter the Build Studio settings on the remote computer (“administratiole to change permissions for the remote computer through the Client panel).

with permissions, you should first create users and user groups that are allowed to work with

n the Client panel.

Cl k Server Settings on the panel’s toolbar and use the subsequent Server Settings dialog to create users and user groups and specify to which group a user belongs.

permission system is based on the following principles: Users can be authorized by their name and

The password specified in the Server Settings dialog,

r user groups only. User-level permissions are not supported. So, to specify permissions for a user, add it to a user group.

A user can belong to only one group.

or by the name and password of their operating system account. Permissions are specified fo



•

page.

After you defined the users and user group, you can specify access permissions for individual macros – you can specify the macro to be run by only certain users. To do this: Select the desired macro in the Macro Right-click the selected macro and choose Edit Macro Properties from the context menu,

or simply click Edit Macro Properties on the panel's toolbar. This will call the Macro Properties dialog.

s to run this macro preset check box.

AutomateAutoma

loss (for insunauthorized a nt/Server subsystem includes special permissionsInterface.

The per• Client panel or Automated Build Studio Web

the server, the client part of Automated Build Studio uses the settings specified in

• A u e and password specified in the Server Settings dialog, or by t n account. The authentication type is selected in the rv

• A u c• Permiss ps. User-level permissions are not supported.

A g p Run

Aut

comrun permission is useful when a user has to modify input data

permission

nd delete them from m the server to the

e them back to the server. This permission naturally includes the Modify mac r

Adminuser gro

Switch to the Permissions page. cific user Select the Allow the spe

Click Add User or Add Group to add the desired users or user groups to the list of users. Click OK to save changes.

d Build Studio Client/Server – User Permissions ted Build Studio macros let you perform various actions, including those that can lead to data tance, Automated Build Studio includes operations that can delete files or folders). To prevent

ccess to these macros and operations, the Clie that restrict actions a user can perform through the Client panel or Automated Build Studio Web

missions subsystem is based on the following principles: The operations a user can perform through the Interface are specified by the user permissions in the Server Settings dialog.

• To connect to the Connections dialog.

ser can be authorized by user namhe ame and password of the operating systemSe er Settings and Connections dialogs. ser an belong to only one group.

ions can only be specified for grourou can have any combination of the following permissions:

macros - Users having this permission can run macros from the Client panel or omated Build Studio Web Interface, pause and stop macro runs.

Modify macro run parameters - Users that have this permission active can only modify mand-line arguments of a macro. For instance, specify the desired configuration for the

or initialize variables. This(which is not allowed by the Run macros), but assigning him the Manage macrosis undesirable. Manage macros - Users having this permission can register macros on athe client computer, modify the macro properties, download macros frocli nt and upload

ro un parameters permission rights. ister server - Users having this permission can register and unregister new users and ups on the server.


Automated Build Studio Client/Server – User Permissions 107

To monitornon-availabbe hidden o on the Client Panel.

The general proceduAutomated Build Studio ned user or user groups for th s

• You (or any o this, you do not need

On the panel’s Macro page, click the ellipsis button of the Connection edit box. This will g. The dialog will guide you through the process of creating the

on. On the next two pages pecify the connection type (DCOM or Web service) and settings (computer name or

lick

macro executions, users do not need special permissions. Depending on the Hide le macros option, the macros that users do not have the correct permissions for can r visible re for creating users and user groups is as follows. In our explanation we assume that has just been installed on the server computer and that you have not yet defi

is erver. other user) create a connection to the remote computer. To d

special administrator permissions. Open the Client panel.

call the Connections dialoconnection.

On the first page of the dialog, specify the name for your connectiyou sURL).

On the fourth page you have to specify the authentication parameters. Select Authenticate as the logged on Windows user and click Finish.

Automated Build Studio will create a new connection and automatically select it in the Connection box of the Client panel’s Macro page.

• You will be added to the EVERYONE group. By default, users belonging to this group have all the permissions for the client/server operations.

Server Settings on the Client panel's toolbar. This will call the Server Settings dialog.

ensuing Add Group dialog. Note that the group name cannot coincide with another

appropriate group (this group should have the Administer server permission). This will

nly monitor macro runs, but not start, stop,

- In the dialog: - Specify the user name and password:

- If you want a user to be authenticated by the operating system, select the Windows user check box and then enter the user name (including the domain) into the User name edit field in the format DomainName\UserName.

• C• In the dialog:

Create the user groups and specify their permissions: - Switch to the Groups page. - Create the new groups by clicking Add. - Specify the group name and permissions using the check boxes at the bottom of the

group name or with a user name. - If you will be the Build Studio server administrator, add your user name to the

automatically remove your user name from the EVERYONE group. - Select the EVERYONE group and clear all the check boxes at the bottom of the page, so

users belonging to this group will be able to odownload or upload them.

Create new users and add them to the created groups. To do this: - Switch to the Users tabbed page. - Click Add to create a new user. This will call the Add User dialog.



You can either enter the desired user and domain names or click the ellipsis button of the User name box and choose the user using the subsequent standard Select User dialog. - If you want a user to be authenticated by the Automated Build Studio server, clear the Windows user check box and type the desired user name and password.

- In the Group edit box specify the group, to which the user will belong. - Click OK to add the new user with the specified properties.

After you finish creating users and groups, click OK to close the Server Settings dialog.

Connection Parameters You can connect to the remote computer using one of the following methods:

• DCOM • Web service (SOAP)

Below are descriptions of these connection methods. After the descriptions we will also describe which connection type to choose.

In order for you to be able to establish the connection to the server computer, you may need to prepare this computer in the appropriate manner. For more information on this, see Preparing the Server Computer section of the Using the Client/Server Functionality topic.

DCOM DCOM (Distributed Component Object Model) is a protocol that enables software components to

communicate directly through t does not require any additional runtime applications on the server, sinc supported by Automated Build Studio (see System Req

Using the DCOM connection you can only connect to those computers that belong to the domain, to which your computer belongs. Within the domain range, the DCOM connection is faster than the Web service connection.

When establishing the DCOM connection to the remote computer, you need to specify the desired computer name. In order for Build Studio to establish the connection, the computer must meet the following requirements:

• The Automated Build Studio Service must be running on this computer. This service is used to exchange data between the client and server computers. It is part of Automated Build Studio and is installed by the Build Studio installation program.

• The DCOM options must be set properly: Open the Control Panel | Administrative Tools | Component Services window. Right-click the Console Root | Component Services | Computers | My Computer node in

the tree on the left of the window and select Properties from the context menu.

he network. Ite DCOM is an integral part of the operating systems uirements).


Connection Parameters 109

This will call the Computer Properties dialog.



Activate the COM Security page of the dialog.

ess Permission section. This will call the Access Permissions Click Edit Limits in the Accdialog.


Connection Parameters 111

Make certain that the user account, which you will use to connect to the server computer, is

added to the Group or user names list and that the Remote Access permission is enabled for it. You can set this setting for the Everyone user group to enable all domain users to

u specify in the

connect to the build server. Do not confuse this user (or user group) name with the name and group yoServer Settings dialog. The Server Settings dialog defines the name that is used to connect to the remote Automated Build Studio, while in the Access Permissions dialog you specify the account, used to connect to the remote computer.

Click OK to save the changes and return to the Computer Properties dialog. Click Edit Limits in the Launch and Activation section. This will call the Launch

Permissions dialog:



Make certain that the user account, which you will use to connect to the server computer, is

added to the Group or user names list and that the Remote Activation permission is enabled for it. You can enable this setting for the Everyone group to enable all domain users to connect to the build server. Do not confuse this user (or user group) name with the name and group you specify in the Server Settings dialog. The Server Settings dialog defines the name that is used to connect to

Click OK to save the changes and return to the Computer Properties dialog. Click OK in the Computer Properties dialog to close it.

ongs or does not belong to the domain of the client computer. I

messages. When e

the http://ComputerName/VirtualDirectoryName format, for instance:

the remote Automated Build Studio, while in the Access Permissions dialog you specify the account, used to connect to the remote computer.

Web service (SOAP) This connection type lets you connect to any computer where Automated Build Studio is installed

regardless of whether this computer belf you select this type of connection, the client and server computer will communicate through SOAP

stablishing the connection to the remote computer, you need to specify the URL connection in

http://JohnSmithComp/AutomatedBuildStudio

Here JonSmithComp is the server computer's name and AutomatedBuildStudio is the virtual directory name. This is the default virtual directory created by Build Studio's installation program.


Automated Build Studio Client/Server Web Interface 113

Note: Do not confuse the names of the virtual directories. The virtual directory name of the

er

In o ust meet the following requirements

• The Au ce is used to exchange data between client and server co o and is installe

• The rem et Information Services 5.1 or later installed

Automated Build Studio.

WhichUsi can only connect to those computers that belong to the domain, to

which yourservice conn

Using t you are not limited by the domain bounds. - you can connect to computers th to choose this connection t ur computer.

eb Interface

ieClieobtains tahave to inst

Automabrowser his installed o

RequirTo use Automated Build Studio Web Interface, the server computer must have the following software

installed: • Mic

with essional, Microsoft Windows Server 2003 or

• Autinclinst

•

• Microsoft Data Access Co

Automated Build Studio Server is AutomatedBuildStudio, while the virtual directory name that is used to access the Automated Build Studio Web Interface (if it is installed on the servcomputer) is AutomatedBuildStudioWeb.

rder for Build Studio to establish the connection, the server computer m:

tomated Build Studio Service must be running on this computer. This servimputers. It is part of Automated Build Studi

d by Build Studio's installation program. ote computer must have Microsoft Intern

and must have the virtual directory providing access to the appropriate Build Studio modules. This virtual directory is created by the installation program of

Connection Type to Choose ng the DCOM connection you

computer belongs. Within the domain range, the DCOM connection is faster than the Web ection.

he Web service connection at do not belong to the domain containing your computer. So, you have

ype if the server computer does not belong to the domain containing yo

Automated Build Studio Client/Server Web Interface

About Automated Build Studio WAutomated Build Studio includes client and server functionality (see Automated Build Studio

Cl nt/Server - Overview). To execute and monitor macros running on the server computer, you use the nt panel of the Build Studio instance running as a client. The client code connects to the server computer,

da from it and displays this data in the Client panel. In order to work through the Client panel, you all Automated Build Studio on your computer. ted Build Studio's Client/Server Web Interface lets you control the server through your Internet

(t at is, without installing Automated Build Studio on client computers). The Web Interface module n the server computer and generates web pages that you access through your Internet browser.

ements

rosoft Windows 2000 Professional with Service Pack 4, Microsoft Windows 2000 Server Service Pack 3, Microsoft Windows XP Prof

Microsoft Windows Vista. omated Build Studio with Automated Build Studio Web Interface (the Web Interface is uded in Automated Build Studio and it can be installed during Automated Build Studio allation).

Microsoft Internet Information Services ver. 5.0 or later. mponents 2.8 or later.



• Microsoft .NET Framework 2.0. Adobe Flash• Player 8 or later.

tion Services should be installed prior to Microsoft .NET

mrowser options to ensure that this support is enabled.

Using Web Interface To view a page generated by the Web interface, open your Internet browser and navigate to the following

page:

Note that Microsoft Internet InformaFramework 2.0.

As for the client side, the web browser, in which you will browse the pages generated by Web Interface, ust support cookies and JavaScript. This kind of support is built into most modern browsers. However, you

may need to check b

http://ServerName_or_IP/AutomatedBuildStudioWeb

As you can see, you can specify the server computer using either its name or IP address. AutomatedBuildStudioWeb is the virtual directory holding the pages generated by the Web Interface

module. AutomatedBuildStudioWeb is the default directory name. You can change it when installing Build Studio on the server computer or any time later using the Internet Information Services dialogs and windows.

Note: Do not confuse the names of the virtual directories. The virtual directory name of the Automated Build Studio Server is AutomatedBuildStudio, while the virtual directory name that is used to access the Automated Build Studio Web Interface (if it is installed on the server computer) is AutomatedBuildStudioWeb.

After you enter the specified address, you will see the Login page asking you to specify the authentication parameters for login.

The next page after the Login page is very similar to Automated Build Studio’s Client panel. You can use it in the same manner as you use the Client panel. For more information, see Using the Client/Server Functionality and Automated Build Studio Client/Server - Common Tasks (in on-line help).

The page also contains a section similar to the Charts panel. This section graphically represents statistics on macro runs that were performed on remote computers.

Automated Build Studio Gadget for Windows Sidebar Automated Build Studio version 4 provides you with a new feature, called Automated Build Studio

Gadget, which helps you monitor macro execution under Windows Vista. This topic describes how to set it up and how to use it.

Overview Gadgets are lightweight html-based applications that usually indicate process data. For example, time,

resource load, RSS feeds and so on. The gadget supplied with Automated Build Studio allows users to monitor macro runs in real time.

The gadgets concept was introduced in Microsoft Vista. When installing Build Studio on this platform, you can enable the Automated Build Studio Gadget for Windows Sidebar item. After installation the gadget becomes available in the Gadget Gallery. It can be placed on the Windows Sidebar or anywhere on the desktop.


Automated Build Studio Gadget for Windows Sidebar 115

The gadget displays a list of registered macros on a local or remote computer and for each macro it

shows the information about its progress or results. Depending on the Show additional information in the main windo t line. The data is regula e update interval could be changed via the settings dialog. However, the size and to scroll through the list items use the up and down buttons in the lower right corner.

n additional window with details: if the macro is being executed at that mo n indicates the current progress state, otherwise it displays the history of previou n

w optiorly upd

n, this information can be represented as popup hint or as a supplementary texated. By default the gadget gathers data every 5 seconds, but th

minimal interval is 1 second. The gadget window has a fixed

A click upon a macro name invokes ame t, then the windows ru s.

T yed by a gadget is similar to the data shown by the Build Studio Web Interface, however

the gad . To control the server via the Web Interface, click the server name in the in the gadget’s lower left corner. This will call the default internet browser and navig

No is specified by the Web Interface URL property erverName_or_IP/AutomatedBuildStudioWeb,

Connection Parameters ection parameters are empty and the gadget shows information about the macros on ever you can explicitly define the monitored computer in a settings dialog box:

he data displaget only monitors macro runs and does not control them

ate to Web Interface logon page.

te: The address of the Web Interface logon pageof the settings dialog. By default it is http://Showever, the alias name (AutomatedBuildStudioWeb) can be redefined during the installation on a target machine.

By default, the connthe local computer. How

1. Right-click the gadget and choose Options in the context menu, or press the Settings button.



2. In the dialog, select the connection type in the Connect via radio group.

Tip: If the computer where you connect, resides in your local network and belongs to the same domain that your computer belongs in, select DCOM.

Server name (DCOM) or Web

d that you use to

– or – Enter the desired user name and password in the corresponding fields.

•

If the computer where you connect does not belong to the domain that your computer belongs in, select Web service.

To connect to a remote computer, it should be properly configured beforehand. Read the Connection Parameters topic for instructions how to do this.

3. Depending on the chosen connection type, specify a value in theservice URL (Web Service) field.

4. Specify user credentials. Check the Authenticate by OS to logon with the same username and passworlog into your computer.

Managing Monitored Macros The gadget control monitors the macros that are registered in a special way. However, to manage the list

of monitored macros you should use the Client Panel of a Build Studio or Automated Build Studio Client/Server Web Interface.

To register a macro, do the following:

Add Macro button on the Client panel oClick the r Web Interface toolbar. This will call the Add Macro dialog, where you can specify the desired run settings.

page of the dialog you can specify the macro file name by typing it in the ou can also click the ellipsis button of the Macro

ng Select File dialog. ain of the user account

the account data, the server

choose the user

e Identification page does not match the data needed by

will be allowed to run

• On the General tabbedMacro file name edit box. To specify the file, yfile name box and choose the desired file in the ensui

• On the Identification page you can specify the name , password and domthat you want the macro to be executed under. If you do not specifyexecutes the macro using the account that is running Automated Build Studio’s service (by default, this is the SYSTEM account). Three notes: Specify the user name along with the domain name. For instance, MyDomain\JohnSmith.

You can either type the desired user and domain names, or click Browse andwith the ensuing standard Select User dialog.

The macro may include operations that use current user account data for functioning (for instance, the operation that checks out files from Visual SourceSafe may use the name and password specified by operation properties, or name and password of the current account). So, if the login data specified in ththe operation, the operation execution fails.

The specified account must have permissions to run executables on the server computer. • On the Permissions page you can specify the user groups and users, who

the macro. • Click Finish to close the Add Macro dialog.


Automated Build Studio Gadget for Windows Sidebar 117

To remove a macro from the list of monitored macros, selecct a macro in the Client panel or Web Interface and click the Remove Macro toolbar button. To change the macro properties, select it and press

Edit Macro Properties button. This will call the Macro Properties dialog where you can change whatever parameter you like.


Charts 118

Cha t

Ch

successful and failed runs, check the runs activity and organize macro runs. available if the Collect information about macro runs

• Duration of the macro run. e user, who initiated the macro run.

can view macros run

r s

arts – Overview Automated Build Studio can collect information about macros running on your computer and display the

information as graphics in the Charts panel. You can use this information to analyze the run statistics, determine the ratio of

Note: The statistical data is macro property is enabled. By default this property is enabled.

Build Studio logs the following data:

• The macro name. • Configuration used for the run.

• Date and time of the run.

• Name of thAutomated Build Studio displays this information using one of several chart types. You can view

statistics for all macros that were run on your computer, or only for one macro. Youning by all users or by some specific user. Of course, you can specify the date range for displaying the

statistics. The following topics provide detailed information about this:

Charts Panel Describes the Chruns that were pe

arts panel and contains information about viewing and printing statistics of macro rformed on the current or remote computer.

Chart Types Explains chart types used by Automated Build Studio.

Viewing Charts Data Stored on Another Computer Viewing charts data stored on another computer.

Moving Charts Data From One Computer to Another Explains where Build Studio stores data displayed in the charts panel and describes how to move them from one computer to another.

Automated Build Studio collects information on macro runs performed on your computer and displays it in graphical form in the Charts panel. Use this panel to analyze accumulated statistics, estimate the builds

Charts Panel


Charts 119

pro

any of the following:

ct Panel dialog, which is called by selecting View | Select Panel

Bui

• n - Let’s you compare the execution time of different macro runs. • Build Frequency - Let’s you explore the load (macro runs) on your computer.

):

gress and determine the better time for running your macro. Using the panel, you can also view statistics on macro runs that were performed on another computer.

If the Charts panel is hidden, you can make it visible by doing• Select Charts from the View menu. • Select Charts from the Sele

from the menu of Automated Build Studio, or by selecting Build Studio | Panel List from the main menu of Visual Studio.

ld Studio displays the gathered information using several chart types: • Build Results - Provides general view of macro run statistics.

Build Duratio

The following image displays a sample view of the panel (the Build Duration chart type

Specifying the chart type The name of the currently selected chart type is displayed at the top of the panel. You can switch

between different chart types by clicking the arrows shown to the right and to the left of the active chart type name or using the Right and Left arrow keys as shortcuts.

You can also click Chart type at the top-right corner of the panel and choose the desired type in the ensuing Select Chart Type dialog.

For more information on chart types, see Chart Types.

Specifying the date range To specify the date range for the data that is displayed:


Charts 120

• Click Data type at the top-right corner of the panel. • Choose the desired period in the ensuing Select Date Range dialog.

By clicking the arrows shown on the left and on the right of the date range, you switch to the previous or ast month in the Select Date Range dialog, clicking the left and the previous and next months. If you select custom range, then

to the next number of the days that are included into the

io logs information about the macro name and configuration that only

• C default, the link’s text is All macros). This will invoke the Select Macro and Configuration dialog. This dialog lists the macro-

pair and click OK. You can also the arrows that are shown to the left

and to e Shift-Right and Shift-Left shortcuts.

To cro runs performed by a user A tracks macro runs performed by all users who work with Automated Build

Stud Player on your computer. By default, the Charts panel does not filter the macro run by t

nd link in the top-left corner of the panel (by default, the link’s text is All

acros on

You can also view results for users by clicking the arrows that are shown to the left and to the right of the link or wit

To cro runs performed on another computer U el you can view statistics on macro runs that were performed not only on your

comput n, Automated Build Studio S must be installed and running on the remote computer.

T the panel (by default, the link’s text is Local).

This will invoke the Select Server dialog. can also click the

mputer dialog. • Click OK to close the Select Server dialog. Automated Build Studio will retrieve data from the

mputer and display it in the Client panel.

next period. For instance, if you select Lright arrows you can view statistics for clicking on the arrows will return or advance the view

specified range. Also, you can switch the date range with the Up and Down arrow keys.

View results for one macro and configuration only For each macro run Automated Build Studwas useview re

d for the run (see Charts - Overview). By default, the charts display results for all macros. To sults for one macro and configuration:

lick the third link in the top-left corner of the panel (by

configuration pairs. • In the dialog, choose the desired macro-configuration

switch between macro-configuration pairs by clicking the right of the link or with th

view mautomated Build Studio

io or Automated Macro he name of the user, who started the run. To view results only for one user: • Click the seco

operators). This will invoke the Select Operator dialog. This dialog lists names of users who run myour computer.

• In the dialog, choose the desired user name and click OK.

h the Shift-Up and Shift-Down shortcuts.

view information on masing the Charts pan

er, but on other computers in the network. In order for the panel to be able to display this informatioervice

o view results stored on another computer: • Click the left link in the top-left corner of

• In the dialog, specify the name of the desired computer or its IP address. You ellipsis button and choose the computer in the ensuing Browse for Co

specified co


Charts 121

To zoom in the view • Press the left mouse button to and drag the mouse pointer toward the right bottom corner to mark

the area to be enlarged.

• Press the left mouse button to and drag the mouse pointer towards the top-left corner. n.

ChAut a

the Charts p

•

•

ng arro

hint displaying detailed information appears. pe you can see statistics and ratio of successful/failed builds and determine the builds

pro

When this type is selected, the Charts panel displays statistics about how long it takes for macro runs to execute. The horizontal axis displays dates and the vertical axis displays the run duration.

• Release the mouse button when you specified the area to be enlarged.

To zoom out the view

• Release the mouse butto

To print the chart • Select the desired chart type and date range (see above for more information on this). • Right-click somewhere within the chart and choose Print or Print Preview from the context

menu. The Print command will open the standard Print dialog, from which you can send data to the printer. The

Print Preview command will open the Print Preview Form, in which you can customize the chart before printing it.

art Types om ted Build Studio collects information about macros running on your computer and displays it in

anel using one of the following chart types: • Build Results

Build Duration Build Frequency

The name of the currently selected chart type is shown at the top of the Charts panel. To choose a chart type to display, click Chart type at the top-right corner of the Charts panel and then

choose the desired type in the ensuing Select Chart Type dialog. You can change the chart type by clickiws on the right and on the left of the currently selected chart type or by pressing the Right and Left

arrows on keyboard.

Build Results When this type is selected, the Charts panel displays the bar diagram of successful and failed macro runs.

The horizontal access displays dates and the vertical axis shows the number of runs. Each bar represents a day in which at least one macro run was performed. The lower section of the bar corresponds to successful macro runs, the upper section corresponds to failed runs. When you moved the mouse pointer over a bar, a

Using this chart tygress.

Build Duration


Charts 122

Each run is represented by a dot. To view informthe mouse pointer over that dot. Build Studio will sh

ation on the run, that corresponds to a dot, simply move

horizontal axis displays dates and the vertical axis shows the time (from 00:00 to 23:59). Each run is represented by a dot. To the

charts, see Charts Panel.

ViewThe Ch

accumulated er as well as from any other computer on the network. he panel to be able to retrieve statistics from the remote computer, Automated Build Studio

must be installed on that co

Cle of the currently selected computer. By default, the caption is Local.

•

m One Computer to Another

s data in .xml files located in the following folder:

n Data\AutomatedQA\Automated Build l

Each .x puter. The BuildHistory.xml file is the “main” file

The cha ation about macro runs macro property is ena

ow the run information in a hint. Using this chart type you can find the slowest macro runs and determine when they happened. This

information will help you find the reason of the slowdown.

Build Frequency When this type is selected, the Charts panel displays information on how often builds are performed. The

view information on the run, that corresponds to a dot, move the mouse pointer over dot. Automated Build Studio will show the information in a hint. Using this chart you can find time periods when your computer is the most busy and choose the time for

your builds. For more information on viewing

ing Charts Data Stored on Another Computer arts panel displays statistics on macro runs in a graphical form. The panel can display statistics from your comput

In order for tmputer, the Automated Build Studio Service must be running and the macro must

have the Collect information about macro runs property enabled. To view charts that are built on statistics stored on a remote computer:

• Switch to the Charts panel. • ick the leftmost link at the top-left corner for the panel to select the computer. The link caption

specifies the nam• Specify the desired computer’s name or IP address in the ensuing Select Server dialog.

Click OK to close the dialog. Automated Build Studio will display the macro run statistics in the Charts panel.

Moving Charts Data FroAutomated Build Studio can collect information about macros running on your computer and display it

as graphics in the Charts panel. You may want to move the collected data to another computer and view it there or send the accumulated results to your team members for review.

Build Studio stores the chart

<Documents and Settings>\All Users\ApplicatioStudio\Bui d history

ml file corresponds to a macro that was run on your comand it contains references to other .xml files. rts data for a macro is available if the Collect inform

bled on the target computer. By default this property is enabled.


Charts 123

To move the charts data to andesired computer. Note that you should paste the fil

other computer, simply copy the contents of the Build history folder to the es to the same folder on that computer. Also, this

computer must have Automated Build Studio installed on it.


Debugging Macros 124

D Debugg fix logical errors and check whether your macro functions correctly. Automated

Build S doperatio , debugging m

Note: allow

ebugging Macrosing lets you

tu io’s macro debugger includes all modern debugging features: breakpoints, stepping over ns watches, expression evaluation, and so forth. The following topics provide more information on

acros in Automated Build Studio. With Automated Build Studio you can only edit MSBuild projects, since it doesn't running and debugging these projects. So, all debugging features are turned off when you are editing an MSBuild project in Automated Build Studio.

Debug utomated Build Studio ging Macros in A Provides information on how to use the macro debugger.

Stepping Trough The Macro Describes how to step over operations or trace into a group of operations during the debugging process.

Running to the Cursor p the macro execution on the currently selected operation in the Macro panel.

Describes how to sto

Using Breakpoints Explains how you can create and use breakpoints and how to modify their properties.

Conditional Breakpoints Describes how you can create and use conditional breakpoints.

Watches Panel Provides information on the Watches panel and devariables and expressions.

scribes how you can use it to watch values of

Br kPro n on the Breakpoints panel and describes how you can use it to debug macros. ea points Panel

vides informatio

Ev uDes

Debugging Macros in Automated Build Studio

t d B

halting the macr question, and the cution, stopping at those same lines. Every

al ating Expressions cribes how to evaluate expressions.

AbouAutomate uild Studio provides a macro debugger as an aid in developing macros. Debugging refers to

o execution at certain lines, with the Macro panel automatically highlighting the line inn running through the macro in step with the exe



time the he

debugge as check or change t

sect

r All b

Build Studcontains the ese is the equivalent of a Run Macro button, but with run, execution starts at the top of the first executed routine. But after each sto tway of sele if the

r stops somewhere, there are several things it will allow you to do, suchvalue of variables, but, merely stopping before certain lines is often a great help in tracking what your

macro is doing. Note that all debugging features are turned off when you are editing an MSBuild project in Automated

Build Studio. With Build Studio you can only edit these projects, since it doesn't allow running and debugging them. See the Working With MSBuild Projects document or the Working With MSBuild Projects

ion in on-line help.

Using the Macro Debuggede ugger actions are available from the Debug menu, toolbar or shortcuts (In Visual Studio, from the

io | Debug menu and the Automated Build Studio toolbar). The left part of the Debug Toolbar execution choices of the debugger. Each of th

two differences. First, on a newp i will resume at the line where the debugger stopped. Second, each execution choice is a different

cting the next line that the debugger will stop on. These facilities function only Enable Ma

Wh d Show on macro start option of the Summa p start. You can turn on the Highlight operatio o ation currently being executed so you can easily trace the macro execution path.

The two main ways of macro debugging: p before every enabled operation in the macro. There are two variations,

cro run if the selected operation is never executed.

macro where you want the macro to pause during execution. Once the execution is paused d its variables.

ou do not have to set the curs conditio ger stops only if, at that point in the run, a certain condition you defined is true. See Using Breakpoints.

. You ca of any expression you can define with ava l pan

Possible Issues When debugging macros in Automated Build Studio, keep in mind that the Highlight operation option

slows the macro execution speed. As well as monitoring many expressions at once in the Watches panel, especially if they involve a lot of calculations.

cro Debugging item is pressed. en ebugging macros, it is recommended that you turn off thery anel, to disable activating the Summary panel upon macron ption of the Macro panel, to command Automated Build Studio to highlight the oper

• The debugger can stotracing or stepping over. See Stepping Through the Macro.

• The debugger can run through the macro from the current execution point, without stopping, to the macro operation that the cursor is on. Execution will stop just before that line. This is one way of going straight at suspect code. See Running to the Cursor for more information. Note that execution will not stop until the end of the ma

Operations can also be preset for the run to stop when they are reached. These operations are called breakpoints. A breakpoint is a location set in your

, you can check the state of the macro, its output anSetting a plain breakpoint is the same as running to the cursor, except that yor at the operation (it is memorized) and you can have several breakpoints. You can also have

nal breakpoints, where the debug

Once you have halted the execution, you can check the value of variables and expressions in two waysn use the Evaluate dialog, which lets you find the value

ilab e variables and constants and the usual arithmetic and logical operators, or by using the Watchesel where you can set up a list of these expressions to be evaluated every time the macro execution stops.



Stepping Through the Macro Stepping means executing just one macro operation, then stopping (until the next step) to check the state

of the macro, its output and its variables. The next operation to be executed is highlighted in the Macro panel.

There are two ways to step through the macro, depending on what is meant by “executing just one operation” when that operation contains a call to a sub-macro: Trace Into or Step Over.

Trace Into

cro operation), Automated Build Studio jumps to the first operation of acro and stops there, ready to step through it again, one operation at a time. After Build Studio has e end oto the

•

Under Trace Into, execution proceeds one operation at a time. If the operation contains a call to a sub-macro (for example, the Run Submathat sub-mreached th f the sub-macro, it jumps to the operation following the operation that called the sub-macro.

macro, press either: To trace in T t

VisuThe Borla Keyb

ep O i execution point is single step (full s To step over the macro (sub-macro), press either:

race Into on the Debug toolbar (or from the Automated Build Studio toolbar in Microsofal Studio).

• Trace into shortcut. For the MS Visual Studio IDE keyboard scheme, it is F11, for thend IDE scheme - F7. You can also change the assigned shortcut via the Customizeoard dialog.

Step Over Under St ver, execution proceeds one operation at a time with n the macro or sub-macro where the

now located. If the next operation contains a sub-macro call, the whole call is executed in apeed, no stop), and execution stops at the next operation in the current macro (sub-macro).

• Step Over on the Debug toolbar (or from the Automated Build Studio toolbar in Microsoft Visual Studio).

• The Step Over shortcut. For the MS Visual Studio IDE keyboard scheme, it is F10, for the Borland IDE scheme - F8. You can also change the assignedKeyboard dialog.

shortcut via the Customize

Runnin Select the first suspected spot, test up

to it (th i acro output and macro variables are as expecte n ed is highligh

operation where you want to run your first check. The

g to the Cursor Running to the cursor is the easiest way to use the macro debugger.

at s, run at normal speed, no stopping), check that the md, a d if ok, select a new check spot to test up to. At each stop, the next statement to be executted in the Macro panel.

To do this, switch to the Macro panel and select the n sta th s: rt e macro run using either of these method

• Press Run Macro To The Cursor Position on the Debug toolbar (or from the Automated Build Studio toolbar in Microsoft Visual Studio).

ursor Position shortcut key. The default shortcut is F4, though it ize Keyboard dialog.

• Press the Run Macro to the Ccan be changed via the Custom

Then, check the state of the macro, its variables and results, select the new stop operation in the macro and select Run Macro To The Cursor Position again.



Usant the script to pause during execution. Once

executio is

Bre o

ing Breakpoints A breakpoint is a location in your script where you w

n paused, you can check the state of the script, its output and its variables.

akp ints only function if the Enable Macro Debugging item on the Debug toolbar is checked ated Bui(the Autom ld Studio toolbar in Microsoft Visual Studio). If this item is unchecked, the macro

executio w paThe bre

dependent o nal expression. nd the macro execution reaches it

(in a normal run or using the debugger), execution will stop just before the breakpoint operation. This ope the Macro panel. If a breakpoint is disabled, Automated Build Studio does not

After the pause, you can resume the macro execution, or use one of the debugger execution options for further checking.

To set a breakpoint on an operation, select the desired operation in the Macro panel and click the left margin of the operation line. When you set a breakpoint, the corresponding operation is highlighted in red, and the

n ill not use on breakpoints. akpoints list is kept for each macro. Each breakpoint can be enabled or disabled and made n a condition - like a pass count or a conditio

When a breakpoint is enabled with the optional condition set to true, a

ration will be highlighted in stop the macro execution. At any stop you can check the environment state as well as the macro output and the state of its

variables. Using breakpoints is the easiest and most flexible way to preset spots in your macros where you want to perform these types of checks.

icon appears in the left margin of the operation line. Setting breakpoints is a toggle, so repeating the set on the same line will remove the breakpoint.

To set a breakpoint on an operation, select the desired operation in the Macro panel and then use one of the following methods:

• Click the left margin of the operation line. • Press the Toggle breakpoint shortcut. (By default, F9. You can change the assigned shortcut via

the Customize Keyboard dialog.) To work with the list of all breakpoints for the current macro, use the Breakpoints panel. This panel

allows you to enable, disable or delete breakpoints. To modify breakpoint properties, use the Breakpoint Properties dialog. To call it, right-click the breakpoint icon in the gutter of the Macro panel and select Properties from the context menu. This menu also holds the Enabled item that controls whether the breakpoint is enabled or disabled. Disabled breakpoints are shown with the icon. Disabling breakpoints is useful if you want to deactivate the breakpoint temporarily without deleting it.

Besides setting ordinary breakpoints, which pause the macro execution when the debugger reaches them, you can make breakpoints pause the macro only if certain conditions are met. This implies assigning either conditional expressions, or pass counts (however, using both on a single breakpoint disables it). See Conditional Breakpoints. Conditional breakpoints are shown with the icon. means the breakpoint is a disabled conditional breakpoint.

Note that you can set breakpoints while your macro is running. The new breakpoint will be set, and your macro will pause when it reaches the breakpoint.

Conditional Breakpoints Once you have set a breakpoint, by default, script execution will pause just before the breakpoint line. By

editing the breakpoint description in the Breakpoints panel or in the Breakpoint Properties dialog you can



command the execution to stop at the breakpoint under certain conditions. Such a breakpoint is called a conditional breakpoint.

Automated Build Studio uses a special icon for conditional breakpoints - , means a disabled

kpoint: • In the Macro panel, click in the gutter on the left of the desired operation. This sets the

breakpoint. the main menu to activate the Breakpoints panel, or choose

uild Studio’s main menu and then choose Breakpoints from the choose Build Studio | Panel List from Visual

nu and then choose Breakpoints from the ensuing Select Panel dialog).

ties dialog. To

WTh panel watch expression is a variable (ordinal or

stored) current debugging session. Watch expressions (watche em

Studio you can only edit these projects, since it doesn’t allow running and debugging them (see the Wohelp).

To p• Select View | Watches from Automated Build Studio main menu.

og.

l dialog.

conditional breakpoint. To create a conditional brea

• Select View | Breakpoints fromView | Select Panel from Bensuing Select Panel dialog (in Visual Studio, Studio’s main me

• In this panel, the new breakpoint will be at the bottom of the list. You can then set one of two types of breakpoint conditions. The two possible conditions are -- conditional expressions pass counts

To modify the condition and pass count properties of a breakpoint, use the Breakpoint Propercall it, right-click the breakpoint icon in the Macro panel gutter and select Properties from the context

menu, or right-click the desired breakpoint in the Breakpoints panel and select Properties from the context menu.

atches Panel e Watches displays all current watch expressions. A whose value you wish to track during a macros) are added, r oved, disabled or edited from the panel context menu.

The panel’s features are turned off when you are editing an MSBuild project in Automated Build Studio. With Build

rking With MSBuild Projects document or the Working With MSBuild Projects section in on-line

dis lay the Watches panel, do one of the following:

• Choose View | Select Panel from the main menu and choose Watches in the ensuing SelectPanel dial

• Choose Build Studio | Panels from Visual Studio’s main menu and then choose Watches from the ensuing Select Pane

• Press the View | Watch List shortcut. The default shortcut is Ctrl-Alt-W, though you can change the assigned shortcut via the Customize Keyboard dialog.



The panel holds two columns: Expression and Value.

Column Description Expression e variable to be traced. The check box next to the variable name

atch is enabled, that is Automated Build Studio traces it. If the Specifies the name of th

cifies whether this wspecheck box is clear, the expression is not traced.

Value column. Specifies the value of the variable specified in the ExpressionYou may want to keep a watch expression available, but not allow Build Studio to calculate it. You can

accomplish this b ion. The expression itself will be grayed, and no value for it will be displayed. To en clear the check box in the Expression column. You can achieve eck or uncheck Enabled in the Edit Watch dialog invoked for the selected watch expression.

The WatchesTo add a watch expression

context menu.

To modify a watch expression desired watch expression in the Watches panel and choose Edit from the context

anel

anel resides at the bottom of the Macro panel. If the Breakpoints panel is hidd

y disabling the express a watch able or disable expression, select or

the same result if you ch

panel is blank until you add watch expressions to it.

• Right-click somewhere within the Watch List panel and select New Item from theAutomated Build Studio will display the Add Watch dialog in which you can specify the variable whose expression you want to trace.

• Right-click the menu. This will call the Edit Watch dialog, where you can edit the expression.

To delete a watch expression • Select the desired watch expression in the Watches panel. • Press Del or right-click the selected expression and choose Delete from the context menu.

Breakpoints PThe Breakpoints panel displays all of the breakpoints that are currently set in your macro. You can use

this panel when debugging Automated Build Studio macros. The panel’s features are turned off when you are editing an MSBuild project in Automated Build Studio. With Build Studio you can only edit these projects, since it doesn't allow running and debugging them (see the Working With MSBuild Projects document or the Working With MSBuild Projects section in on-line help).

By default, the Breakpoints pen, you can do one of the following to display it:

• Select View | Breakpoints from Automated Build Studio’s main menu.



• Choose Build Studio | Panels tudio’s main menu and then choose Breakpoints from suing Select Panel

from Visual Sthe en dialog

• Press the View | Breakpoints s , though you can change ssigned shortcut via the C

.

hortcut. The default shortcut is Ctrl-Alt-Bthe a ustomize Keyboard dialog.

• Choose View | Select Panelensuing

from Build Studio’s main menu and then choose Breakpoints from the Select Panel dialog.

corresponds to a breakpoint that is set in your project. Panel columns Each row of the Breakpoints list

hold information about breakpoints: Column Description Enabled Specifies whether the breakpoint is enabled or disabled. Automated Build Studio will not

stop the script execution on a disabled breakpoint. If the Enable Macro Debuggingitem on the Debug toolbar is not pressed, all breakpoints are treated as disabled. The disabled breakpoints are marked with the icon, enabled breakpoints - with the icon.

Condition Condition parameter for the breakpcolumn, the breakpoints icon is chang

oint, if any. After you specified any value in this ed to (or to ) to indicate that the breakpoint is

a conditional breakpoint. For more information, see Conditional Breakpoints and Breakpoints - Conditional Expressions.

Pass Count Pass count parameter for the breakpoint, if any. After you specified any value in this column, the breakpoints icon is changed to (or to ) to indicate that the breakpoint is a conditional breakpoint (see Conditional Breakpoints and Breakpoints - Using Pass Count).

Description Any descriptive text on the breakpoint. You can disable or enable breakpoints in the panel. To do this, simply select or clear the Enabled check

box for the desired breakpoint. The point of disabling a breakpoint is that you can keep its definition, even thou ly halt its execution.

the reakpoint properties.

elect the desired breakpoint in the Breakpoints panel. selected breakpoint and choose Delete from the context menu.

licking it in the Macro panel gutter.

gh you temporariThe Breakpoints panel is empty if breakpoints have not been set. To modify a breakpoint

• Right-click the desired breakpoint in the Breakpoints panel and select Properties from context menu. Use the resulting Breakpoint Properties dialog to modify b

To delete a breakpoint • S• Press Del, or right-click the• You can also delete a breakpoint by c

To jump to the breakpoint operation in the macro



• Double-click the breakpoint in the list.

Evaluating Expressions aluate values of macro variables during macro debugging. To do this, pause the macro at the

desired point one of the ways described below. You can ev

and then use

To pause the macro execution To pause the macro execution, do one of the following:

• Set a breakpoint on the desired operation to pause the execution. See Using Breakpoints. • Set the cursor to the desired operation and then run the macro to the cursor. See Running to the

Cursor. • Press Pause on the Debug toolbar. If the toolbar is hidden, right-click somewhere in the

area and choose Debug from the ensuing context menu. (In Visual Studio, select Pause from the Automated Build Studio toolbar.)

s paused, you can evaluate variable values.

ng Expressions ways of evaluate variables during the macro debugging: using watches or the Evaluate

dial ecide which way to use by following the simple rule: If you need to trace a variable value during the whole macro debugging session, use the Watches panel. If you need to evaluate values of certain vari alog.

toolbar

Once the macro execution i

EvaluatiThere are twoog. You can d

ables once, without tracing them during the macro run, use the Evaluate di


Script Writing 132

Sc

Script Writing – Basics

and cannot use pointers. ated Build Studio. VBScript and JScript are supported by DLLs

(of s or Internet Explorer. To run VBScript or JScript in Automated Buihigher, part of Win

ript Writing

General Information A script is a single script-language procedure or function. A script in Automated Build Studio is part of a

macro (see Script Operation). You can modify scripts using the Edit Script Form. A script can be written in one of the three supported scripting languages: DelphiScript, VBScript or

JScript. For each Script operation, the scripting language is specified in the Operation Properties dialog. All three supported scripting languages use only OLE-compatible data types

DelphiScript support is built in Automthe same name) supplied with Windowld Studio, Internet Explorer 5.0 or higher must be installed on the machine. If you do not have IE 5 or

you can install the Microsoft scripting components directly. The latest version of these DLLs (as a dows Script Components) is available at http://www.microsoft.com/downloads/.

For ta de iled information on scripting languages, see: VBScript http://www.msdn.microsoft.com/scriptingJScript http://www.msdn.microsoft.com/scriptingDelphiScript DelphiScript Description in Automated Build Studio help.

What can yo ainly to solve the following problems:

rform specific actions that cannot be executed with existing operations. See List of Oper

e macro and access their properties. See Working With Operations in Scripts.

cts. Automated Build Studio’s Object Model can help

rm almost any action, ther

ith a database of an exotic or obsolete format. In such a case, you can create a custom ope n on this, see Creating Custom Ope

ur scripts do in Automated Build Studio? They are used m

• To peations.

• To assign values to macro variables. See Using Variables and Constants in Macros.

Note: Macro variables cannot be used as loop variables. A loop variable should be a local script variable.

• To call operations existing in th

• To work with internal and external objeyou better understand how you can use scripts to work with different objects.

Note that though supported script languages are quite powerful and let you perfoe can be situations when scripts are not helpful. For instance, it may be impossible to write a script

routine for working wration that will perform the desired actions. For more informatiorations in on-line help.


Script Writing 133

WritingEach scr e routine called Main. When Automated Build Studio runs a script, it calls the

script’s Main e script. et’s hav

Scripts ipt must have th routine, which, in its turn, can call other procedures and functions defined in the a look at source code written in the Edit Script Form for a newly created script:L

[VBScript]

Sub Main

Log.Message("Something has happened")

End Sub

[JScript]

function Main()

{

Log.Message("Something has happened");

}

[DelphiScript]

procedure Main;

begin

Log.Message('Something has happened');

end;

As you can see, the source code that is created by default includes the Main routine only. Note tha upply parameters for this routine, you can use

variables or riables and Constants in Macros).

DebuggDebuggi ript Form. Whenever

you run a sc gs how the script was executed, posts errors it finds and user-defined messages, so you can al pts and find errors easily if there are some. Sometimes y For this purpose, use methods of the Log object.

Object Model In your ration lets you perform certain actions that cannot be done with other

Automated with internal objects of Automated Build Studio and e terfaces), process variables defined in the macro, call of these operations. Automated Build Studio treats bject model that is used in Auto

The top- ed in Automated Build Studio are --

t Main does not have parameters. If you need to sconstants defined in your macro. (See also Using Va

ing Scripts ng your scripts becomes easier when you use the Log panel of the Edit Script, this panel loways find out whether there are problems in your scriou may need to post custom messages to the log.

macros, the Script opeBuild Studio operations. In most cases, scripts dealxternal objects of other applications (via OLE/COM inoperations that exist in the macro and access properties each variable, constant or operation as an object. This topic explains the omated Build Studio.

Each object can have one parent and one or several child objects. Automated Build Studio contains a number of top-level objects, which you can address in scripts directly. To get access to other objects you should use methods and properties of the top-level objects.

level objects defin


Script Writing 134

Object Description ABSUtils be used as utilities which are specific to Unifies methods that can

Automated Build Studio only. BuiltIn ed Build Lets your scripts call routines that are built into Automat

Studio. See List of Built-In Routines. Constant Provides access to variables and constants defined for a macro in

See Using Variables and Constants in s and Variables

Automated Build Studio. Macros.

Log post custom messages to Automated Use methods of this object toBuild Studio’s Log panel from scripts.

Operatio scripts. In order for a script to call an operation, this operation must have a

Modifying Operation Properties and Working

ns Provides access to Automated Build Studio operations from

unique name. See With Operations in Scripts.

Utilitie variables of the Borland VCL SysUtils e Utilities Object - List of Supported

ables and

s Makes certain functions andunit available to your scripts. SeFunctions and Utilities Object - List of Supported VariConstants.

T ec Team’s Visual Macro acro including scripts between these applications, you will see that they are usually incompatible and need to be rewritten.

Hand inDur alue to

an opera onstateme t

he obj t model used in scripts of Automated Build Studio differs from that used in AQdev Builder. As a result, when porting a m

l g Exceptions in Scripts ing the script run different exceptions may occur. For instance, a script may store improper vti property or to a stored variable. Automated Build Studio does not provide any new functions or

nts hat handle exceptions in scripts. You can use the means provided by scripting languages.

VBScript To handle exceptions, you can use the Err object and the On Error statement. For more information

on them, see VBScript documentation (the on-line version is available at http://www.msdn.microsoft.com/scripting). The following code demonstrates how you can handle exceptions in VBScript routines:

[VBScript]

Err.Clear ' Resets the exception indicator

On Error Resume Next ' If an exception occurs,

' Automated Build Studio will continue running

' the script rather than stop it

' Do something

...

If Err.Number > 0 Then

' An exception occurred !!!

' Posts the exception messages to the test log


Script Writing 135

Log.Error Err.Description

Else

' No exceptions

...

End If

JScript To handle exceptions in JScript, use the try{} catch{} finally{} statement. Catch holds code

that is executed when an exception occurs within the try{} block. Finally contains instructions which are executed always, regardless whether or not exceptions occur in the try{} block. For more information on these statements, see JScript documentation (the on-line version is available at http://www.msdn.microsoft.com/scripting). The following code illustrates how you can handle exceptions in JScript routines –

[JScript]

try{

// Do something

...

}

catch(e)

{

// Posts the exception message to the test log

Log.Error(e.description);

}

finally{

...

}

DelphiScript Means that handle exceptions in DelphiScript are similar to those that handle exceptions in Delphi. This

includes the try... except... end and try... finally... end statements. These statements handle exceptions that occur within the try... except and try... finally blocks.

The except... end block is executed only if an exception occurs. Use it to perform specific actions as a response to an exception. If there are no exceptions, the control is passed to the instruction next to the end statement.

The finally... end block is always executed. Use it to ensure that certain operations in your code are completed whether or not exceptions occur.

To obtain the exception message in scripts, use the ExceptionMessage function. The following code illustrates exception handling in DelphiScript routines –

[DelphiScript]

try

// Do something


Script Writing 136

...

except

// An exception occurred !!!

// Posts the exception message to the test log

Log.Error(ExceptionMessage);

end;

Wough the Automated Build Studio operations provide an extensive complement of customizable

options, they cannot cover all possible cases. So you may need to program specific actions that cannot be don is using the Script operation. Scripts let you perform a wid

ou can do this.

CalliIn order to call an operation from a script, you should assign a unique name to that operation. To do this:

ated Build Studio and select erties dialog.

dialog, switch to the Properties page and specify the operation name in the Unique Name

A ue name to the operation, you can call this operation in your scripts. To call the desire

orking With Operations in Scripts Alth

e with Build Studio’s operations. You can do the variety of tasks: change macro variables, set special processing of data, get access to various objects via

COM interfaces, etc. In addition, your scripts can initiate execution of operations or they can get and set values of operation properties. This topic explains how y

ng Operations From Scripts

Right-click on the operation you wish to call in a script in AutomProperties from the context menu. This will call the Operation Prop

•

• In thefield. The operation name should be unique among other operations. It is used to refer to the operations in scripts.

fter you assign a uniqd operation in script, use the following syntax:

Operations.operation_unique_name.Execute

For example, Operations.MySubmacro1.Execute

If the epost a mess g Build Studio po adepends on thof its parents.

AccessinTo ique name to this operation. You

can doAfter

the followOperFor i

operation

op ration was called successfully, the Execute method returns True and Automated Build Studio a e about the operation execution to the log. Otherwise, it returns False and Automated

sts n error message on that matter to the log and (optionally) stops macro execution. The latter e value that is set in the Stop Execution If Operation Fails property of the given operation and See Handling Errors in Macros.

g Operation Properties in Scripts get or set an operation property from script, you should assign a un this as it was described above in the Calling Operations From Scripts section.

you assign a unique name to the operation, you can access the operation properties in scripts. Use ing syntax:

ations.operation_unique_name.property_name = property_value

nstance, the following code changes the Minor Version property of the Compile Delphi Project :

[VBScript]


Script Writing 137

i = Operations.MyDelphiProjectOperation.minorVersion

i = i + 1

Operations.MyDelphiProjectOperation.minorVersion = i

[JScript]

i = Operations.MyDelphiProjectOperation.minorVersion;

i = i + 1

Operations.MyDelphiProjectOperation.minorVersion = i;

[DelphiScript]

var

i : OleVariant;

begin

i := Operations.MyDelphiProjectOperation.minorVersion;

i := i + 1;

Operations.MyDelphiProjectOperation.minorVersion := i;

. . .

end;

You can also use variables, constants and their combinations when changing property values from script. For rty of the If File Exists operation: instance, the code below sets the File Name prope

[VBScript]



Operations.IfMyFileExists.filename =

Variables.FolderPath & "\" & Variables.FileName

[JScript]



Operations.IfMyFileExists.fileName =

Variables.FolderPath + "\\" + Variables.FileName;

[DelphiScript]



Operations.IfMyFileExists.fileName :=

Variables.FolderPath + '\' + Variables.FileName;

If yospecifyinin Macro

u want to concatenate values of variables and constants using the syntax that is acceptable when g operation property values via the Operation Properties dialog (see Using Variables and Constants s), use the ABSUtils.TranslateExpression method in your scripts. For example:

[VBScript]


Script Writing 138




ABSUtils.TranslateExpression("%FolderPath%\%FileName%")

[JScript]




ABSUtils.TranslateExpression("%FolderPath%\\%FileName%");

[DelphiScript]



Operations.IfMyFileExists.fileName :=

ABSUtils.TranslateExpression('%FolderPath%\%FileName%');

Not

Autom name that is shown in t

refines the “visual” name of a property from all invalid characters (such as pluses,

If a property name consists of several words, they are capitalized and then concatenated. •

UsingGenerate

All t operation node in the Code Completion window of the Edit Script form (to view additional information about operation properties, press the

e: Macro variables cannot store references to objects, they can only store ordinary values: numbers, strings, dates, etc.

ated Build Studio forms the names of operation properties in scripts on the base of the propertyhe Operation Properties dialog. The algorithm of name building is simple:

• Build Studio minuses, spaces, ampersands, etc.).

•

Build Studio applies the lower case to the first letter of the resulting property name (however, the names of properties that are common for all operations are in capital letters).

this algorithm, the Stack Frames property, for example, gets the stackFrames name for scripts; debug info becomes generateDebugInfo, etc. he operation properties are shown as subnodes of the

button):


Script Writing 139

Some properties may contain one of predefined values. For instance, the CheckTimeOutMode property

can y is a program analogue of the Timeout property that is common for all the operations). For properties like CheckTimeOutMode, the Code Completion window shows the values that can be used for setting the property value:

hold either 0, 1 or 2 (this propert

Note: Though the type of the CheckTimeOutMode property is an integer, you can use strings when setting the property value. Build Studio will automatically convert the specified string to the appropriate integer value and then assign this value to the property. For instance, you can use the following strings when setting the value of CheckTimeOutMode:

• None (analogue to 0) • Global (analogue to 1) • Local (analogue to 2)


Script Writing 140

When you obtain the property value, Automated Build Studio will return an integer value, not a string.


Automated Build Studio Command-Line Interface 141

Automated Build Studio Command-Line Interface

CoThis top

Player.

/nOpens Automated Build Studio without displaying the splash screen.

/Run MAfter the macro finishes, Automated Build Studio will stay open.

/RunASee

/SilentYoStu•

• o will not display

• ny

/variaInthanthisar

mmand-Line Arguments ic describes the command-line arguments of Automated Build Studio and Automated Macro

Automated Build Studio Command Line Automated Build Studio (<Automated Build Studio>\AutomatedBuildStudio.exe) uses the following

command line arguments, which are case-insensitive:

file_name Launches Build Studio and loads the specified macro (.bbp or .bxp file) into it.

s

or /R ust be specified after file_name. This will run the specified macro upon loading Build Studio.

ndExit or /RE /Run. This option does the same as /Run but closes Build Studio after the macro finishes.

Mode, /ErrorAndWarningMode or /ErrorOnlyMode u can use one of these arguments to specify which message boxes and dialogs Automated Build dio will display during a macro run:

/SilentMode - If this argument is specified, Automated Build Studio will neither display any dialogs nor inform you about any errors and warnings that occurred during a macro run. /ErrorAndWarningMode - If this argument is used, Automated Build Studidialogs, but it will show error and warning messages.

/ErrorOnlyMode - If this argument is used, Automated Build Studio will not display adialogs and message boxes except for error messages.

ble_name=variable_value or -variable_name=variable_value itializes the specified variable with the given value. The variable (stored variable) must exist in e macro you are running. See Using Variables and Constants in Macros. Here, variable_name d variable_value are the actual name and value of the variable. If the variable value holds spaces, e entire value must be enclosed in double-quotes. This command line argument is valid only if it used with the /Run or/RunAndExit arguments. To initialize several variables, you can use this gument several times in the same command line.



/c fR configuration. See Using Macro Configurations. If this r

thco

ro using all existing macro configurations. See Using Macro Configurations.

uild Studio with command line arguments. • Use the following command line to run Automated Build Studio, load the specified macro

(My.bbp) in it and start the macro execution for the Release configuration. dBuildStudio.exe"

AndExit

Automated Macro PlayThe s ted Build Studio also includes the Automated Macro Player. This is a console

applicat Studio>\AutomatedMacroPlayer.exe) that is used to run the macro you have constructed using Build Studio. When calling the Macro Player via the command line, you can pass it the name of a cro Player will start running this macro immediately, using the active configuration. Because it is easier and faster than Build Studio, the Macro Player is a good solution to run the m ly and proved to be reliable.

In ad all the other parameters that are supported ndExit, which are simply ignored by the

AutomThe Au n also includes Automated Build Studio Service. This is a

Window N d to provide client-server functionality and continuous integration support. It dispatches data and commands between clie acro runs, traces task triggers and starts a task when the trigger eve

o logs on request to resources they ra ge, ti

St riggers’ logs, which are posted to the VSSLog subfolder of this folder. The log files’ format depends on the

on iguration_name uns the macro with data of the specified

a gument is not specified, the active configuration which is saved in the macro will be used. To run e macro for several configurations at once, you can use this argument several times in the same mmand line.

/@all Runs a mac

Note: To determine which parameters were passed to Build Studio in its command line, add a Script operation to you macro and use the ParamStr and ParamCount functions in the script.

Here are some examples of running Automated B

C:\Automated Build Studio\Automate"C:\Work\Macros\My.bbp" /Run /Release

• The following line commands Automated Build Studio to run without the splash screen, to load the specified macro (My.bbp), to start its execution, to initialize the ProjectDir variable and to exit when the macro execution is over. AutomatedBuildStudio.exe "C:\Work\Macros\My.bbp" /ns /Run/ProjectDir="C:\My Projects"

er Command Line in tallation of Automaion (<Automated Build

file that holds a macro and the Ma

acros you have already checked thoroughdition to the macro file name, you can pass the Macro Player by AutomatedBuildStudio.exe except for /ns, /Run and /RunA

Macro Player.

ated Build Studio Service Command Line tomated Build Studio’s installatio

s T service (<Automated Build Studio>\Bin\AutomatedBuildService.exe) that is use

nt and server machines, stores results of mnts or conditions are accomplished. AutomatedBuildService.exe accepts the following command-line arguments:

/trace:on and /trace:off F r some triggers, the Automated Build Studio Service can post t ce. These are the triggers of the Microsoft Visual SourceSafe File Change, PVCS File ChanS arTeam File Change, Subversion File Change, Surround SCM File Change, Team Coherence F le Change and Vault File Change types. The logs are collected in the <Automated Build

udio>\Bin\Extensions folder except for the Microsoft Visual SourceSafe File Change t



trigger type, and it usually includes the entire command line of the launched process (it is used to check the state of the traced resource), the process response, the request date and time and the latest date and time of the traced resource obtained during the check. New records are appended to the log file that is stored for each trigger. The /trace:on argument enables logging of triggers' activity.

called TraceMode, is created in the

ice. his ne b s sto

try and will set the number of running tasks.

ervice (if it is not registered yet) and passed in the /poolsize and/or /trace

if it is already running.

e Automated Bu

/exit This argument is suppos to AutomatedBuildServi cess, not as a service. The /exit

race of

AutomatedBuildService

At that, the DWORD value, which is HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Automated Build Studio Service registry key and is set to 1. The /trace:off argument disables trigger logging and sets TraceMode to 0). Later, when being launched, AutomatedBuildService.exe will read the data of the TraceMode value from the registry, and it will either enable or disable trigger logging.

/poolsize:N This argument sets tAutomatedBuildServ

he number of tasks that can be run siexe. By default, t

multaneously byumber is 5. The integer value N passed in this red as the PoolSize value of the DWORD type in argument (it can rang etween 1 and 30) i

the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Automated Build Studio Service registry key. Later, when being launched, AutomatedBuildService.exe will read the data of the PoolSize value from the regis

/service Registers the AutomatedBuildService.exe process as an NT sruns this service. Before the service is run, it reads the valuescommand-line arguments or reads the corresponding values from the registry (see above).

/restart Starts the Automated Build Studio Service if it is not running and restarts it

/stop Stops th ild Studio Service.

ed to be used with the /poolsize and /trace arguments when they are passedce.exe being launched as a stand-alone pro

argument simply writecommand-line argume

s the corresponding values specified by the /poolsize and/or /tnts to the registry, but it does not run an instance.exe with newly set parameters.

Exit Codes Both Automated Build Studio and Automated Macro Player provide the following exit codes, which

report on the results of the last run: Exit Code Description 0 The last run was executed successfully. 1 An error occurred in a macro during the last run.

Normally, these codes are of use when Automated Build Studio or the Automated Macro Player is launched from a batch file. Here is a simple example:

REM Clears the screen

CLS


http://www.automatedqa.com/downloads/abs.asp


@ECHO OFF

R he BuiEM Launc s Automated ld Studio without splash screen

REM and runs the specified macro

START \W "C:\Automated Build Studio\AutomatedBuildStudio.exe" /ns /RunAndExit C:\Macros\MyProj.bbp

REM If ERRORLEVEL is greater than 1, go to Unknown

IF ERRORLEVEL 2 GOTO Unknown

IF ERRORLEVEL 1 GOTO Errors

IF ERRORLEVEL 0 GOTO Success

:Unknown

ECHO Unknown return code

GOTO End

:Errors

ECHO There are errors

GOTO End

:Success

ECHO No errors

GOTO End

:End


Miscellaneous 145

M ou

W ith SoStudi

Automated Build Studio as g Build Studio, you can check in and check out you , etc. To perform these actions, Automated Build Studio that is runn es the File | Source Control menu. Note that Automated Build Studio als tegration with the CVS, PVCS, Perforce, Visual SourceSafe and many other source t ros of corresponding operations (for the full list of supported source control systems, The difference between these operations and the al with the files with

rks. d Build Studio is running as a standalone application, it supports all Microsoft Source

SProxy or Jalindi Igloo plug-in

rce Integrity stem

M)

sion Harvest Change Manager Etc.

rce control system, this system must support ontrol system. thout an SCC

his case you have to install the provider manually. m, you should add your macro to it. To do this:

iscellane s

orking W urce Control Systems Automated Build o provides integrated source control services. This means that you can use

a client for your source control provider. Without leavinr macro ie ions, v w its history, compare its vers

ing as a standalone application includo supports an in

con rol systems within mac see Supported Tools).

menu is that the menu operates with your macro file only, while the operations dewhich your macro wo

mateWhen AutoCode Control API compatible source control systems including:

• Microsoft Visual SourceSafe • Concurrent Versions System (CVS), through the CV• Merant PVCS Version Manager • Team Coherence • Rational ClearCase • Starbase Versions (StarTeam) • Seapine Surround SCM • IBM VisualAge TeamConnection • CS-RCS • MKS Sou• Perforce P4 Version Control Sy• CM Synergy (Continuus C• AllChange • Code Co-op • SourceOffSite • AllFu•

In order for Automated Build Studio to work with a souMicrosoft SCC API and your computer must have an SCC Provider registered for this source cNote that some of the source control systems (for instance, Subversion) are shipped wiprovider. In t

Before you start using a source control syste


Miscellaneous 146

• •

Save your macro to a file if you have not saved it yet. Select Add to Source Control from the File | Source Control menu. This will call the Select SCC

ider dialog that lists source control systems installed on your computer. Automated Build

•

Once yocontrol systto which yo

No

After y system, you will be able to check it in or out, view history and use other services provided by the source control system. These actions will be applied to the sele ce control system, you mus

• out your macro from the selected source control system. t - Lets you undo the check out action. This item is enabled only when Check

t

Note:

Ho in/check-out status of a macro may not coincide with the status if you checked out your macro from

o outside

ialog displays the history of the selected file (creation date, check in dates, etc.) and the current version number.

• Compare Files - Lets you compare a file stored in the source control system with another file in the source control system with a file that is

tored in the source control system. The actual actions n the source control system you use as well as on the

nstance, if you use Microsoft Visual SourceSafe and your macro is a file in the .bxp format, clicking the Compare Files item will show Visual SourceSafe's Difference Options dialog, in which you can select the files for comparison, specify comparison

acro is a file in the .bbp format, Visual mpare the files right after you select the

Compare Files item. Other source control systems may provide another behavior.

ProvStudio generates this list automatically. Select the desired source control system in the dialog and press OK. u press OK in the Select SCC Provider dialog, Build Studio will connect to the selected source

em. Then, it will show the source control system's dialog in which you need to specify the project u want to add your macro.

te: If your macro has already been added to the chosen source control system outside of Automated Build Studio, but you want to check it in or out from Build Studio, you should add your macro to this source control system anyway as it is described above.

our macro is added to the source control

cted source control system only. If you want to add your macro to another sourt unbind the macro from the chosen source control system first. To do this, select File | Source Control |

Unbind From Source Control. Then you can add your macro to another source control system as it is described above.

The File | Source Control menu holds some more items for working with source control systems: • Check In - Checks in your macro to the source control system chosen in the Select SCC Provider

dialog. Check Out - Checks

• Undo Check OuOu is disabled.

Automated Build Studio traces the check-in/check-out status of a macro and enables or disables the Check In and Check Out methods according to this status. For instance, Automated Build Studio disables the Check In item after the macro was checked in and enables it after the macro was checked out. The Check Out item is disabled when Check In is enabled and vice versa.

wever, Build Studio’s check-of the macro in the source control system. This happensthe source control system using Automated Build Studio and then checked in the macrof Build Studio using any other tool, for example, using a client application of the source control system. To bring Build Studio’s status of the macro to the source control system’s status, select Refresh Status from the File | Source Control menu.

• History - Calls the History dialog provided by the source control system. This d

stored in the source control system, or a file storednot stored in it, or two files that are not sperformed by this menu item depend o"nature" of the files. For i

options and start comparing the files. If your mSourceSafe will not show any dialogs - it will co


Miscellaneous 147

• Properties - Invokes the dialog that shows source-control propertiesprovided by the source control system.

• Run Application - Launches the client application of the source control systeSelect SCC Provider dialog. This may be necessary if you want to do something that cannot be done with Build Studio.

For more information, see the documentation on the particular client that supports the Source Code Control technology.

Micrsoft Visual Studio, which Build Studio integrates with, also has a File | Source Control menu with similar items. However, their purpose differs from what is described above. In particular, only the Microsoft Visual SourceSafe integration is supported. To learn control systems, see Visual Studio’s documentation

Working With Automated Build Studio via COM Automated Build Studio is a COM server and it can be controlled from other applications like

COM server (for example, like Microsoft WAutomated Build Studio macros. This topAutomated Build Studio via COM from a Visual Basic applicaAutomated Build Studio from managed applications (C#) is also included. Our sam

• Connect to Automated Build Studio via COM. • Open an Automated Build Studio project. • R• Chec

The topic inc

of your macro. This dialog is

m selected in the

more about Visual Studio’s native support for source .

any other ord). Other AutomatedQA applications can use it to integrate

ic provides a step-by-step explanation of how you can control tion. A description of how to work with

ple code will:

uns a test. k the results ludes the following sections:

Setting up Visual Basic (Optional) Connecting to Automated Build Studio Automating Automated Build Studio With the Integration Object Working W

Two• A simple alternative to testing your appl

Automated Build Studio and pass it certArguments for more information.

• COM only commands work if one instance of Automated Build

Setting up Visual Basic (Optional) To wor

Studio objefollowing steps explain how to do this.

• Open your COM client application in Microsoft Visual Basic. • Select Project | References from Visual• In the References dialog, check Automated Build Studio Library and press OK. This will

reference to the Automated Build Studio object library for your COM client applicati

ith Automated Build Studio From Managed Code notes before we proceed:

ications with Automated Build Studio via COM is to run ain command-line arguments. See Command-Line

Studio is running.

k with Automated Build Studio in your VB application, add a reference to the Automated Build ct library to your application that will use Automated Build Studio as a COM server. The

Basic's menu. This will call the References dialog. add a

on:


Miscellaneous 148

If Automated B

Browse and seleOpen File dialog

Connecting to Automated Build CThe first step in using Automated Build Studio as a COM serve

connection, you have to create a reference to the absApplication objecand properties to connect and work with Automated Build Studifollowing program and class identifiers:

uild Studio's library is not present in the dialog, you can add it directly by pressing cting the <Automated Build Studio>\Bin\Automated Build Studio.exe file in the ensuing .

Studio via OM r is connecting to it. To create a t. This object implements methods

o. To create a connection you can use the

Application Program Id Class Id Automated Build Studio ABS.Application {28180ECD-1420-4640-8C6B-A1EC7925F9E2} Automated Macro Player AMP.Application {183F38AF-EDC5-4799-8218-5F6BAF668AB3}

The following code creates a connection by calling Visual Basic’s CreateObject function and using ABS.Application as the program id:

[Visual Basic]

Set ABSApp = CreateObject("ABS.Application")

This line will connect your COM client application to the currently running instance of Automated Build Studio. If Automated Build Studio has not yet been launched, CreateObject will launch it.

The absApplication object contains the following methods and properties: Property or Method DescriptionQuit omated Build Studio. Method. Use it to exit AutManager Property. Returns a reference to the IaqBaseManager object that

provides access to internal Automated Build Studio interfaces. These are


Miscellaneous 149

th ces that different components of Automated Build Studio us

e same interfae to connect and work with each other.

IntegrationManager Pr ntegrationManager ob her-level functions sp

operty. Returns a reference to the IabsIject that provides access to a subset of higecifically engineered to let users perform typical actions over

Automated Build Studio. To automate Automated Build Studio, we will use the IabsIntegrationManager object. The

Manager object provides deeper access to Automated Build Studio’s internal objects and components, its use is more complex: the calls to methods and properties of internal objects should match certain conditions adopted in Automated Build Studio; execution of a simple action may require several complex calls and so on. The use of the IabsIntegrationManager object is much simpler. It includes all functionalities that let you perform most common actions: open macros, run them, and export results. The next section describes how you can use this object to automate Automated Build Studio.

Automating Automated Build Studio With the Integration Object The IabsIntegrationManager object contains three properties that return references to helper

objects, which you can use to open macros, run them and export results: Property Object Description Exporter IabsExporter Contains methods used to export results. Macro IabsMacro Contains methods used to open and save macros. Runner IabsRunner Contains methods used to run macros and control the macro runs.

At the beginning of the topic we wanted to create sample code that will -- • Connect to Automated Build Studio. • Open a project. • Run a test. • Check results of the test.

The IabsMacro, IabsRunner and IabsExporter objects contain special methods to perform these steps, so the execution of almost all of these steps requires no more than a single method call: Action Description To open a macro... Use the Open method of the IabsIntegrationManager.Macro object. Tomacro rconsta .

method of the bles

obtain or change a va iable or Use the VariableByName or ConstantByName

object. nt. . IabsIntegrationManager.Macro.Varia

To obconfigura

eConfiguration

e ConfigurationsList property of the IabsIntegrationManager.Macro object to obtain the IabsConfigurationsIterator object. To enumerate configurations, use the methods of this object.

tain work with To obtain the active configuration name, use the Activtions... property of the IabsIntegrationManager.Macro object.

To enumerate configurations, use th

To run a macro... Use one of the following methods of the IabsIntegrationManager.Runner object:

• Run - Runs the currently opened macro in Automated Build Studio.


Miscellaneous 150

• BatchRun - Runs the currently opened macro using the specified configurations.

Before calling any of these routines make sure Automated Build Studio is not ou can do this, by calling the IabsRunner.Running

Each of these methods return after the macro run was started or after the macro failed to start. They do not pause the program execution until the macro run is over. To wait until the macro execution is over, you can check the Running

n a loop.

executing macros. Yproperty in a loop.

property iIn the sample code that goes after this table, we will use the BatchRun method to start tests.

To trace the macro execution progress...

To obtain information about a macro's execution, use the RunProgress method ntergationManager.Runner object. The method returns inYou can d within a loop. The loop condition will check th e, the loop ress method to obtain information about execution

of the IabsIformation about the macro execution through its parameters.

call the RunProgress methoe value of the IabsRunner.Running property. If the value is Trubody can call the RunProg progress and display this information to the user.

To pause a macro ru

To pa Pause method of the IabsIn o execution ationManager.Runner.Run.

n... use a macro run, use thetergationManager.Runner object. To resume the macr, call IabsIntegr

To stop a macro run... To sto e IabsIn

p a macro run, use the Stop method of thtergationManager.Runner object.

To check results... To chec se theRunRes t. This prop

k whether the last macro run finished successfully, uult property of the IabsIntegrationManager.Runner objecerty returns a boolean value indicating the result.

To obtain the last error description...

To obtai e IabsIn

n the last error's description, use the LastError property of thtegrationManager.Runner object.

T or e IabsIn

•

•

•

o export results... To exp t macro execution results, use one of the following methods of the thtegrationManager.Exporter object: ExportErrorsFromLog

ExportLog

ExportSummary

The following code demonstrates how you can automate Automated Build Studio: [Visual Basic]

Sub RunABS absApplicatiDim AbsApp As on, IntegrationManager As IabsIntegrationManager ' Connecting to Automated Build Studio App = CreateObject(Set Abs "ABS.Application") ' ng the Integratio Obtaini nManager object rationManager = ASet Integ bsApp.IntegrationManager


Miscellaneous 151

' Opening the macro If egrationManager. Not Int Macro.Open("c:\Work\Automated Build Studio\Samples\Macros\BuildLogic\BuildLogic.bxp" Then) ' If Build Studio failed to open the macro isplay notification a ine ' d nd exit the rout not open the MsgBox "Can specified project" ABSApp.Quit Exit Sub End If ' Runs the macro ionManager.Runner.Integrat BatchRun "Release" e macro ' Waiting until th run is over anager.RWhile IntegrationM unner.Running DoEvents Wend ' Exporting results .RunnIf IntegrationManager er.RunResult Then IntegrationManager.Exporter.ExportSummary "C:\MyFile.htm", False End If ' Closing Automated Build Studio AbsApp.Quit End Sub

Two notes: • To run the tests, we use

macro run is started. If y ated Build Studio when a macro is running (this or example, w o

displays a message that e application and terminate the o avoid this

• Macro operation propert in your Automated Build Studio acro. When you start he

IabsRunner object, Aumacro. Therefore, we reco utomated Build St

g with Automated Buious sections, we used Vis ill

describe how you can perform the sa ct to Automated Bu work with it via the

To work with Automated Build d code, add a reference for the Automated Build Stu

• Select Project | Add Re u of Visual Studio. This will call the Add ialog. g:

Switch to the COM ta

d the BatchRun method. This method returns immediately after the ou try to close Autom

happens, f hen you call Quit right after BatchRun), Automated Build Studiasks you whether you want to close th

macro run. T message, we used a loop that waits until profiling is over. ies and various settings are stored

m running your macro using the Run or BatchRun methods of ttomated Build Studio uses the settings stored in your Automated Build

Studio with A

mmend that you prepare your macro before you run that macroudio via COM.

Workin ild Studio via COM from managed code In prev ual Basic to automate Automated Build Studio. In this section, we w

me tasks from C# code. Our sample code will conneild Studio and IabsIntegrationManager object.

Studio from managedio library to your project:

ference from the main menReference d

• In this dialobbed page.


Miscellaneous 152

Find Automated Bu f available components.

Choose this library i button. The library will appear in the Selected Componen

Press OK to close the you the reference is added,

In order to work with Auto PI functions - CoCreateInstance and GetAct e functions are defined.

de demonstrates

ild Studio Library (TypeLib Version: 1.0) in the list o

n the list and click the Selectts list. dialog and save your changes.

After you will have access to Automated Build Studio’s interfaces. mated Build Studio via COM, two Windows AiveObject are used. So you need to write special code where thes

The following co how you can use Automated Build Studio via COM: [C#]

// Add the following lines to your unit using System.Runtime.InteropServices; using AutomatedBuildStudio; ... public class Form1 : System.Windows.Forms.Form { ... // Defines functions needed to obtain a reference to ABS [DllImport("Ole32.dll", Pres ")] erveSig = false, EntryPoint = "CoCreateInstance[return: MarshalAs(UnmanagedType.IUnknown)] private static extern object CoCreateInstance([In] ref Guid clsid, [MarshalAs(UnmanagedType.IUnknown)] Object punkOuter, int context, [In] ref Guid iid); [DllImport("oleaut32.dll", PreserveSig = false, EntryPoint = "GetActiveObject")] [return: MarshalAs(UnmanagedType.IUnknown)] pri ref Guid clsid, int reserved); vate static extern object GetActiveObject([In] // Defines helper constants pr st int INPROC_SERVEivate con R = 1; private const int LOCAL_SERVER = 4; pr 1_Click(objivate void button ect sender, System.EventArgs e) { Guid CLSID_ABS = new Guid("28180ECD-1420-4640-8C6B-A1EC7925F9E2"); Guid IID_ABS = "8new Guid( CFC12DB-6026-486B-A563-889D1AC8A859"); object ABSAppObject = null; ess to Autom // Obtains acc ated Build Studio try { ABSAppObject = GetActiveObject(ref CLSID_ABS, 0); } catch { try


Miscellaneous 153

{ ABSAppObject = CoCreateInstance(ref CLSID_ABS, null, INPROC_SERVER | LOCAL_SERVER, ref IID_ABS); } catch { } } (ABSAppObject == null) if return; ins the IabsIntegra // Obta tionManager object AutomatedBuildStudio.absApplication ABSCOMObject = (AutomatedBuildStudio.absApplication) ABSAppObject; I AutomatedBuildStudio.Iabs ntegrationManager IntegrationManager = AB eSCOMObject.IntegrationManag r; try { ence // We have a refer to the integration object. its // Now we can use methods and properties to automate // Automated Build Studio. g the macro // Openin if (! IntegrationManager.Macro.Open("c:\\Work\\Automated Build St ros\\Buildudio\\Samples\\Mac Logic\\BuildLogic.bxp")) { // If Build Studio failed to open the macro display notific // ation and exit the routine ystem.Windows.For pen the specified S ms.MessageBox.Show("Cannot oproject"); bject.Quit( ABSCOMO ); return; } e macro // Runs th Manager.Run Integration ner.BatchRun("Release"); // Waiting until the macro run is over while(IntegrationManager.Runner.Running) Application.DoEvents(); // Exporting results if(IntegrationManager.Runner.RunResult) { IntegrationManager.Exporter.ExportSummary("C:\\MyFile.htm", false); } } ystem.Runtime.Inte s.COMException ex) catch(S ropService { ms. " + System.Windows.For MessageBox.Show("An exception occurred: ex.Message); } finally { ated B// Closes Autom uild Studio ct.Quit(); ABSCOMObje


Miscellaneous 154

// Releases COM objects Marshal.ReleaseComObject(IntegrationManager); Marshal.ReleaseComObject(ABSCOMObject); Marshal.ReleaseComObject(ABSAppObject); } } ... }

Please pay attention to thelease all objects that w

last three lines. They call the method to re e referred to in our co . Else, the work with Automated Build Studio y and the next attempt to automate A

Sounds for Automated Build Studio Events f one of these

e will play the app bout the event. The sound n f you are not ro is running.

Marshal.ReleaseCOMObjectde. Make sure that you call this method and release the objectswill not be finished properl

utomated Build Studio will fail.

Automated Build Studio has a number o events to which sounds can be assigned. Each timevents occurs, the computer ropriate sound and thus notify you aotification is especially useful i at the computer where the mac

Build Studio has the following events:

Event Description Breakpoint Hit Occurs every time the macro execution is paused on a breakpoint. Macro Execution Failed Occurs when the macro execution fails. Macro Execution Succeeded Occurs when the macro execution is completed successfully.

To specify the soundo

to be played for ea dio Device Pr

ch of these events, use the standard Sound and Auperties dialog. You can call this dialog from the Control Panel:


Miscellaneous 155

To associate a sound with an event: • Find the Automated Build Studio x.

nt under thecify the sou

sound fr ss Browse and n the ensuing O

node in the dialog's Program events bo• Choose the desired eve Automated Build Studio node. • In the Sounds box, spe nd to be played when the event occurs.

You can either choose the om the dropdown list of the Sounds box, or prechoose a .wav file i pen File dialog.


Operations Reference 156

O e

Operation Categories operation are divided into the following

cate

perations Referenc

In Automated Build Studio, all s that can be used in macrosgories:

Category Description .NET Tools Operations that can run various .NET utilities to process your

.NET-connected applications. Archivers Operations that let you pack and unpack files using the Zip and

RAR compression formats. Authenticode O allow to sign and check signed files using the

Microsoft Authenticode technoloperations that

gy. AutomatedQA Tools Operations that run other products by

in AutomatedQA Corp. and

teract with them. Borland Compilers Operations that let y

Coou compile projects with Borland and

deGear compilers installed on your computer. Build Tools Operations that run automatic builds using external build tools. Burn CD/DVD Operations t write such

im CD or DVD disk. hat let you create ISO images a

ages or arbitrary files and folders to a s well as

Communication Operations that let you send and receive e-mail and news messages as well as send messages via MSN Messenger or ICQ.

Concurrent Versions System Operations that work with Concurrent Versions System. They let you retrieve files from CVS, put them into it, etc.

Execute Operations that run programs from macros. Files and Directories Operations to work with files and folders (creating, copying and

les and folders). moving fiFrequently Used sed when creating Operations that you have most frequently u

macros. FTP Operations that let you browse the contents of FTP se

as download and upload files from / to rvers, as well

them. Help Compilers Operations that let you compile help files in HLP, CHM and other

formats. HTTP Operations that let you browse the contents of HTTP servers, as

d post data from / to them. well as get anInstallers Operations that let you build installation programs using such tools

as InstallShield and Wise.



Interactive s that let you create various dialog boxes in order to input Operationor select values, display messages and select files and folders.

Internet Information Servic(IIS)

es Operations that allow you to manage Web and FTP sites on a local or remote computer.

Issue Tracking Operations that let your macros create and modify items stored in systems. different issue tracking

JediVCS Operations that work with the Jedi Version Control System. For example, checking files in and out.

Logging Operations that let you control the logging of macro runs and export the whole log contents or its part to a file.

Microsoft Compilers Operations that let you compinstalled on your computer.

ile projects with Microsoft compilers

Microsoft Compilers for Smart Device

Operations that let you compile projects with Microsoft compilers for Smart Device installed on your computer.

Microsoft Virtual Server Operations that control virtual machines running under Microsoft Virtual Server 2005.

Microsoft Visual SourceSafe Operations that work with Microsoft Visual SourceSafe. They let you retrieve files from VSS, put them into it, etc.

Misc Miscellaneous operations that let you insert comments into macros, the macro execution, wait until a specific window appears, pause

etc. Oracle Operations that work with Oracle Database System. They

back up, restore and recover databases as well as to execute RMA let you

N and SQLPlus scripts.

Other Compilers ith miscellaneous Operations that let you compile projects wcompilers installed on your computer.

Patch Management s used to work with patch managements tools such as OperationIncUpdate Builders or Visual Patch.

Perforce Operations that work with Perforce. They let you retrieve files from Perforce, put them into it, etc.

Prepare Code Operations used to compress, decompress and encrypt executables and libraries and include exception-handling code in them.

PsTools Operations that work with system utilities from the PsTools suite. PVCS that work with Merant PVCS Version Manager. They

and put them into it. Operationslet you retrieve files from PVCS

Read/Write s and Operations used to work with text, INI files, XML documentthe system registry.

Remote Macro Execution Operations that let you run macros and monitor macro runs on other computers in the network.

Source Code Tools Operations that analyze source code files for different compilers. SourceGear Vault Operations that work with SourceGear Vault. They let you retrieve

files from a SourceGear Vault repository, put them into it, etc. SourceOffSite Operations that work with SourceOffSite. They let you retrieve



files from a SourceOffSite repository, put them into it, etc. Standard General operations used to organize loops, conditionally execute a

group of operations, etc. StarTeam Operations that work with Borland StarTeam. They let you retrieve

files from StarTeam, put them into it, etc. SQL Operations that allow y

well as ases. ou to execute SQL queries

to maintain Microsoft SQL Server datab and scripts as

Subversion Operat les from S

ions that work with Subversion. They let you retrieve fiubversion, put them into it, etc.

Surround SCM Operat files fro

ions that work with Surround SCM. They let you retrievem Surround SCM, put them into it, etc.

Team Coherence Operat Software Components Team ions that work with QualityCoherence. They let you retrieve files from Team Coherence, put them into it, etc.

Team Foundation Version Control

Operations that work with Microsoft Team Foundation Version Control. They let you retrieve files from Team Foundation Version

into it and so on. Control, put themUnit Tests Operations that can run various test utilities to test units of your

application. WMI Operations that let you start, pause and stop services, run and

r on your local computer. ent Instrumentation.

terminate processes, etc. on a remote oThese operations use Windows Managem

You can also create custo help.

. ls Categgory

m operations. For more information on this, see on-line

NET Too ory The .NET Tools cate includes the following operations:

Operation Description CLRxLint Verifies checked exceptions defined in your .NET assemblies using

Software4net CLRxLint. Configure ASP.NET P.NET on the current computer using the ASP.NET Configures AS

IIS Registration Tool (aspnet_regiis.exe). Dotfuscator tes your .NET code using PreEmptive Dotfuscator. ObfuscaEdit Assembly Informatio al assembly n Modifies assembly attributes in one or sever

information source files. Extract Public Key Extracts the public key from a .NET a

Tool (snssembly, a key file or a .exe). container using the Strong Name

Fix COM References one or more Fixes references to the COM interop assemblies inMicrosoft Visual Studio .NET projects.

FxCop Tool Analyzes code of your .NET assemblies using Microsoft FxCop. GAC Iterator sembly cache using the Global

ly Cache Tool (gacutil.exe). Iterates records of the global asAssemb



Generate Key Pair s a new key pair using the Strong Name Tool (sn.exe). GenerateILMerge Merges multiple .NET assemblies into a single one using Microsoft

ILMerge. Install/Uninstall Assembl

cache using the Global Assembly Cache Tool y Installs or uninstalls a .NET assembly into/from the global

assembly (gacutils.exe).

Install/Uninstall Key /from the specified key

Installs or uninstalls a key pair intocontainer using the Strong Name Tool (sn.exe).

InstallUtil Uses the Installer Tool (InstallUtil.exe) to install or uninstall serverresources by executing the installer components of a s

pecified

.NET assembly. Manifest Generation and yment manifests Editing Creates, signs or updates application and deplo

using the Manifest Generation and Editing Tool (mage.exe). Native Image Generator Installs, updates or removes native images for an assembly and its

dependencies using the Native Image Generator utility (ngen.exe). Register/Unregister Assembly Registers or unregisters a .NET assembly using the Assembly

ration Tool (regasm.exe). RegistRe-sign Assembly Re-sig ns a previously signed or delay-signed .NET assembly with

the real key pair using the Strong Name Tool (sn.exe). Resources Generator Converts .txt or .resx files to or from .resource files using the

Resource File Generator utility (resgen.exe). Run AL.EXE Runs the Assembly Linker utility (al.exe). Run SN.EXE Runs the Strong Name Tool (sn.exe). Verify Strong Name Verifies the identity of a .NET assembly installed into the global

assembly cache (simple text name, version number, culture information, public key and digital signature) using the Strong Name Tool (sn.exe).

WiseOwl Demeanor Obfuscates your .NET code using WiseOwl Demeanor. X .NET code using Code Systems Corporation

XenoCode. enoCode Obfuscates your

For more information on operations of this group, see the NET Specific Opearations document or on-line h

A oryu

elp.

rchivers Categ The Archivers category incl des the following operations:

Operation Description Extract Files From RAR File Extracts files from an archive packed with WinRAR. Extract Files From ZIP File Extracts files from an archive packed using the Zip compressio

format. n

Pack Files With WinRAR Packs files to an archive with WinRAR. Pack Files With Zip pression format. Packs files to an archive using the Zip com



For more information on op e Operations document or in on-lin

A tege category i

erations of this group see Archievers Category in the General-Purpose help.

uthenticode Ca ory The Authenticod ncludes the following operations:

Operation Description Certificate Manager Manipulates the certificates, certificate trust lists and

certificate revocation lists. Check Signed File Validity (ChkTrust) Verifies a signed file using the ChkTrust utility. Check Signed File Validity (Si Tool utility. gnTool) Verifies a signed file using the SignCreate Personal Information Exchange File

Creates a PFX-file that holds private keys and software publishing certificates.

Create Software Publishing Certificate Creates a sample software publishing certificate. Create X.509 Certificate Creates a sample X.509 certificate. Make Certificate Trust List Creates a certificate trust list. Se registry keys that control the

n process. t Registry Keys Values Defines values of the

verificatioSigning Code (SignCode) Signs a file with a software publishing certificate using the

SignCode utility. Signing Code (SignTool) Signs a file with a software pu

SignTool utility. blishing certificate using the

Time Stamping Files Adds or updates the signed certificate’s time stamp For more information on operations ose

O -line help.

A A Tools Catd

B er tools by Automat

of this group see Authenticode Category in the General-Purpperations document or in on

utomatedQ egory The AutomatedQA Tools category i

uild Studio with othncludes the following operations that let you integrate Automate

edQA Corp.: Operation Description AQtime .NET Edition 1 Profiles your application with AQtime .NET Edition version 1.X. AQtime 3 Profiles your application with AQtime 3. AQtime 4 Profiles your application with AQtime 4. AQtime 5 Profiles your application with AQtime 5. TestComplete Runs tests created in TestComplete 2.x and 3.x. Te mplete 4.x. stComplete 4 Runs tests created in TestCoTestComplete 5 ated in TestComplete 5.x. Runs tests creTestComplete 6 Runs tests created in TestComplete 6.x.



TestExecute Runs TestComplete tests with TestExecute 2.x or 3.x. TestExecute 4 Runs TestComplete tests with TestExecute 4.x. TestExecute 5 Runs TestComplete tests with TestExecute 5.x. TestExecute 6 Runs TestComplete tests with TestExecute 6.x.

For more information on operations of this group see AutomatedQA Tools Category in the Testing, Profiling and Issue-Tracking Operations document or in on-line help.

ategory erations:

Borland Compilers CThe Borland Compilers category includes the following op

Operation Description Compile Borland C# 2005 Project Compiles Borland C# 2005 projects. Compile Borland C# 2006 Project Compiles Borland C# 2006 projects. Compile Borland Developer Studio 2 oper Studio 2005 005 Compiles a group of Borland DevelProject Group projects. Compile Borland Developer Studio 2006 Project Group

Compiles a group of Borland Developer Studioprojects.

2006

Compile Borland VB .NET 2005 Project Compiles Borland VB .NET 2005 projects. Compile Borland VB .NET 2006 Project Compiles Borland VB .NET 2006 projects.

Compile C++Builder 3-4 Project 3 and Borland C++Builder 4. Compiles Borland C++Builder projects created in Borland C++Builder

Compile C++Builder 3-6 Project Gro (supports Borland C++Builder v. 3 - 6) up Compiles a group of Borland C++Builder projects

Compile C++Builder 5 Project Compiles Borland C++Builder 5 projects. Compile C++Builder 6 Project Compiles Borland C++Builder 6 projects. Compile C++Builder 2006 Project Compiles Borland C++Builder 2006 projects.

Compile Delphi 3-7 Project Compiles Borland Delphi projects (supports Delphi v. 3 - 7).

Compile Delphi 4-7 Project Group pports Compiles a group of Borland Delphi projects (suDelphi v. 4 - 7)

Compile Delphi 8 for .NET Project Compiles Borland Delphi 8 for Microsoft .NET projects. Compile Delphi 8 for .NET Project Group

Compiles a group of Borland Delphi 8 for Microsoft .NET projects.

Compile Delphi 2005 for .NET Project Compiles Borland Delphi 2005 for Microsoft .NET projects.

Compile Delphi 2005 for Win32 Project Compiles Borland Delphi 2005 for Microsoft Windows projects.

Compile Delphi 2006 for .NET Project Compiles Borland Delphi 2006 for Microsoft .NET projects.



Compile Delphi 2006 for Win32 Project Compiles Borland Delphi 2006 for Microsoft Windows projects.

Compile Delphi 2007 for Win32 Projs.

ect Compiles CodeGear Delphi 2007 for Microsoft Windows project

Compile Delphi 2007 for Win32 ProjGroup

ect Compiles a group of CodeGear Delphi 2007 for Microsoft Windows projects.

Compile JBuilder Project Compiles Borland JBuilder projects (supports Borland JBuilder 6 or later).

Compile JBuilder Project Group Compiles a group of Borland JBuilder projects (supports Borland JBuilder 6 or later).

For more information on operations of this group see Borland Compilers Category in the Compilers, Help Compilers and Code Preparation Operations document or in on-line help.

Build Tools Category Tools category includes the following operations: The Build

Operation Description

Ant Runs an automatic build using Apache Ant. IncrediBuild Runs a distributed build

Software IncrediBuild. of Visual C++ projects via Xoreax

IncrediBuild Command d performed by Controls the running of a distributed builIncrediBuild.

MSBuild Runs an automatic build using Microsoft MSBuild. NAnt Runs an automatic build using NAnt.

For more information on operations of this group see Build Tools Category in the Installation and Building Operations document or in on-line help.

Bu CD/DVD category includes the following operations:

rn CD/DVD Category The Burn

Operation Description Burn ISO Image Burns an existing ISO image to a CD or DVD disk. Burn CD/DVD Burns or DVD disk. arbitrary files and folders to a CDCreate ISO Image Creates an ISO image from arbitrary files.

For more information on operations VD Category in the General-Purpose O n-line help.

C egoategory inclu

of this group see Burn CD/Dperations document or in o

ommunication Cat ry The Communication c des the following operations:



DescriOperation ption E-mail Enumerator Receiv d on the server at once or

arch to locate those you actually es all the e-mail messages store

sewant to recei

es through the list of these messagesve from the server.

Receive E-mail Message Receives an individual e-mail message. Receive News Message Receives a news message. Send E-mail Sends an e-mail message. Send Message via ICQ Sends a message to an ICQ user. Send Message via Windows Sends a message to one or several Windows Messenger, MSN

r or Windows Live Messenger users. Messenger MessengeSend N Sends a mews Message essage to a newsgroup.

For more information on perations do

operations of this gro Communication Categup see ory in the General-Purpose O cument or in on-line help.

C Systestem categ work

with Concurrent Versions System (CVS):

oncurrent Versions m Category The Concurrent Versions Sy ory includes the following operations, which are aimed to

Operation Description CVS Add Adds files to the CVS repository. CVS Checkout Checks out files from the CVS repository to a working folder. CVS Commit Incorporates changes from your working files into the CVS repository. CVS Export Gets a copy of t he CVS repository. he source files from tCVS Import Incorporates an

repository folde entire source distribution from an outside source into the CVSr.

CVS Init Creates a new CVS repository on the current computer. CVS Login Establishes a

connection parauser session, so that further CVS operations do not need meters.

CVS Logout Terminates theoperation.

user session that was established with the last CVS Login

CVS Release Safely undoes aCVS History fil

ll uncommitted changes and leaves an appropriate trace in the e.

CVS Remove Removes files from the CVS repository. CVS RTag Assigns symbolic tags to definite file revisions in the CVS repository. CVS Update Settles your

files since ycha

our nges to the checked-out CVS files with any revisions of these last checkout or update.

Get Changes From CVS Gets a list of modified, added and removed files from a CVS repository. Run CVS Command Executes an arb mmand. itrary CVS co

For more information on operatioersion Control Systems document or i

ns ofV n on-l

this group see Concurrent Versions System Category in the ine help.



Execute Category The Execute category includes the following operations, which let you run external applications from

within your macros: Operation Description Execute ACT Script Runs a Microsoft Application Center Test project. Ex ified DOS command. ecute DOS Command Performs the specExecute Macro macro created with Automated Build Studio. Executes a Execute Program Launches the specified program. Open File With Registered Application ile type. Opens a file in the application associated with the fRun Smart Device Emulator for Launches an emulator to test your projects built

Windows CE or Pocket PC. For more information on operations

O ine help.

Files and Directories Category includes the follo

of this group see Execute Category in the General-Purposeperations document or in on-l

egory The Files and Directories cat wing operations:

Operation Description Beyond Compare Compares files or folders via Beyond Compare. Beyond Compare Script Runs a Beyo are script that includes commands controlling Beyond

dnd Comp

Compare an performing file operations via this tool. Calculate Checksum Calculates a an appropriate format. checksum of a file using Compare Files Compares two files byte-by-byte. Copy File(s) Copies one or several files. Copy/Move Directory Copies or moves a folder to the new location. Create Directory Creates a new folder with the specified name. Delete File(s) Deletes one or several files. Directory Enumerator Obtains a collection of folders

folder in the collection. and then performs child operations for each

File Enumerator O tion of files and then performs child operations for each file in

btains a collec the collection.

Find/Replace in File Se th another value. arches for a value in a file and replaces it wiGet File Attributes Retrieves the attributes of a specified file. Get File Version Info Retrieves version information from a specified file. Get Size Gets the size of the specified file or folder. If Directory Exists Executes the child operation(s) if the specified directory exists. If File Exists Executes the child operation(s) if the specified file exists. Move File(s) Moves the specified files to a new location. Remove Directory Deletes a folder.



Rename Directory Renames a folder. Robocopy Copies files and folders using Microsoft Robust File Copy Utility

(robocopy). Run Robocopy Job Runs a robocopy job f

to which destination. ile that contains settings that control what to copy and

Set/Clear File Attributes Modifies the file attributes. Set File Version Info Assigns version information for the specified file. Set Manifest Embeds manifest into a DLL or executable file. Set Resource Language Assigns the language of the resources stored in DLLs or executables. Validate XML File Validates an XML file against DTDs and schemas. XCopy Copies one or several files or folders, including subfolders.

For more information on operations o-line help.

f this gr eneral-Purpose Operations

Frequently Used Category contains opera when creating your

m add op e macro, this operation is automatically added to frequently used o f the category, of the category. The m yed in this ca

ategory that you c hide o , use the S mmand of th

F

oup see Files and Directories Category in the G document or in on

The Frequently Used category tions that you use most frequentlyacros. The category is populated as you erations to macros. When you add an operation to th

the Frequently Used category. Most perations are displayed on the top o less frequently used – on the bottomaximum number of operations displa tegory is 20.

For convenience, the Frequently Used can quickly locate the needed operation. To

is displayed on the top of Operations panel so r display this category in the Operations panel

how “Frequently Used” category co e Operations panel’s context menu.

TP Category The FTP category includes the following operations:

Operation Description Connect To FTP Connects to an FTP server. Create FTP Directory Creates a new folder on the FTP server. Delete FTP File Delete a file on the FTP server. Disconnect From FTP Disconnects from an FTP server. Download File(s) From FTP Downloads the specified file(s) from the FTP server. FTP File Enumerator Obtains a list of rrent directory of the FTP server and files of the cu

performs child operation for each file in the list. Get Current FTP Directory Obtains the name o he FTP server. f the current directory on tGet FTP File Size Obtains the size of the specified file that is located on the FTP server. If FTP Directory Exists Performs the child operation(s) if the specified directory exists on a FTP

server.



If FTP File Exists Executes the child operation(s) if the specified file exists on the FTP server.

List Current FTP Directory Saves the contents of the current directory on the FTP server to a variable.

Remove FTP Directory Deletes the specified directory on the FTP server. Rename FTP File Renames the specified file on the FTP server. Set Current FTP Directory Specifies the current directory on the FTP server. Synchronize Directories Synchronizes the contents of a local directory and the directory on a

FTP server. Up One Level Change the curre n the FTP server to its parent directory. nt directory oUpload File(s) to FTP Uploads the specified file(s) to the FTP server.

For more information on operations of this gr P Category in the General-Purpose Operations d ine help.

Help Compilers Category The Help Compilers category includes the fo

oup see FTocument or in on-l

llowing operations:

Operation Description Doc-O-Matic Builds a Doc-O-Matic help project. Help & Manual Builds a Help & Manual help project. Microsoft Help Compiler s th Build e help file in .hlp format. Microsoft HTML Help Compiler Builds the help file in .chm format. NDoc Help Compiler Builds th ver. 1.0-1.3. e help file in several formats using NDoc NDoc 1.31 Help Compiler Builds the help file in several formats using NDoc ver. 1.3.1 RoboHelp Builds th help WinHelp project. e RoboSandcastle HTML Generator (BuildAssembler)

Generatthe assem

es logically grouped HTML topics for each element of bly.

Sandcastle Reflection Generator Creates a re.NET as(MRefAssembler)

flection file that describes each element in the sembly.

Sandcastle XSL Transformer (X

PerformslTransform)

s XSL transformation for the specified XML-file.

For more information on operations of this gr Compilers and Code Preparation Operations docum

HTerations:

oup see Help Compilers Category in the Compilers, Helpent or in on-line help.

TP Category The HTTP category includes the following op

Operation Description Connect To HTTP Connects to an HTTP server.



Disconnect From HTTP Disconnects from an HTTP server. HTTP Head Requests a Web server using the HEAD method. HTTP Get Sends an HTTP request of the GET type to a Web server. HTTP Post Sends an HTTP request of the POST type to a Web server.

For more information on operations of this group see HTTP Category in the General-Purpose O e help.

I

perations document or in on-lin

nstallers Category The Installers category includes the following operations:

Operation Description Advanced Installer Builds installation programs with Advanced Installer. Ghost Installer Builds installation programs with Ghost Installer. Inno Setup Builds installation programs with Inno Setup. InstallAnywhere Enterprise Builds installation programs with InstallAnywhere Enterprise. InstallAnywhere.NET Builds . installation programs with InstallAnywhere.NETInstallAware Builds installation programs with InstallAware Studio. InstallShield 7-2008 Operation Builds installation programs with InstallShield v. 7-2008. InstallShield Express Limited Edition

Borland Builds d Limite

installation programs with InstallShield Express Borland Edition.

InstallShield Professional 6-7 Builds nal v. 6.1- installation programs with InstallShield Professio7.x.

InstallShield Standalone Build Builds installation programs with InstallShield Standalone Build module.

InstallShield Universal Builds installation programs with InstallShield Universal. MS Setup Project Builds installation programs with Microsoft Windows Installer. M statement against a Windows Installer Package

(MSI) database. SI Generic Executes an SQL

MSI Merge two Windows Installer (MSI) packages into one. MergesMSI Transform Package (MSI) or Applies a transform to a Windows Installer

generates a transform file. MSI Update Properties Installer Package Modifies properties' values defined in a Windows

(MSI) and/or adds new properties. MSI Validation Validates a Windows Installer Package (MSI) using Internal

Consistency Evaluators (ICEs).

Nullsoft Scriptable Install Syst em Builds installation programs with Nullsoft Scriptable InstallSystem.

W(Wise for Windows Installer v. 5.0 or higher, Wise for Visual Studio .NET v. 5.0 or higher, Wise Package Studio v. 5.0 or

ise Builds installation programs with Wise installation authoring tools



higher). W rograms with Wise Installation System. ise Installation System Builds installation pWiX Compiler (candle) Compiles the

object fWindows Installer XML (WiX) source files into WiX

iles. WiX Decompiler (dark) Converts the MSI installation package into the Windows Installer

XML (WiX) source files. WiX Linker (light) Creates the Windows Installer Package (MSI or MSM) based on

ML (WiX) object files. the Windows Installer XFor more information on opera ory in the Installation and Building

Operations

Interactive Category wing operations:

tions of this group see Installers Categ document or in on-line help.

The Interactive category includes the follo

Operation Description Check List Display a group of check boxes. s a dialog withConfirmation Box Displays a confirmation dialog. Input Box Displays an input dialog. Message Box Displays a message box. Radio Group Displays a dialog with a group of radio buttons. Select File Displays an Open File dialog. Select Folder Displays a Browse for Folder dialog.

For more information on operations of th ee Interactive Category in the General-Purpose Operations document or in on-line help.

Internet Information Serviceices (IIS) c

is group s

s (IIS) Category ategory includes the following operations: The Internet Information Serv

Operation Description Add/Remove Allowed ISAPI/CGI Extension (IIS6+)

Enables or disables ISAPI extensions and CGI applications in IIS.

Create Application Pool (IIS6+) Creates a new application pool. Create FTP Directory (IIS6+) Creates a new folder on an IIS FTP site. Create FTP Site (IIS6+) Creates a new IIS FTP site. Create Virtual Directory Creates a virtual directory on a IIS web site. Create Web Site Creates a new IIS web site. Delete Application Pool (IIS6+) Deletes an existing application pool. Delete FTP Directory (IIS6+) Removes a folder from a IIS FTP site. Delete FTP Site (IIS6+) Deletes an existing IIS FTP site.



Delete Virtual Directory Deletes an existing virtual directory from an IIS web site. De . lete Web Site Removes an existing IIS web siteManage Configuration Backup or restores the IIS metabase. Saves Manage Service Starts, stops or restarts the specified IIS service. Manage Site Starts, stops or restarts the specified IIS site.

For more information on operations of this group see Internet Information Services (IIS) Category in the General-Purpose Operations document or in on-line help.

gory tions:

Issue Tracking CateThe Issue Tracking category includes the following opera

Operation Description AQdevTeam Create Issue Creates an item in AQdevTeam. CaliberRM Create Requireme Adds a requirement to a CaliberRM database. nt CaliberRM Delete Requiremen aliberRM database. t Removes a requirement from a CCaliberRM Edit Requirement atabase. Modifies a requirement stored in a CaliberRM d

CaliberRM Requirement Enumn of requirements stored in a CaliberRM

erator database and then executes child operations for eachrequirement in the collection.

Obtains a collectio

StarTeam Create Issue est, a task or a topic) to a Adds an item (a change requStarTeam database.

StarTeam Delete Issue a e.

Removes an item (a change request, a task or a topic) fromStarTeam databas

StarTeam Edit Issue Modifies an item (a change request, a task or a topic) stored in a StarTeam database.

StarTeam Issue Enumerator Obtains a collection of items (change requests, tasks or topics) stored in a StarTeam database and then executes child operations for each item in the collection.

Team Coherence Create Issue Adds an item (a bug report, feature request, etc.) to Team Coherence's database.

Team Coherence Delete Issue Removes an item (a bug report, feature request, etc.) from Team Coherence's database.

Team Coherence Edit Issue Modifies an item (a bug report, feature request, etc.) stored in a Team Coherence database.

Team Coherence Issue Enumerf items (bug reports, feature requests,

.) stored in a Team Coherence database and then executes ld operations for each item in the collection.

ator etcchi

Obtains a collection o

Team Foundation Create Work dio 2005 Team Item Foundation. Adds a new work item to Microsoft Visual Stu

Team Foundation Edit Work It al Studio 2005 em Team Foundation. Edits a work item stored in Microsoft Visu



For more information on operand Issue-Tracking Operations do

JS category include

ations of this group see IssueTracking Category in the Testing, Profiling cument or in on-line help.

ediVCS Category The JediVC s the following operations:

Operation Description JediVCS Check In Checks in one or more modules to the JediVCS repository. JediVCS Check Out Checks out module(s) from the JediVCS repository. JediVCS Get Module Retrieves one or more modules from the specified location. JediVCS Input Executes a sequence of commands from an external file. JediVCS Label Project ecifies a label for the project stored in the JediVCS repository. SpJediVCS Lock Enumerator es and executes a Retrieves a collection of checked out modul

child operation over each module in the collection. JediVCS Module Enumerator a collection of modules that belong to a specified

e Retrieves project and executes a child operation over each module in thcollection.

JediVCS Project Enumerator Retrieves a collection of projects stored in the JediVCS and executes a child operation over each project in the collection.

JediVCS Synchronize Project Obtains the latest or desired versproject.

ion of all modules of a specified

JediVCS Synchronize Project Group Obtains the latest or desired version of all projects from a specified project group.

JediVCS Undo Check Out Undoes the checkout of module(s) in the JediVCS repository. For more information on operations of this group see JediVCS Category in the Version Control Systems

O cument or in on-line help.

Logging Category owi

perations do

The Logging category includes the foll ng operations:

Operation Description Disable Logging Filters out the messages to be posted to the log. Enable Logging Re-enables posting of messages to the log. Export Errors From Log Exports errors from Build Studio’s Log panel to a file or to a variable. Export Log Exports the contents of Build Studio’s Log panel to a file or a variable. Export Summary Exports the c

or a vo

ariable. ntents of Build Studio’s Summary panel to an HTML file

Set Log Marker Adds a marker to the log. For more information on operations

perations document or in on-line help. of se

Othis group see Logging Category in the General-Purpo



M goThe Microsoft Compilers category includes the following operations:

icrosoft Compilers Cate ry

Operation Description ASP.NET Compiler Performs in-place or deployment compilation of the

ASP.NET Web application. Compile Visual C# .NET 7.x Project Compiles Visual C# .NET 7.0 and 7.1 projects. Compile Visual C# 2005 Project Compiles Visual C# 2005 projects. Compile Visual C# 2008 Project Compiles Visual C# 2008 projects. Compile Visual Basic .NET 7.x Project Compiles Visual Basic .NET 7.0 and 7.1 projects. Compile Visual Basic 2005 Project Compiles Visual Basic 2005 projects. Compile Visual Basic 2008 Project ompiles Visual Basic 2008 projects. CCompile Visual C++ .NET 7.x Project Compiles Visual C++ .NET 7.0 and 7.1 projects. Compile Visual C++ 2005 Project Compiles Visual C++ 2005 projects. Compile Visual C++ 2008 Project es Visual C++ 2008 projects. CompilCompile Visual J# .NET 7.x Project ojects. Compiles Visual J# .NET 7.1 prCompile Visual J# 2005 Project Compiles Visual J# 2005 projects. Compile Visual Studio Solution Proj 7.1, Visual Studio ect Compiles Visual Studio .NET 7.0,

2005 and Visual Studio 2008 solutions. Compile Visual C++ 6.0 Project Compiles Visual C++ 6.0 projects. Compile Visual Basic 6.0 Project Compiles Visual Basic 6.0 projects. Compile Visual Basic 6.0 Project Gro piles a group of Visual Studio 6.0 Projects up ComCompile Visual Studio Workspace Compiles Visual Studio 6.0 workspaces. MSIL Assembler Generates a portable executable file (PE) from MSIL

assembly language. For more information on operations of this gr

Help Compilers and Code Preparation Operations doup see Microsoft Compilers Category in the Compilers,

ocument or in on-line help.

M ilers forpilers for Sma

icrosoft Comp Smart Device Category The Microsoft Com rt Device category includes the following operations:

Operation Description Compile eMbedded Visual C++ 4.0 P Compiles eMbedded Visual C++ 4.0 projects. roject Compile Visual Basic .NET 7.x PrSmart Device

r ce.

oject for Compiles Visual Basic .NET 7.0 and 7.1 projects fosmart devi

Compile Visual Basic .NET 2005 P smart roject for Compiles Visual Basic .NET 2005 projects forSmart Device device. Compile Visual C# .NET 7.x PrSmart Device

rt oject for Compiles Visual C# .NET 7.0 and 7.1 projects for smadevice.

Compile Visual C# .NET 2005 Pr t oject for Compiles Visual C# .NET 2005 projects for smar



Smart Device device. Compile Visual C++ .NET 2005 P isual C++ .NET 2005 projects for smart roject for Compiles VSmart Device device.

For more information on operations of this group see Microsoft Compilers for Smart Device Category in the Compilers, Help Compilers and Code Preparation Operations document or in on-line help.

Microsoft Virtual Server Category g operations: The Microsoft Virtual Server category includes the followin

Operation Description Discard/Merge Undo Disks Discards or merges changes that are stored in the undo

disks file. If OS Is Loaded Executes the child operation(s) if the operating system

was loaded successfully on the virtual under Microsoft Virtual Server 20

machine running 05.

If Virtual Machine Is … rtual machine ft Virtual Server 2005 is in a

Executes the child operation(s) if a virunning under Microsoparticular state.

Pause/Resume Virtual Machine on Pauses or resumes a virtual machine running Microsoft Virtual Server 2005.

Register/Unregister Virtual Mach ine Registers or unregisters a virtual machine in MicrosoftVirtual Server 2005.

Reset/Shutdown/Turn off Virtual ine running on 2005 or shuts down the

Machine Resets or turns off a virtual machMicrosoft Virtual Serveroperating system on the virtual machine.

Run Virtual Machine osoft Virtual Server Runs a virtual machine on Micr2005.

Save State/Discard Saved State al machine running on

state.

Saves the state of a virtuMicrosoft Virtual Server 2005 or discards the saved

Send Key Sequences Simulates the given series of keys being typed (pressed and then released) inside the virtual machine running

osoft Server 2005. under MicrVirtual Machine Device Enumerator Obtains a list of devices installed on a

and executes child operations virtual machine

for each device in this list. Virtual Machine Enumerator Obtains a list of virtual machines installed on a virtual

ns for each machine in server and executes child operatiothe list.

For more information on opera l-Purpose Operations document or in

tions of this group see Microsoft Virtual Server Category in the Genera on-line help.



M ouThe Microsoft Visual SourceS y includes the following operations:

icrosoft Visual S rceSafe Category afe categor

Operation Description Check In File(s) to VSS iles to Microsoft Visual

SourceSafe. Checks in one or more f

Check Out File(s) From VSS Checks out files from Visual SourceSafe. Get Changes From VSS Retrieves a list of modified, added and removed files

from Visual SourceSafe. Get F by their date in Visual SourceSafe. ile(s) by Date From VSS Gets files specified Get File(s) by Label From VSS Operation Gets files specified by their label in Visual SourceSafe. Get Latest Version From VSS Gets the latest version of files from Visual SourceSafe. Pin File(s) in VSS Pins the files specified by their label or version number

in Visual SourceSafe. Set Label to VSS File(s) Specifies labels for files stored to Visual SourceSafe. Undo Check Out File(s) From VSS Undoes the checkout of files under a Visual SourceSafe. Unpin File(s) in VSS Unpins the specified files in Visual SourceSafe. VSS File Enumerator Obtains a collection of files stored in Visual SourceSafe

and then performs child operations for each file in the collection.

VSS Version Enumerator s

operations for each history item in the collection.

Obtains a collection of history items for a project or filestored in Visual SourceSafe and then performs child

For more information on ope n the V n

Misc Category Misc

rations of this group see Microsoft Visual SourceSafe Category iersion Control Systems docume t or in on-line help.

The category includes the following operations:

Operation Description Co tree of a macro. mment Displays a comment in the operations Create GUID ew GUID and saves it to a variable. Generates a nDelay Delays the macro execution for the specified time span. Get Free Disk Space fied disk. Obtains the amount of free space on the speci

If COM Class Is Registered ccording to the result of the check. Checks if a COM class is registered in the system and performs child operations a

If Window Exists Checks if a window appears on screen and performs the child operations according to the result of the check.

For more information on ocument or in on

ope s d -line help.

rations of this group see Misc Category in the General-Purpose Operation



Oracle Category ludesThe Oracle category inc the following operations:

Operation Description Back Up Oracle Database Backs up the specified Oracle database. Execute RMAN Script Executes a block of Recovery Manager commands. Execute SQLPLUS Script Runs an SQLPlus script that accesses an Oracle database. Recover Oracle Database Recovers an Oracle database. Restote Oracle Database Restores a database from the back up.

For more inperations docum

formation on o the General-Purpose O ent or in on-lin

The Other Compilers category includes the following operations:

perations of this group see Oracle Category in e help.

Other Compilers Category

Operation Description Compile Chrome Project Compiles RemObject Software Chrome projects. Compile Intel C++ Project for Visual Studio .NET 7.x

Compiles Intel C++ for Windows projects integrated into udio .NET 7.x. Visual St

C + 2005 Project fS ++ Compiler

ect for Smart Device ows CE.

ompile Visual C+ or Compiles your Visual C++ 2005 Projmart Device Using Intel C by using Intel C++ Compiler 2.0 for Wind

Gyour C/C++

rsion CC Compiler Preprocesses, compiles, assembles and links files using the GNU Compiler Collection (GCC) ve4.1.1.

I IA-32 dows, versions 7-

binary code that ntel C++ Compiler forEmploys Intel C++ Compiler for Win9.1, to compile C++ source code into targets the IA-32 architecture based processors.

Intel C++ Compiler for Itanium pile C++ source code into binary code that Employs Intel C++ Compiler for Windows, versions 7-9.1, to comtargets Intel Itanium processors.

Is Intel Fortran Compiler for Windows, versions 8-

he IA-32 architecture based processors. ntel Fortran Compiler for IA-32

Employ9, to compile Fortran source code into binary code that targets t

I m ows, versions 8-

ntel Fortran Compiler for ItaniuEmploys Intel Fortran Compiler for Wind9, to compile Fortran source code into binary code that targets Intel Itanium processors.

Java Compiler Compiles Java projects. For more information on operations of this group see Other Compilers Category in the Compilers, Help

Compilers and Code Preparation Operations document or in on-line help.



Patch Management Category ng operations: The Patch Management category includes the followi

Operation Description IncUpdate Builder Builds a project created in IncUpdate Builder 2.53 or later. Visual Patch Builds a project created in Visual Patch 2.0 or later.

For more information on of this group see Patch Management Category in the Installation a ns docu

P ryThe Perforce category inc

operations nd Building Operatio ment or in on-line help.

erforce Catego ludes the following operations:


Get Changes From Perforce files from a Perforce’s depot. Gets a list of modified, added and removed

Perforce Custom Command Executes the specified Perforce command. Perforce Edit Files Opens files kept in Perforce's client workspace for editing. Perforce Edit Jobs Creates, edits or deletes jobs.

Perforce File Enumerator ion aobut the files kept in Perforce’s depot without Gets informataccessing their contents and saves it to a variable.

Perforce Fix Job that fixes it. Links the job to the changelistPerforce Lock/Unlock Files Locks the opened files against changelist submission or unlocks them. Perforce Login Logs in to a Perforce server. Perforce Logout Logs out of a Perforce server. Perforce Set Label to Files Sets a label to the file revisions kept in Perforce’s depot. Perforce Submit Files Sends changes made to opened files to the depot.

ze kept in Perforce’s depot and client wSynchronizes file revisionsPerforce Syncroni orkspace.

For more information on opera s Operations document or in on-line

Prepare Code Categore Code category inc

tions of this group see Perforce Category in the Version Control Systemhelp.

ry The Prepa ludes the following operations:

Operation Description ASPack C an executable file or a library with ASPack. ompressesASProtect C prevents

u ect. ompresses and encrypts an executable file or a library andnauthorized usage of your application with ASProt

Eurekalog 4 Cc

atches exceptions raised by memory leaks and generates a log of the all stack using EurekaLog 4.



EurekaLog 5 C aks and generates a log of the atches exceptions raised by memory lecall stack using EurekaLog 5.

EurekaLog 6 C emory leaks and generates a log of the c

atches exceptions raised by mall stack using EurekaLog 6.

Generate Key For ASProtect G n keys for files protected with ASProtect. enerates registratiomadExcept 2 C to

t xcept 2. ollects information about exceptions and sends this information

he specified e-mail address using madEmadExcept 3 C

t g madExcept 3. ollects information about exceptions and sends this information to

he specified e-mail address usinProtect Files With Armadillo C able file or a library and prevents

u n with Armadillo. ompresses and encrypts an executnauthorized usage of your applicatio

Themida Ec

mploys Themida to protect your applications against modern racking.

UPX Compress Compresses an executable file or a library with UPX. UPX Decompress D d executable file or a

lecompresses the specified UPX-compresse

ibrary. UPX Test Checks the integrity of the compressed data in a UPX-compressed file. WinLicense E License to protect your applications against modern

cmploys Winracking and to provide advanced license control.

For more information on opera lp Compilers and Code Preparation O

PsTools Category

tions of this group see Prepare Code Category in the Compilers, Heperations document or in on-line help.

The PsTools category includes ations: the following oper

Operation Description Change Password (PsPasswd) Changes account passwords via the PsPasswd utility. Control Services (PsService) List and control services via the PsService utility.

Get Computer or User SID (PsGetSid) Returns the security ID (SID) of a computer or a user via ity. the PsGetSid util

Get Event Log (PsLogList) Dumps event log records by using the PsLogList utility. Get List of Opened Files (PsFile) Lists files opened remotely via the PsFile utility.

Get Logged on Users (PsLogged y. On) Lists users who are logged on locally and via resource sharing, by using the PsLoggedOn utilit

Get Process Information (PsList) Lists detailed information about processes via the PsList utility.

Get System Information (PsInfo) Lists information about a system by using the PsInfo utility.

Run Process (PsExec) Executes processes remotely by using the PsExec utility.

Shut Down Computer (PsShutd g the own) Shuts down or optionally reboots a computer by usinPsShutdown utility.



Suspend/Resume Process (PsSuspend) Suspends and resumes processes by using the PsSuspend utility.

Terminate Process (PsKill) Kills processes by name or process ID via the PsKill utility.

For more information on op e Operations document or in on-line

PVCS Category udes t

erations of this group see PSTools Category in the General-Purpos help.

The PVCS category incl he following operations:

Operation Description Get Changes From PVCS Gets a list of modified and added files from PVCS Version

Manager. Get File(s) From PVCS Checks out files or gets the latest version of files from PVCS

Version Manager. Pu Version Manager. t File(s) to PVCS Checks in files to PVCS Get Changes From PVCS (PCLI ist of modified and added files from PVCS Version ) Gets a l

Manager via Project Command-Line Interface. Get File(s) From PVCS (PCLI) Checks out files or gets the latest version of files from PVCS

Version Manager via Project Command-Line Interface. Put File(s) to PVCS (PCLI) Checks in files to PVCS Version Manager via Project Co

Line Interface. mmand-

For more information on opera s Operations document or in on-line

Rational ClearCase Category ar Case categ ations:

tions of this group see PVCS Category in the Version Control Systemhelp.

The Rational Cle ory includes the following oper

Operation Description ClearCase Apply Label earCase repository. Assigns a label to files stored in Rational ClClearCase Check In al ClearCase repository. Checks in one or several files to RationClearCase Check Out learCase

ry. Checks out one or several files stored in Rational Creposito

ClearCase Create Label Assigns a new label to one or several files stored in Rational ClearCase repository.

ClearCase Custom Command Executes a custom command concerning Rational ClearCase. ClearCase Lock Locks files and objects stored in Rational ClearCase repository. ClearCase Undo Check Out Undoes the check-out operation performed for one or several

files stored in Rational ClearCase. ClearCase Unlock Unlocks files and objects stored in the Rational ClearCase



repository. ClearCase Update View Updates snapshot view. Get Changes From ClearCase Re d files from the ClearCase repository. trieves change

For more information on operationontrol Systems document or in on-line h

s C el

Read/Write Category cludes the

of this group see Rational ClearCase Category in the Versionp.

The Read/Write category in following operations:

Operation Description D teelete Registry Key or Value Dele s a key or a value entry from the system registry. F Parses s child

operatile Content Enumerator the file contents into fragments and then perform

ions for each fragment. G turnet INI Value Re s the value of an entry from an INI file. G urn ry. et Registry Value Ret s the value of an entry from the system registG Obtainet XML Value s the value from an XML file. I heck

and pef Registry Key or Value Exists C s whether a specific key or value exists in the system registry

rforms child operations according to the result of the check. I Obtain

valuesoperat n or value in the collection.

NI File Enumerator s a collection of sections in an INI file or a collection of in a specified INI file section and then performs child ions for each sectio

R Reads ead From File entire data from a file to a specified variable.S Sets thet INI Value e value of an entry in an INI file. S ets thet Registry Value S e value of an entry in the system registry. Set XML Value Sets the value stored in an XML file. W riterite to File W s the variable value to a specified file.

For more information on operations of this group see Read/Write Category in the General-Purpose Operations document or in on-line help.

tegory Remote Macro Execution CaThe Remote Macro Execution category includes the following operations:

O Descripperation tion D oownload Macro Downl ads the macro from a remote computer. If Remote Macro State Is ... Checks macro on a remote computer has the specified

te an ing to the result of the check.

whether thesta d performs child operations accord

R xecuteemote Execution Stack E s child operations on several remote computers in parallel. Remote Group Execute computer. s child operations on a remote



R iatescompute

emote Macro Command Init , pauses, resumes or stops the macro run on a remote r.

S fieremote c

etup Connections Speci s the connections and connection parameters used to access omputers.

U adspload Macro Uplo the macro to a remote computer.

N uild Studia special

ote nnec

P

Soerations that let you perform analysis of your source code

files. This category includes the following operations:

ote: In order for Automated Bshould be configured in

o to successfully connect to a remote computer, that computer way. The settings are the same as the ones you set when

establishing connections to remdetailed information, see the Co

computers for Automated Build Studio’s Client panel. For tion Parameters topic.

For more information on operations of

urpose Operations document or in on-linethis group see Remote Macro Execution Category in the General- help.

urce Code Tools Category The Source Code Tools category includes op

Operation Description CodeHealer Analyzes Delphi source code using CodeHealer by SOCK Software. Pa eganza Pascal

Analyzescal Analyzer Verifies Delphi or Pascal source code files by using P

r. Project Analyzer Analyzes Visual Basic source code using Aivosto Project Analyzer. Run Project Analyzer Macro Executes the Aivosto Project Analyzer macro.

For more information on operations o , Help Compilers and Code Preparation Op

SourceGear Vault Category ry includes the following operations:

f this group see Source Code Tools Category in the Compilerserations document or in on-line help.

The SourceGear Vault catego

Operation Description Get Changes From Vault Gets a li ded files of a SourceGear Vault repository. st of modified and adVault Add Adds files to a SourceGear Vault repository.

Vault Check In Sends chrepositor

anges made to working copies of files to a SourceGear Vault y.

Vault Check Out Checks out working copies of files from a SourceGear Vault repository. Vault Cloak Cloaks a folder in a SourceGear Vault repository.

Vault Commit Sends chrepositor

anges made to working copies of files to a SourceGear Vault y.



Vault Create Folder Creates a folder in a SourceGear Vault repository. Vault Custom Command Runs an mmand. arbitrary SourceGear Vault coVault Delete Deletes files and folders from a SourceGear Vault repository.

Vault File Enumerator Returns a collexecutes

ection of files stored in a SourceGear Vault repository and child operations for each file of this collection.

Vault Get File(s) By Label Gets files from a SourceGear Vault repository by label. Vault Get File(s) By Version Gets files from a SourceGear Vault repository by version. Vault Get Latest Version Gets the latest version of files from a SourceGear Vault repository. Vault Label Sets a label to files or folders within a SourceGear Vault repository. Vault Uncloak Uncloaks a folder in a SourceGear Vault repository. Vault Undo Check Out Undoes t Vault repository. he checkout of files under a SourceGear

For more information on operations of l Systems document or in on-line help.

SourceOffSite Category ludes the following operations:

this group see SourceGear Vault Category in the Version Contro

The SourceOffSite category inc

Operation Description SourceOffSite Add s to a SourceOffSite repository. Adds fileSourceOffSite Check In y. Checks in files to a SourceOffSite repositorSourceOffSite Check Out ry. Checks out files from a SourceOffSite repositoSourceOffSite Create Project repository. Creates a new project within a SourceOffSiteSourceOffSite Custom Command Executes custom SourceOffSite command. SourceOffSite Delete Deletes files from SourceOffSite repository. SourceOffSite Enumerator Obtains a collection of files stored in a SourceOffSite

repository and performs child operations for each file in the collection.

SourceOffSite Get Latest Version Gets the laterepository.

st version of a file from a SourceOffSite

SourceOffSite Get Project By Lab project sprecified by label from a SourceOffSite el Gets therepository.

SourceOffSite Label Project Site repository. Creates a label in a SourceOffSourceOffSite Undo Checkout Undoes the checkout of files under a SourceOffSite repository.

The operations require that the your computer. O ill occur.

For more information on operatio l Systems document or in on-line help.

client application of SourceOffSite be installed ontherwise, an error w

ns of this group see SourceOffSite Category in the Version Contro



S y The SQL category includes the fol

QL Categorlowing operations:

Operation Description Back Up Database Backs up the specified Microsoft SQL Server database. C Checks

databasheck Database the integrity of objects in the specified Microsoft SQL Server

e. C Removelean Up Database s unused space from the specified Microsoft SQL Server database. Execute DTSRun Executes the specified DTS package. Execute SQL Script Runs an SQL script that accesses a Microsoft SQL Server instance. Execute SQL Statement Executes an SQL query against the specified Microsoft SQL Server

database which is accessed via OLE DB. Execute Stored Procedure Executes the specified stored procedure from a particular Microsoft SQL

Server database which is accessed via OLE DB. Rebuild Indexes Rebuilds indexes on tables in the specified Microsoft SQL Server database. Restore Database Restores the specified Microsoft SQL Server database from the backup

file. Run SQL Best Practices Uses Microsoft SQL Server Best Practices AnA

alyzer to verify whether common best implemented in the specified Microsoft SQL

database. nalyzer practices are

Server Update Statistics s inform

Microsoft SQL Server database. Update ation about distribution of key values in the specified

For more information on operations of th ral-Purpose Operations docum

Standard Category The Standard category includes the following operations:

is group see SQL Category in the Geneent or in on-line help.

O Descriptiperation on C s

tase Execute

matchesthe child operation(s) if the Switch expression value

he specified value. Else Executes operation(s) if the condition of If... operation or all

Case opeprecedes t

the childrations that precedes the Else operation is not met. that he Else operation is not met.

F xecutes inalization E the child operation(s) right before the macro run is finished. For Loop Executes

for state ramming languages such as C++, Visual Basic or Delphi

the child operation(s) in a loop. This is an analogue of the ment in prog.

Go to Label Transfers macro execution to the specified Label operation. Group Lets you o eral operations into a group. rganize sevI es tion f Previous Operation Fails Execut the child operation(s) if an error occurred during execu



of the pre ro. vious operation in the macI n S

Executes on of the previous operation c

f Previous Operatioucceeds in the ma

the child operation(s) if executiro was successful.

If ... Then Checks t n and performs the child operation(s) if the condition

he conditio is True.

Initialization Executes the child operation(s) right after the macro run is started. Label Marks a particular point in the macro. List Enumerator Obtains a collection of list items and then performs child operations

for each item in the collection. Log Message Posts a custom message to the log. Run Submacro Executes operations of a submacro. Script Lets you create a custom script in any of the 3 supported scripting

languages. Set\Reset Variable Value Sets or restores the default value of a variable from a macro. Stop Macro Execution Stops the macro run without any conditions. Submacro Organizes a set of operations into a submacro. You can call the same

submacro using the Run Submacro operation from different places in your macro.

Switch Executes one of the several operations or groups of operations, depending on the expression value. This is an analogue of the switch statement in such programming languages as C++ or Delphi, or Select Case statement if Visual Basic.

While Loop Performs the child operation(s) in a loop. This is an analogue of the while statement in such programming languages as C++, Visual Basic or Delphi.

For more information on operations of this group see Standard Category in the General-Purpose Operations document or in on-line help.

StarTeam Category The StarTeam category includes the following operations:

Operation Description Get Changes From StarTeam

Gets a list of modified, added and removed items from a StarTeam repository.

StarTeam Add Adds files to a StarTeam repository. StarTeam Apply Label Labels particular file revisions in a StarTeam repository with a view

label or a revision label. StarTeam Check In Sends changes made to working copies of files to a StarTeam

repository. StarTeam Check Out Checks out working copies of files from a StarTeam repository. StarTeam Create Label Creates a view label or a revision label in a StarTeam repository.



StarTeam Custom Command

Executes a StarTeam command supported by stcmd.exe.

StarTeam Delete Local Deletes local revisions of files from a working folder mapped to a StarTeam repository’s folder.

StarTeam File Enumerator Obtains a collection of files stored in a StarTeam repository and performs child operations for each file in the collection.

StarTeam Lock Locks files in a StarTeam repository. StarTeam Remove Removes files from a StarTeam repository. StarTeam Unlock Unlocks files in a StarTeam repository. StarTeam Update Status Updates file statuses in a StarTeam repository.

For more information on operations of this group see S

opera

tarTeam Category in the Version Control Systems Operations document or in on-line help.

Subversion Category The Subversion category includes the following tions:

Operation Description Get Changes From Gets a list of mSubversion repository.

odified, added and removed files from a Subversion

S tories,ubversion Add Adds files, direc or symbolic links to Subversion’s repository. S king copiubversion Chec out Checks out work es of files from the repository. S ing copiubversion Cleanup Cleans up work es by removing locks that resume unfinished

operations. S ade to wubversion Commit Sends changes m orking copies of files to the repository. SC

ersionubversion Custom Executes a Subvommand

command.

S directoubversion Export Exports a clean ry tree. S n abo

ontentubversion File Enumerator Gets informatio ut files kept in Subversion’s depot without

accessing their c s and saves this information to a variable. Subversion Import Commits a copy of PATH to URL recursively. S irectorubversion MkDir Creates a new d y under Subversion. S ges maubversion Revert Undoes all chan de to local copies of files kept in the

repository. S of wor

es it to aubversion Status Gets the status king copies of files and directories and posts it

to the log or sav variable or to a file. Subversion Update Updates working copies of files.

For more information on operations of this grouOp

p see Subversion Category in the Version Control System erations document or in on-line help.



Surround SCM Category wing oThe Surround SCM category includes the follo perations:

Operation Description Get Changes From Surround SCM Gets a list of m

Modified, added and removed files from a

Surround SC repository. Surround SCM Add Adds files to a Surround SCM repository. Surround SCM Check In Sends changes

ository. made to working copies of files to a Surround

SCM repSurround SCM Check Out Checks out w

y. orking copies of files from a Surround SCM

repositorSurround SCM Commit Changelist Sends changes

chang made to working copies of files within the

specified elist to a Surround SCM repository. Surround SCM Create anch Creates a new bra Br nch in a Surround SCM repository. Surround SCM Create Repository Creates a new folder in a Surround SCM repository. Surround SCM Custom Command Runs an arbitrary Surround SCM command. Surround SCM Delete Deletes files and folders from a Surround SCM repository. Surround SCM File Enumerator Returns a collection of files stored in a Surround SCM

y andn.

repositor executes child operations for each file of this collectio

Surround SCM Freeze Branch Prevents users branc

from making changes to files stored in the specified h.

Surround SCM Get Gets files from a Surround SCM repository. Surround SCM Label Sets a label

y. to files or folders within a Surround SCM

repositorSurround SCM Undo Check Out Undoes the ch

sitory. eckout of files within a Surround SCM

repoSurround SCM Unfreeze Branch Unfreezes the previously frozen branch.

For more information on operations of this group see S

lowing o

urround SCM Category in the Version Control Systems document or in on-line help.

Team Coherence Category The Team Coherence category includes the fol perations:

Operation Description Get Changes From Team Coherence Gets a list of m

ry. odified and added files of a Team Coherence

repositoRun Team Coherence Command Runs a Team Coherence command. Team Coherence Add File(s) Adds files to a Team Coherence repository. Team Coherence Assign Label Assigns a versio

oherencen label to a specific revision of files under a

Team C repository.



Team Coherence Check In File(s) Checks in files from your working folder to a Team Coherence ry. reposito

Team Coherence Check Out File(s) Checks out fi folde

les from a Team Coherence repository to your working r.

Team Coherence File Enumerator Obtains a collthen per

n.

ection of files stored in a Team Source repository foand

collectiorms child operations for each file in the

Team Coherence Get File(s) Obtains a specry.

ific revision of files stored in a Team Coherence reposito

Team Coherence Promote File(s) Promoter

s filesomotio

stored in a Team Coherence repository to the n level defined in that repository. next p

Team Coherence Remove File(s) Removes files from a Team Coherence repository. Team Coherence Remove Project or RemoveFolder reposito

s a prory.

ject or a folder from a Team Coherence

Team Coherence Undo Check Out Undoesrepositor

the y.

checkout of files under a Team Coherence

For more information on operations of this group see Te

trol Cry inc

am Coherence Category in the Version Control Systems Operations document or in on-line help.

Team Foundation Version Con ategory The Team Foundation Version Control catego ludes the following operations:


A s and y. dd File(s) And Folder(s) to TFVC repositor

Adds file folders to the Team Foundation Version Control

Bn itemon Versce.

ranch in TFVC FoundatiCopies a from one location to another in the Team

ion Control repository and in the local workspa

Check in File(s) to TFVC Checks in files y.

to the Team Foundation Version Control repositor

Check Out File(s) From TFVC repositorChecks out files

y. from the Team Foundation Version Control

Delete File(s) And Folder(s) From TFVC

RemovesControl r

files eposit

and folders from the Team Foundation Version ory.

Delete Label From TFVC Deletes labels eposit

from files kept in the Team Foundation Version Control r ory.

Get Changes From TFVC Gets a list of mon Ve

odified, added and deleted items from the Team rFoundati rsion Control reposito y.

Get File(s) From TFVC Control rGets the speci

epositfied files from the Team Foundation Version ory.

TFVC Working Folder between Foundati

Creates, modiwor

on Ve

fies, or displays information about mappings kspace folders and corresponding Team rsion Control repository folders.



Lock in TFVC Version Locks or unlock

Control rs files or folders in the Team Foundation epository.

M changes Control rerge in TFVC Applies from one branch of the Team Foundation

Version epository into another.

Rename or Move in TFVC RenameControl r

s or moveepository

s files stored in the Team Foundation Version .

Set Label to TFVC File(s) Version Specifies labe

Controls for files stored in the Team Foundation l repository.

Undelete in TFVC Restores itemson Ve

that were previously deleted from the Team Foundati rsion Control repository.

Undo the Pending Changes in TFVC Deletes pendinon Versi

g changes from the workspace of the Team Foundati on Control repository.

Unlabel in TFVC Removes a labeeposit

l ory.

from an item in the Team Foundation Version Control r

For more information on operations of this group see Team Foundation Version Control Category in the on-lin

operat

Version Control Systems Operations document or in e help.

Unit Tests Category The Unit Tests category includes the following ions:

Operation Description Run JUnit Test Runs a unit test of your .NET code using JUnit. Run MSTest Runs a unit test of your .NET code using MSTest. Run NUnit Test Runs a unit test of your .NET code using NUnit.

For more information on operations of this group see Uelp.

The Wait category includes the following operations:

nit Tests Category in the Testing, Profiling and Issue-Tracking Operations document or in on-line h

Wait Category

Operation Description Wait for Date and Time Delays the macro execution for the specified time period, or until

the specified date and time occur. Wait for File Delays the macro execution until the file attributes are checked, file

exists or does not exist, file contents are changed or meets the condition, or until the specified time period elapses.

Wait for INI File Delays the macro execution until the specified section, key or key value exists or does not exist, the specified key value is changed or meets the condition, or until the specified time period elapses.

Wait for Process Delays the macro execution until the desired process is created, or until the specified time period elapses.


Operations Reference


187

Wait for Registry Delays the macro execution until the predefined key or key value exists or does not exist, the specified key value is changed or meets the condition, or until the specified time period elapses.

Wait for Remote Computer Delays the macro execution until the specified remote computer responds, or until the specified time period elapses.

Wait for Variable Delays the macro execution until a macro variable is assigned the specified value, or until the specified time period elapses.

Wait for Window Delays the macro execution until the desired window is created, or until the specified time period elapses.

For more information on operations of this group see Wait Category in the General-Purpose Operations document or in on-line help.

WMI Category The WMI category offers operations that let you use functionality of Windows Management

Instrumentation in your macros. Windows Management Instrumentation is a component of Windows operating systems that is aimed at collecting computer management information in the enterprise environment and performing various administrative tasks. The WMI operations operations that let you automate these tasks with ease. The category includes the following operations:

Operation Description COM Class Enumerator (WMI) Obtains the collection of COM classes registered on a

computer and performs child operations for each element of this collection.

Control NT Service (WMI) Starts, stops or pauses the service run. Get COM Class Extended Info (WMI) Obtains extended information about a COM class registered

on a computer. If COM Class Is Registered (WMI) Checks whether a COM class is registered on a computer and

performs child operations according to the result of the check.

If Process Is Running (WMI) Checks whether a process is running and performs child operations according to the result of the check.

If Service Is Running/Stopped/Paused (WMI)

Checks whether a service is running (stopped or paused) and performs child operations according to the result of the check.

Install Application (WMI) Installs or advertises an application on the local or remote computer.

NT Service Enumerator (WMI) Obtains the collection of services registered on a computer and performs child operations for each element of this collection.

Process Enumerator (WMI) Obtains the collection of processes running on a computer and performs child operations for each element of this collection.

Remote Shutdown/Power Off/Reboot (WMI)

Shuts down, powers off or reboots a remote computer.

Operations Reference


188

Run Process (WMI) Launches an application. Terminate Process (WMI) Terminates a running process. Uninstall/Reinstall Application (WMI) Uninstalls or reinstalls an application on the local or remote

computer. Upgrade Application (WMI) Upgrades an application installed on the local or remote

computer. For more information on operations of this group see WMI Category in the General-Purpose Operations

document or in on-line help.

Index


189

Index .bbp files .............................................................45 .bxp files .............................................................45 .msbuild files ......................................................45 .NET Tools Category........................................158 .proj files.............................................................45 .target files ..........................................................45 .tasks files ...........................................................45 .vmp files ............................................................45

A Adding operations to macros..............................38 Adjusting operations in macros ..........................38 Analyzing results of macro runs.........................55 Append From File – menu and toolbar item.......45 AQCommunity ...................................................19 Archivers Category...........................................159 Authenticode Category .....................................160 Automated Build Studio .......................................6

Basic concepts ................................................24 Command-line arguments.............................141 Community site ..............................................19 Exit codes .....................................................143 FAQ ................................................................19 Getting support ...............................................19 Newsgroups ....................................................19 Overview ..........................................................6 Samples...........................................................19 Using With Windows Firewall .......................21 What's new......................................................14 Working via COM........................................147

Automated Build Studio Client/Server....100, 113, 114 Connection Parameters .................................108 Overview ......................................................100 User permissions ..........................................106 Using the Client/Server functionality ...........100 Web Interface – About .................................113 Windows Sidebar Gadget – About ...............114

Automated Build Studio Gadget – About.........114 Automated Build StudioSystem requirements......9 Automated Macro Player....................64, 141, 143

About ..............................................................64 Command-line arguments.............................141 Exit codes .....................................................143 Using With Windows Firewall .......................21

AutomatedQA Tools Category .........................160 B

Basic concepts ....................................................24 Batch Run – menu and toolbar item ...................53 bbp files ..............................................................45 Begin a progress group – property......................41 Borland Compilers Category ............................161 Breakpoints.......................................................127

About ............................................................127 Conditional breakpoints................................127

Breakpoints panel .............................................129 Build Strategies...................................................67 Build Tools Category........................................162 Burn CD/DVD Category ..................................162 bxp files ..............................................................45

C Changing operation properties............................41 Charts................................................................118

About ............................................................118 Chart types....................................................121 Charts panel ..................................................118 Moving data from one computer to another .122 Viewing data stored on another computer ....122

Child operations..................................................24 COM – Working with Automated Build Studio

via .................................................................147 Command-line arguments.................................141 Communication Category.................................162 Community site...................................................19 Concurrent execution of operations....................82 Concurrent Versions System Category.............163 Conditional breakpoints....................................127 Configurations ....................................................45 Connection Parameters .....................................108 Constants ............................................................84

About ..............................................................84 Basic concepts ................................................24 Creating ..........................................................86 Using in macros ..............................................84 Using in operation properties..........................88 Using in scripts ...............................................89

Continuous integration support...........................67 Creating a new macro .........................................35

Index


190

D Debugging macros............................................124

About ............................................................124 Breakpoints panel .........................................129 Conditional breakpoints................................127 Running to the cursor ...................................126 Stepping through the macro..........................126 Using breakpoints .........................................127 Watches panel...............................................128

Description – property ........................................41 Different Configuration Settings – column ........45 Distributed builds ...............................................74

About ..............................................................74 Creating macros for ........................................76 Scenarios.........................................................75

E Enabled – property .............................................41 Enabled in Configurations – column ..................45 Environment attribute .........................................84 Errors ..........................................................58, 134

Handling errors in macros ..............................58 Handling exceptions in scripts......................134

Exceptions – Handling exceptions in scripts ....134 Execute Category..............................................164 Exit codes .........................................................143 Export – menu item ............................................55 Exporting macro run results ...............................57

F FAQ ....................................................................19 Files and Directories Category .........................164 Firewall – Using Automated Build Studio and

Windows Firewall...........................................21 Frequently asked questions.................................19 Frequently Used Category ................................165 FTP Category....................................................165

G Gadget...............................................................114 Getting support ...................................................19 Go to Message – menu and toolbar items...........55

H Handling .....................................................58, 134

Errors in macros .............................................58 Exceptions in scripts.....................................134

Handling exceptions in scripts..........................134 Help Compilers Category .................................166 HTTP Category ................................................166

I Incrementing the Build Version Number ...........62

Inserting one macro into another ........................45 Installers Category ............................................167 Integration With Visual Studio.....................92, 95

About ..............................................................92 Key features....................................................92 Running ABS macros from Team Explorer ...95

Interactive Category .........................................168 Internet Information Services (IIS) Category ...168 Issue Tracking Category ...................................169

J JediVCS Category ............................................170

L Loading macros ..................................................45 Log panel ......................................................24, 55

About ..............................................................24 Working with..................................................55

Log to summary – property ................................41 Logging Category .............................................170 Logging macro runs............................................54

M Macro configurations..........................................45 Macro File node (Integration with Team Explorer)

........................................................................95 Macro panel ........................................................24 Macro presets....................................................102 Macro run results – Exporting ............................57 Macro runs..............................................53, 55, 64

Analyzing results of macro runs .....................55 How to run a macro ........................................53 Pausing macro runs.........................................53 Scheduling macro runs ...................................64 Stopping macro runs .......................................53 Triggered by changes in files under source

control.........................................................67 Macro Runs node (Integration with Team

Explorer).........................................................95 Macros ..........................................................35, 45

About ..............................................................24 Calling operations from scripts.....................136 Changing operation properties........................41 Changing operation properties from scripts..136 Creating a new macro .....................................35 Debugging ....................................................124 Handling errors in macros ..............................58 Incrementing the Build Version Number........62 Inserting one macro into another ....................45 Loading of.......................................................45 Logging macro runs........................................54 Saving of.........................................................45

Index


191

Sending notifications from macros.................56 Using variables and constants.........................84 Working with operations and operation

properties in scripts...................................136 Message – column ..............................................24 Microsoft Compilers Category .........................171 Microsoft Compilers for Smart Device Category

......................................................................171 Microsoft Virtual Server Category ...................172 Microsoft Visual SourceSafe Category ............173 Misc Category ..................................................173 Modifying operation properties ..........................41 Moving charts data from one computer to another

......................................................................122 msbuild files .......................................................45 MSBuild projects – Running ABS macros from 94 MSBuildABSTask.dll assembly – About ...........94 Multi-threaded execution of operations..............82

N Newsgroups about Automated Build Studio ......19 Notifications – Sending of..................................56

O Object Model ....................................................133 Operation order in macros – Changing of ..........38 Operation properties – Changing from scripts..136 Operations

About ..............................................................24 Adding operation to macros ...........................38 Calling operations from scripts.....................136 Changing operation properties in scripts ......136 Changing the operations order in macros .......38 Removing from macros ..................................38 Working with operations in scripts...............136

Operations panel .................................................24 Oracle Category................................................174 Order of operations in macros – Changing of ....38 Ordinary constants..............................................84 Ordinary variables ..............................................84 Other Compilers Category................................174

P Parallel builds .....................................................74 Parallel execution of operations .........................82 Patch Management Category............................175 Pause – menu and toolbar item...........................53 Perforce Category .............................................175 Prepare Code Category.....................................175 proj files..............................................................45 PSTools Category .............................................176 PVCS Category ................................................177

R Rational ClearCase Category............................177 Read/Write Category ........................................178 Remote Macro Execution Category..................178 Removing operations from macros.....................38 Results of macro runs ...................................55, 57

Analyzing........................................................55 Exporting ........................................................57

Run – menu and toolbar item..............................53 Run From Selected Operation – menu and toolbar

item .................................................................53 Run Selected Operation – menu and toolbar item

........................................................................53 Run Selected Operation with Children – menu and

toolbar item.....................................................53 Run submacro if operation fails – property ........41 Running macros......................................53, 64, 67

Analyzing results of macro runs .....................55 From MSBuild projects ..................................94 From Visual Studio Team Explorer................95 How to run macros .........................................53 Running at certain point in time .....................64 Running when files under source control get

changed.......................................................67 Scheduling macro runs ...................................64

Running to the cursor .......................................126 S

Samples...............................................................19 Saving macros.....................................................45 Scheduling macro runs .......................................64 Scripts in Automated Build Studio ...........132, 134

Basics............................................................132 Calling operations from scripts.....................136 Changing operation properties from scripts..136 Handling exceptions in scripts......................134 Object model.................................................133 Using variables and constants in scripts .........89

Select Message – menu and toolbar item ...........55 Sending notifications ..........................................56 Show History – toolbar item...............................55 Sounds for Automated Build Studio Events .....154 Source Code Tools Category ............................179 SourceGear Vault Category..............................179 SourceOffSite Category....................................180 SourceSafe Category ........................................173 SQL Category ...................................................181 Standard Category ............................................181 StarTeam Category ...........................................182 Stepping through macros ..................................126 Stop – menu and toolbar item.............................53

Index


192

Stop execution if operation fails – property .......41 Stored variables ..................................................84

About ..............................................................84 Command line initialization ...........................91

Subversion Category ........................................183 Support – Contacting AutomatedQA support team

........................................................................19 Supported tools ...................................................10 Surround SCM Category ..................................184 System constants ................................................84 System requirements.............................................9 System variables .................................................84

T target files ...........................................................45 tasks files ............................................................45 Team Coherence Category ...............................184 Team Explorer – Running ABS macros from ....95 Team Foundation Version Control Category ...185 Technical support ...............................................19 Thread-relative attribute .....................................84 Time with Children – column.............................24 Timeout – property .............................................41 Tracing Task Triggers ........................................71

U Unique name – property .....................................41 Unit Tests Category ..........................................186 User interface – Overview..................................29 User permissions – Automated Build Studio

Client/Server.................................................106 Using breakpoints .............................................127 Using macro configurations................................45 Using the Client/Server functionality ...............100

V Variables.............................................................84

About ..............................................................84 Basic concepts ................................................24 Command line initialization ...........................91 Creating ..........................................................86 Using in macros ..............................................84 Using in operation properties..........................88 Using in scripts ...............................................89

Version Number – Incrementing ........................62 Viewing charts data stored on another computer

......................................................................122 Viewing results of macro runs............................55 Visual SourceSafe Category .............................173 Visual Studio ................................................92, 95

About integration with....................................92 Running ABS macros from Team Explorer ...95

vmp files .............................................................45 W

Wait Category...................................................186 Watches panel...................................................128 Web Interface – About .....................................113 What's new..........................................................14 Windows Firewall – Using Automated Build

Studio and Windows Firewall ........................21 WMI Category..................................................187 Working With Automated Build Studio via COM

......................................................................147 Working With Source Control Systems ...........145 Writing Scripts in Automated Build Studio......132

Basics............................................................132 Calling operations from scripts.....................136 Changing operation properties from scripts..136 Handling exceptions in scripts......................134 Object model.................................................133 Using variables and constants in scripts .........89

Getting Started With Automated Build Studio 4

Documents

Transcript of Getting Started With Automated Build Studio 4