A Custom Action Builder class allows you to control how your action interacts with the AppLife Make Update application and the update build process. Custom Action Builders are not required in order to create and implement custom actions. For most situations, and especially actions that will be used only once, the default Action Builder will provide all that is needed. When you have authored an action that is intended for extensive use, or to be used by other developers, creating a custom action builder allows you provide a more robust and intuitive interaction with Make Update.
The reasons you will implement a Custom Action Builder are:
•You want to validate the properties of your action before an update can be built and published.
•You want to implement a custom user interface to configure your action.
•You want to change the name and icon that Make Update displays when interacting with your action.
•You want to implement a pre and/or post build action around your action.
A Custom Action Builder is a class that inherits from the Kjs.AppLife.Update.Engine.Core.Design.ActionBuilder class. This class is located in the Kjs.AppLife.Update.Engine.Core.Design.dll. Refer to the F1 help for implementation details of the methods and properties of this class.
To link your custom action to its corresponding action builder, you add an ActionBuilderAttribute to your custom action class declaration that specifies your action builder.
From within the action builder, you can reference the action itself with the base class Action property.
Adding Validation
Overriding the ValidateActionCore method allows you to evaluate your action for a valid configuration. This method is called by Make Update when the project is validated. To indicate that your action is not valid, simply add a string description to the errors parameter. This description will be used within the Make Update user interface to indicate the action is invalid and prevent an update package from being built.
Adding a Custom User Interface
The default Action Builder utilizes a property grid to allow you to set the public properties of your custom action.
You can implement your own interface by creating a .Net control or user control.
The control needs to derive from System.Windows.Forms.Control. You should implement a property within your control that allows setting a reference to your Custom Action Builder from outside the user control. This reference will provide all the programmatic access you need from the user control code to interact with your action and Make Update.
The ActionBuilder’s Action property lets you change the state of the action as the user interface elements are manipulated.
Make Update is interested in knowing when the actions within the project have changed and when the actions become valid and invalid. When your user control changes action property values, you should call the SetActionDirty method of the Action Builder. Additionally, when the user control changes values that could affect the validation state of your custom action, you should call the ValidateAction method of the Action Builder.
To connect your custom editor to your action, you override the StartEditingAction method and use the IWindowsFormsActionEditorService to show your custom control in place of the default editor. Use F1 help on this method for additional assistance and an example of how this is performed.
Changing the Action Name and Icon
When you create a custom action, Make Update uses the class name and a default icon to display your action within the Make Update action list. You can change this behavior by setting the DisplayText and Image properties of your custom action builder.
Build Actions
Using a custom action builder, you can perform operations in a pre and post build action. These events occur before and after an update package is built. To use these events for special processing, you override the PrepareForBuild method and/or the CleanupAfterBuild method. Both methods have access to a Build Context object. Using the Build Context object, you can write to the build log by using the Log property. You also can access the project build folder using the BuildDirectory property.
Note: Custom Actions, Custom Builders and Custom Editors do not have to be in the same assembly. The assembly that contains your Custom Actions is included in any update package that utilizes those actions, as your update execution logic resides there. Builders and editors are not used during the update process on the target client. If your builders and editors are in the same assembly as your actions and they significantly increase the size of the assembly, you might consider placing them in a separate assembly to decrease the update package size.