posted on July 29, 2010 20:12
FinalBuilder Server provides a set of triggers that start builds automatically based events, like the time of day, check-ins to a version control system, or changes to a file.
Version 7 adds script based triggers. These triggers run either an (Iron)Python or Powershell script, giving you ultimate of control over when your build is triggered.
Creating a script based trigger
From the FinalBuilder Server home page, create a new project or edit an existing one (I won't cover the details on that here).
Create a new trigger. Give it a name and set the trigger type to Script Based Trigger. Scroll down to the Scripting Options section of the page. You can choose the language of your script and enter it in the 'Script' box.
Triggering a build
An object is made available to both languages that allows you to interact with the build server. In Python, it is exposed as a module called Context, which you do not need to import. In PowerShell, it is exposed as a variable called $context.
The context object has 3 methods:
- SetTriggered(): This is the most important method of the Context object. Calling this method means that the build will be triggered
- AddTriggerOutputMessage(message): The string parameter passed to this method is logged in the build queue. Use this to provide information about the circumstances that triggered the build
- AddFileModificationItem(name, action, user, comment, type, version ): Adds information about a file that was involved in the build triggering. This is logged and also passed to FinalBuilder, for use in the Trigger Files Interator action
- ExecuteProgram(filename, workingDirectory, arguments): This method runs an executable under the context of user set to run the build. It returns an ExecutionResult object
- ComparisonDateTime: a DateTime property used to indicate when the trigger was last triggered, or when the last build started (which ever is more recent). It is useful when, for example, you are checking against a version control system and only want to find changes since the last build.
A stub IronPython module has been provided to allow you to test scripts stand-alone. The stub can be found at \Examples\Context.py.
The following simple script executes a program and triggers the build if the program exits successfully. It uses Context.py for stand-alone testing. The script can also be found in the examples directory:
#copy from here
from System import DateTime
app = 'cmd.exe'
wd = r'C:\Windows\System32'
if Context.ComparisonDateTime < DateTime.Now.AddMinutes(-30):
result = Context.ExecuteProgram(app, wd, '/c "echo hi"')
if result.ExitCode == 0:
Context.AddTriggerOutputMessage('%s successful, build will be triggered' % app)
print 'Build will not be triggered'
print '%s failed with return codee %d: %s ' % (app, result.ExitCode, result.StdError)
print 'Build has been run in the last 30 minutes - not running'
#copy to here
Things to note:
- Only the code between the copy from/copy to comments would be copied to the Trigger script
- You can import IronPython modules, such as time. To do this you will need to install IronPython and specify the install directory in the trigger
- You can use sys.path.append() to add any other directories from which you would like to import modules
- 'print' statements from the last run will appear under the Script area of the trigger
Triggering a build with PowerShell is a simple as calling
$context.AddTriggerOutputMessage("Triggered by PowerShell!")
To test your script before adding it to the trigger, you can load the Trigger and TriggerExecutionContext objects from FinalBuilderServer.Build.dll:
[reflection.assembly]::LoadFile("FinalBuilder Server Install Dir>\FinalBuilderServer.Build.dll")
$trigger = new-object VSoftTechnologies.FinalBuilderServer.Triggers.ScriptBasedTrigger
$context = new-object VSoftTechnologies.FinalBuilderServer.Triggers.TriggerExecutionContext($trigger)
Your scripts should be able to do just about anything that's normally possible in IronPython or PowerShell. Just keep a couple of things in mind:
- triggers are designed to be low-overhead and short-lived: you're best off keeping them as simple as possible
- the script will run in the context of the user that runs the build (set at the project or server level). That user will need access to any external resources that the script references.