User-Defined Actions

Users can create their own custom actions and plug them into Visual Build's extensible architecture. This can be used to create action components for third party tools not supported by the built-in actions, to create actions that accept custom inputs for a particular build, encapsulate common functionality used in your builds, and more.

Action Components

Custom actions have two components:

•	Custom tabs that are displayed in the step properties dialog within Visual Build for entering any custom properties used by the action (custom tabs are optional).

•	The actual action logic that is performed when the step is built. All information about a user-defined custom action is stored in a .action XML configuration file stored in the Action Properties dialog or registered with the COM Register action.

Creating and Using Actions

A user-defined action is created by activating the Actions pane and choosing Edit | Insert Action on the menu bar. This will display the Action Properties dialog to define the action's custom UI pages and the action code itself that is executed when the step is built. Actions are stored and loaded from a <action name>.action file in the application data path. After an action has been created, it will be added to the Actions pane and new steps for that action can be created by double-clicking on the action.

Action Logic

The action logic for user-defined actions can be implemented in one of two ways:

•

Component

A component action is a COM component created in any development tool supporting creating COM components that implement interfaces, such as Microsoft Visual Studio and Embarcadero Delphi.

The component needs to reference the Visual Build Professional 10 Server Objects type library (defined in System\VisBuildSvr.dll in the installation path) and implement the ICustomAction interface. Action components have access to the Visual Build object model (for running programs, reading and modifying macros and step properties, logging messages, etc.). The return value of the BuildStep method determines the success/failure status of the step.

Note: See this topic for a discussion of how thread affects actions.

•

Script

A script action is implemented as script code (in any Active Scripting language).

The action code is implemented in a function named vbld_BuildStep (a return value of vbldStepStatFailed indicates that the action failed). Action script code has access to the Visual Build object model (for running programs, reading and modifying macros and step properties, logging messages, etc.) and can also access any script functions defined within Visual Build or other COM or .NET components installed on the system.

Sample Actions

The User Actions\User Actions.bld project in the Samples folder (and subfolders) demonstrates custom user actions written in VBScript, VB6, C#, and VB.NET.

In addition, several of the built-in custom actions are implemented as user actions. These actions can be used as templates for your own actions by examining the action's properties, GUI and script code.

Debugging User Actions

Components

1.	In your user action project's debugging properties, set C:\Program Files\VisBuildPro10\VisBuildPro.exe as the debug executable (optionally set the debug executable's arguments to the test .bld filename in double quotes).

2.	In your project IDE, set breakpoints in the project as desired, and start debugging the project.

3.	In Visual Build, open or create a project and add a step for the user action to the project.

4.	Build the project or the user action step.

5.	When the step gets built, the breakpoints in your user action will be stopped at, allowing the action to be debugged.

Script

1.	Use the code completing Script Editor to enter the action script code (the Script Editor immediate window can also be used to test functions and code).

2.	Create a step for the action and configure its properties.

3.	Build the project or step.

Any error output will be logged and the build output can be navigated to debug errors. If a syntax or runtime error occurs in the action script code, choose Go | Last Error on the menu, and the Script Editor dialog will be opened to the line of code in the script action where the error occurred, allowing the problem to be diagnosed and corrected.