This example demonstrates how to create a custom action, as well as a corresponding custom action builder and custom action editor to provide an Update Action that will perform a text file search on the deployed client that is being updated for a designated regular expression. The results are then further manipulated with customized .Net code using a Dynamic Code Action.

Custom actions in AppLife Update allow you to execute custom .Net code during the execution of an update package on the deployed client.  Authoring a custom action and adding it to an update consists of:

 

•Creating a .Net class that inherits from the UpdateAction class

•At a minimum, implement a parameterless constructor, Execute method, and a RollbackExecute method on the class.

•Compile the custom action assembly

•Add the assembly to the collection of custom action assemblies in AppLife Make Update

•Add the action to the project list.

 

Custom Actions can be further enhanced by creating a custom action builder. With a custom action builder, you can intervene during the update build process, validate the properties of a custom action, manipulate the action properties as the project file is saved, and launch a customized update action editor.

 

The update scenario demonstrated in this Quick Start is to migrate setting from a text-based configuration file that version 1 of the example application uses, to an xml-based configuration file that version 2 of the example application uses.

 

1.  Review how the AppLife Update Engine operates.  Our custom actions operate in this context.

2.  When added to the Make Update custom action assemblies list, our custom actions are configured within AppLife Make Update and persisted within the AppLife Update project file by interacting with public properties on the custom action classes.  Any public properties that are implemented will be configurable from AppLife Make Update and persisted with your project.

3.  Review the Update Context object.  We will use the context object’s SharedProperties property to pass information between the actions in this example.

 

Architecting our Custom Actions

We are going to create a custom action that searches a designated text file for a line that includes a designated regular expression. If the regular expression search finds a match, the entire line within the text file will be placed in a designated Shared Property within the Update Context Shared Properties collection so that it is available for further processing by the update. This custom action is named Search File Action.

Further processing will be performed by a second custom action that is defined within a built-in Dynamic Code Action.  Dynamic Code actions provide the ability to quickly create customized update activity.

Our Search File Action is further refined by adding a custom action builder.  In the custom action builder, we’ll validate the properties of the action, preventing Make Update from building the action with invalid input information.  We’ll also create and launch a custom update editor.  Our editor will replace the default property grid editor and provide an intuitive interface as well as validation feedback for the update designer.

 

4.  Open the Custom Actions solution with Visual Studio.  Within this solution you will find two projects.  The Custom Actions application and the Actions class library.

5.  Notice that the Actions project contains a reference to the Kjs.AppLife.Update.Engine.Core assembly and the Kjs.AppLife.Update.Engine.Core.Design assembly.  These assemblies are located in the [InstallDir]\PublicAssemblies folder where AppLife Update is installed.  The core assembly contains the UpdateAction base class from which all custom actions are derived. The design assembly contains the ActionBuilder base class used provide a custom action builder and editor.

 

Creating the SearchFileAction

The SearchFileAction derives from UpdateAction.  It contains an empty parameter-less constructor. This constructor is necessary, as without it, the Update Engine could not create an instance of this action.

 

There is a public FileName property that is used to store a path (relative to the deployed client application directory) to a local text file that will be searched when the update action executes.

 

There is a public Regex property that is used to store the regular expression that will be searched for within the identified text file.

 

There is a public SharedPropertyName property that identifies the key name of the Shared Property that will store the results of the regex search.

 

Adding these properties makes this action easily re-usable in other projects.

 

6.  The Execute method of this action backs up the value of the designated Shared Property (if it exists) so that it can be rolled back if the update fails.  Then, the designated text file is searched.

The user is kept informed by utilizing the base class OnProgressChanged method, and the update execution log file is updated using the UpdateContext Log property.

7.  The RollbackExecute method restores the original value of the Shared Property.  No other action is necessary to rollback the execution of this action.

To control the AppLife Make Update palette location of this action, attributes are placed on the class declaration.

[DisplayName("Search File")]

[Description("Search a text file for a regular expression and store the matching line in a shared property.")]

[Category("Files & folders")]

These attributes result in:

These attributes cleanly present the custom action within the Make Update application, however they are not required.  If they were omitted, the action would be in a category named “Misc” with an action name that matches the name of the class.

 

Creating the SearchFileActionBuilder class

Note: See Custom Action Builder.

