posted on March 03, 2008 23:46
For FinalBuilder 6, we wrote a brand new custom action API for .NET programmers. The new API has three main purposes:
- Reduce the learning curve for developers who want to create custom FinalBuilder actions
- Minimise boilerplate code on the part of the developer, so custom actions are simpler and quicker to write.
- Feel more like .NET programming than the old API, so .NET developers are comfortable with it.
For this article, I'm going to show a sample custom action that I created using ActionStudio, Visual Studio 2005 and C#.
Updating Older Actions
If you're updating .NET based actions from FinalBuilder 4 and 5, there's no need to rewrite. See this forum post made about the backwards-compatible Interop assembly for older actions.
The demo action uses the System.String.Format() method to format a string, with arguments provided from FinalBuilder variables. You can download a zip file with the finished action.
To get started, I fired up ActionStudio (under the Tools menu in FinalBuilder 6), and chose Package -> Add New Action to add a new action.
I'm not going into the details of the action definition (you can see it in the .fbap file in the zip file), but I created a .NET based action called "Format String", with two Properties named FormatString and Arguments. I also added a property page to configure the properties at design time.
I fired up Visual Studio and created a New C# Class Library Project.
To use the API, you need to add two new references to the project file - VSoft.CustomActionApi.dll and VSoft.CustomActionInterop.dll.
To add them, right-click on the project then choose "Add Reference..." and click the "Browse" tab. The assemblies are located inside the FinalBuilder 6 program directory, under the ActionDefs\Assemblies\2.0 directory.
Once the References are added, the project will look like this:
Rename the default Class1 to FormatStringAction, and add a using clause for namespace VSoft.CustomActionApi.
Edit the class so it descends from StandardAction, and use Ctrl-Period to "Implement abstract class..."
Here is the stub class:
Implement the class methods. Here is the entire finished class:
Notes for each method:
- The ExpandProperty helper method gets the value of a property, expanding any variable references (like %MyVariable%) before returning. The FailIfBlank parameter can be set to automatically fail the action if the property is blank.
- The action sends an informational log message which takes formatted parameters.
- If the String.Format() method fails, the FormatException is caught and the action throws a VSoft.CustomActionApi.ActionException. If this exception type is raised by an action, FinalBuilder will log the exception message as an error and fail the action.
- The final message is highlighted as "Success" in the log, using the MessageType enum.
The ValidateNonEmptyProperty() method is a helper method which automatically fails validation if the property's value is blank. Some alternate ways to fail validation are to call the SendValidationError() method, or to raise an ActionException.
This private method goes through the array of argument variables and gets their values at runtime. If a variable doesn't exist then the action throws an ActionException. This action makes use of the Context property to access the FinalBuilder variables namespace.
There you have it, a complete usable FinalBuilder action, with full argument validation, tagged logging, variable interaction, and taking full advantage of the .NET Framework - in 40 lines of C# code.
Build the new action and copy the assembly to ActionDefs\Assemblies\2.0.
Launch FinalBuilder. Search for your new action and add it to a FinalBuilder project:
Configure it with some silly values:
- To see some more complex demo actions, including an iterator action, take a look at the file FBDotNetExamples.fbap in the FinalBuilder ActionDefs directory. There is a corresponding solution file, "Dot Net Examples.sln", in the FinalBuilder program directory under ActionDefs\Examples\dotNet.
- The VSoft.CustomActionApi.dll assembly includes full XML documentation, so every method and property should automatically display help information in Visual Studio.
- There is a VSoft.CustomActionApi.chm help file, located alongside the Vsoft.CustomActionApi.dll file inside the ActionDefs\Assemblies\2.0 directory. The help file contains documentation for all classes, methods and properties, as well as some more sample source code.
- The Vsoft.CustomActionApi.dll assembly is not obfuscated in any way, so you can open it in a tool like Reflector to see how it works internally.
- If you're stuck on anything, don't hesitate to leave a comment or email support at finalbuilder dot com