You can easily extend functionality offered by Batch Files’ built-in actions by designing your own using this SDK as a guide. Batch Files provides all the basic actions that perform general tasks, such as search and replace, insert, delete, etc.; however you may have a need to process files of a certain kind in a specific way, and hence require file-format-specific actions. With this SDK and basic VB.NET or C# programming skills you will be able to create your own custom actions that you can then use from within the program to effectively accomplish your goals.
Note that in this documentation the term “action” refers to
both the action that can modify a file in some ways, and a condition that
merely checks if the file matches certain parameters. By using this SDK you can
easily create both the actions and the conditions.
The following are the requirements that must be satisfied for custom action development:
· Basic VB.NET or C# programming skills.
· An Integrated Development Environment (IDE) capable of creating VB.NET or C# .NET Framework 2.0 class library projects. We recommend free Microsoft Visual Basic 2010 Express http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-basic-express or Microsoft Visual C# 2010 Express http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-csharp-express. Of course any version of Visual Studio 2005 and up will also work, as well as open source IDEs like SharpDevelop http://www.icsharpcode.net/opensource/sd/.
· This SDK with samples.
· Free Edition of any product that is part of Batch Files family, or Batch Files Complete Edition (custom action support is not included with any other product / edition combination).
The following conditions must be met in order for your compiled custom actions library to work with Batch Files:
· You must be running Free Edition of any product that is part of Batch Files family, or Batch Files Complete Edition (custom action support is not included with any other product / edition combination).
· Custom action loading must be enabled in program options.
· Your custom actions library must be placed in the program directory (that is the same folder where main application exe is located) and named as actions.<arbitraryname>.dll.
· Your custom actions library must target .Net Framework 2.0 x86.
· If your custom actions library has additional dependencies, all of them must be located in the program folder.
To get started, first open one of the included SDK sample projects in the SDK folder. Both VB.NET and C# versions are available and are equivalent to each other. Once you have opened the project using one of the recommended IDEs, study the project structure, references, and comments in code to get a quick overview of the key components.
For the purposes of making your own custom actions we recommend you create a new .NET 2.0 class library project, though you can use one of the included SDK projects as a base.
The project you create for your custom actions must meet the following requirements:
· It must be a .NET 2.0 class library project targeting x86 platform.
· It must reference Batch.Core.dll which is located in the product’s main folder.
· The output must be named actions.<arbitraryname>.dll.
Other than that there are no restrictions. You can reference other non-framework assemblies in your project, and even do interop with non-managed libraries if you need.
Typically an action is comprised of 3 classes aActionName which is the primary class that defined an action, aActionNameOptions which is additional class that defines action-specific options (if any), and aActionNameOptionsUI which provides a User Interface (UI) that provides access to action-specific options so they can be changed.
When naming your classes, we recommend you follow these guidelines:
· If you action is an action, prefix all its classes with an “a”; if it is a condition, prefix all its classes with an “ac”.
· If the class is an options class, add “Options” to the end of its name.
· If the class provides UI for the options, add “OptionsUI” to the end of its name.
When designing your action classes make sure all of them are Public and are CLS-compliant.
Below is a more detailed overview of the 3 classes…
This is the primary action class that encapsulates action’s definition and processing logic. It must implement BinaryMark.Batch.Core.iProcessingStep interface in addition to either BinaryMark.Batch.Core.iAction interface (if it is an action) or BinaryMark.Batch.Core.iConstraint interface (if it is a condition).
The following requirements must be met when designing this class:
· Must be Public
· Must implement iProcessingStep interface
· Must Implement iAction or iConstraint interface
· iProcessingStep.ID must be unique and to avoid collisions with built-in actions or actions from other libraries be prefixed by a 3-letter code of your choice.
· iProcessingStep.Type must be set to either: ProcessingStepType.StreamAction if you are designing a custom action that modifies file’s content; to ProcessingStepType.FileAction if you are designing a custom action that does not change file’s content but affects file system in any way; or to ProcessingStepType.Constraint if you are designing a custom condition.
· Please follow closely the sample action definition in the SDK sample project when defining and implementing other required properties.
If your action has any options that can be changed to affect action’s behavior, this is the class where these options should be defined. This class must inherit from BinaryMark.Batch.Core.ProcessingStepOptionsBase and additionally, if it represents options for a Condition, it must implement BinaryMark.Batch.Core.iConstraintOptions interface.
Program automatically saves action options to XML template file, so it is critical that this class fully supports XML Serialization, and all properties that represent action’s options must be Public and XML-Serializable.
The following requirements must be met when designing this class:
· All properties that represent action’s options must be Public and XML-Serializable.
· All members that are implemented from an interface or overridden from a base class must also be Public.
If your action has any options that can be changed to affect action’s behavior, this is the class where the User Interface that provides access to action’s options is defined. This class must inherit from System.Windows.Forms.UserControl.
When designing UI for action options, please follow the sample from the SDK. In particular your UI class should have a routine that will be called any time the UI needs to be synchronized with the options. In the SDK this routine is called Prepare.
Note that for compatibility reasons, all UI elements should fit into 500 x 350 pixels area, and thus your action options control should not exceed this size. If you need to place large number of UI elements, consider using tabs to accommodate all of them.
Also note that only one instance of this class will be created and used by the program to conserve resources. So, if there are multiple instances of the same custom action, they will share one instance of this class. Keep this in mind when designing it!
As was mentioned previously, any action must implement iAction interface and any condition must implement iConstraint interface. Each of these interfaces defines one primary function that performs the processing taking in BinaryMark.Batch.Core.ProcessingObject as its input:
· ProcessingObject iAction.Process(ProcessingObject input)
· BinaryMark.Batch.Core.ConstraintCheckResult iConstraint.Check(ProcessingObject input)
Note that both processing functions are instance methods, and should your action have any associated options, these must be accessible via an instance field to the processing functions. See the sample project for details.
ProcessingObject represents the file being processed and as such provides access to its data using the following key properties:
· System.IO.Stream InputStream – represents file’s data (content) in its current state: either file’s original content if no actions have been performed, or the output of the previous action. This is the data your action will work with.
o By default the initial position of the stream is set to the beginning, i.e. 0.
o The Stream can be either System.IO.FileStream or System.IO.MemoryStream.
· Stream OutputStream – represents the stream to which your action should write (output). Conditions do not use this property, only actions - do.
o The Stream can be either FileStream or MemoryStream.
· System.IO.FileInfo OriginalFileInfo – represents the original file’s information. Note: the original file is not guaranteed to exist; this property simply holds the information about the file’s origin.
· FileInfo CurrentFileInfo – represents the current file’s information, if it has changed. Typically it will be Null (Nothing), meaning that it has not changed and is the same as OriginalFileInfo.
· bool WasModified – if the action has modified file’s content in any way, set this to true before returning.
· bool WasPerformedFully – set this to true if the action or condition was fully performed and not exited due to some error.
· string ProcessingSummary – you may optionally provide a meaningful summary of the processing tasks that have been performed.
Individual file’s processing flow can be described as follows:
1. Check ProcessingObject input for any bad state (i.e. ProcessingObject.InputStream is Null (Nothing), or ProcessingObject.InputStream.Length == 0).
2. If your action or condition has any options associated with it, check all of them to ensure they are all valid.
3. Access the ProcessingObject.InputStream property that holds file’s data to actually begin processing.
4. Perform primary processing. An action would at this point write (modified) data to ProcessingObject.OutputStream, while a condition would only perform various checks.
5. When primary processing is done, set a few miscellaneous properties on ProcessingObject, such as WasModified.
6. Finally, you should return the result:
· For actions that have successfully processed a file this would be done by having return input as the last line in the processing function, where the input is the input ProcessingObject.
· For actions that encountered an error, you would need to call a function input.SwapStreamsAndReturn, where the input is the input ProcessingObject. This is needed because the ProcessingObject.OutputStream was not finalized/written to due to an error.
·
For conditions, you should return a new instance of ConstraintCheckResult with the ConstraintCheckResult.Pass
property set to indicate if the condition checks have been passed (true),
or they failed (false). If the condition checks have been
passed, this means that subsequent actions associated with this condition in
the Action Sequence will be performed; while if the condition checks have not
been passed, any subsequent actions associated with this condition in the
Action Sequence will be not performed.
We suggest you closely study the sample project in the SDK folder, read all the comments in the source code files, and closely follow the outlined structure when designing your actions. This, together with your VB.NET and/or C# skills should be sufficient to allow you to develop your own custom actions and extend the functionality offered by Batch Files.