Implementing an action builder for the SearchFileAction will provide validation functionality as well as launch a customized action editor user interface. The custom action editor is assigned to the action by adding a ActionBuilder class attribute to the action class.

[ActionBuilder(typeof(SearchFileActionBuilder))]

public class SearchFileAction : UpdateAction {

8.  Implement ValidationActionCore
This method checks to ensure that a search file name, regular expression, and shared property key name is provided.  If any of these properties are empty, Make Update will not build the project, and the action is adorned as being invalid.

 

 

9.  Implement StartEditingAction
In this method, the custom editor is instantiated and shown, replacing the default property grid editor.

 

Creating the SearchFileActionEditor

A custom action editor is a Windows Forms User Control.  When a custom action editor is created, the corresponding Action Builder instance is passed into the editor as a constructor parameter. We maintain a reference to the Action Builder and by extension, the Update Action. This reference is used to manipulate the Update Action from the custom editor.

The SearchFileAction editor provides textboxes and checkboxes to enter the necessary information required to configure the update action behavior.

 

Adding the actions to your action list

Once the Update Action and supporting classes are compiled into a .Net assembly, we can add the assembly to the custom action assemblies list.

 

Open the Project Settings dialog from the Project menu.  Then open the Custom Actions tab.

 

Add an assembly by clicking the Add an assembly button and browsing to your custom assembly.

 

Note:  AppLife Make Update loads the custom action assemblies that are used by the project.  When a custom action assembly is loaded, the assembly is locked by Make Update.  This could cause Visual Studio builds to fail if you reference your custom action assemblies in Make Update from the Visual Studio build location.  To unload the assemblies you will need to close AppLife Make Update.

 

Once an assembly has been added, its custom actions are placed in the action palettes and are available to be placed into the action list.  Custom actions can also be made available globally to all Make Update projects by placing the assembly into the Make Update AppDir/Custom Actions folder.  This folder is typically located at:

 C:\Program Files\AppLife Update\MakeUpdate\CustomActions

 

Update the Example Application using the Search File Action

Version 1 of the example application utilizes a text-based settings file.  Version 2 utilizes an Xml-based settings file.  In order to update a deployed Version 1, our update must migrate a couple of settings from the old to the new settings files.  To do this, we are going to utilize the Search File action, along with a few built-in Update Actions.

 

Step 1 – Find the settings of interest within the old text-based settings file

Step 2 – Parse the settings that are found using a Dynamic Code Action

Step 3 – Copy the new application assemblies and the new Xml Settings file using an Add & Replace files action.

Step 4 – If previous settings were successfully extracted from the existing settings file in Steps 1 and 2, then update the newly placed Xml file using a Change Xml Node action. Note: These actions are conditionally executed.

Step 5 – Delete the old settings file using a Delete files action.

 

Our update action list looks like this:

 

Search File Editor:

This action will search the OldSettingsFile.txt file for the line that has the Setting1=value, and if found, the entire line will be placed in a Shared Property named Setting1.

 

Parse the Settings values using a Dynamic Action:

The built-in Dynamic Code action provides a simpler method to add a custom action to an update.  To demonstrate this method, a Dynamic Code Action is used to parse the value out of the line that was found by the custom Search File Action.

 

The Dynamic Code action allows you to write a custom action directly within Make Update.  The action is compiled as the update package is built.  This action will read the Shared Property that the Search File action set, and parse the value.  The Shared Property is then updated to include only the value of the setting.

 

Copy the Application Assembly and new Xml Settings File

A built-in Add & Replace files action places the new files on the deployed client.

 

Updating the new Xml File

With the NewSettingsFile.Xml now present and populated with default values, the update must replace the default values with the entries from the previous text-based settings file. To accomplish this, a built-in Change Xml Node action is used.

 

Conditional Execution:

This action has a condition expression set.  The action is only executed if the shared property “Setting1” is not empty.

 

If the Shared Property “Setting1” is not empty, the NewSettingsFile.xml file is updated using an XPath query and the value of the Shared Property.

 

Deleting the old Settings File

The final step in this update process is to use the built-in Delete File action to remove the old settings file.

 

Summary

Creating custom actions for use with AppLife Update is extremely easy.  You are not limited to just the standard AppLife Update actions.  Custom actions allow you to easily define and execute .Net code during your software updates. 

Reference the API Reference documentation

 

Browse the Kjs.AppLife.Update.Engine.Core namespaces for more information on custom actions.