Preventing Breaking Changes in ILLiad/Ares Addons After NLua Update

The version of NLua used by ILLiad has been updated to a new version in the ILLiad Client v9.2.4/9.2.5 release and will be released for Ares in the upcoming Ares Client v5.0.9 release. After this update, addons that worked with the previous versions of ILLiad and Ares may break when used with the updated versions of each product due to several changes in the required code syntax that the latest NLua version will implement.

Addon authors should review these changes against the code used by their addons and preemptively update those addons if necessary according to the instructions for each change listed below to avoid these breaking changes.

Change #1: Case Sensitivity for .NET Object Property Names

.NET object property names are now case sensitive and must be written in Pascal case where the first letter of each word in a compound word is capitalized.

Required code updates

All .NET object properties included in the addon code should be reviewed and changed to the proper casing.

Example

Incorrect format

Previously, an XmlElement's InnerXml property could be accessed using improper casing, such as the following camel case format:

Corrected format

To avoid breaking changes, the property name should be adjusted to use Pascal case as follows:

Change #2: Escaping Backslashes in .NET Regular Expression Patterns

Backslashes must now be escaped with a backslash in .NET regular expression (RegEx) patterns. After the NLua update, unescaped backslashes will result in an invalid escape sequence error.

Required code updates

All .NET RegEx patterns included in the addon code should be reviewed for backslashes and updated to escape these backslashes, if necessary.

Example

Incorrect format

The following is an example of a .NET RegEx pattern containing an unescaped backslash ("fulldisplay\?”):

Corrected format

The simplest fix is to escape the backslash with another backslash (i.e., changing "fulldisplay\?” to “fulldisplay\\?”):

Alternatively, if it is determined upon review that Lua pattern can be used instead, then the .NET RegEx pattern can be replaced as follows:

Change #3: Formatting for Integer Values Defined in config.xml

Number type settings with integer values defined in config.xml will have a ".0" appended to them after the NLua update (e.g., a value of “3” will become "3.0”). This will be an issue if the affected setting is used for something like a port number, where the updated value of "3.0" is not functionally equivalent to "3."

Required code updates

All settings with the type “number” included in the addon’s config.xml file should be reviewed to determine if the updated format will affect the functionality of the setting. If so, the type of the setting should be changed to the type “string.”

Example

The following is an example of a number-type setting that uses an integer value:

This setting will be set to a value of “3.0” after the NLua update. If the new value is determined to be inappropriate for the function of that particular setting, the type should be changed as follows:

Change #4: Use Correct Data Type for Arguments Passed to .NET Object Methods

Arguments passed to .NET object methods must now be of the correct data type. After the NLua update, any arguments passed to these methods that are of the incorrect data type will no longer be automatically converted to the proper data type and will cause errors when using the addon.

Required code updates

All .NET object methods included in the addon code should be reviewed and changed if necessary to ensure that the arguments passed to these methods are values of the correct data type.

Example

The CreateTextNode() method, which creates a text node in an XML document, takes a single string-type argument. Prior to the NLua update, a number-type argument could be passed into this method without issue because it would be automatically converted to a string, but this is no longer the case.

To resolve this issue, modify the argument passed to the CreateTextNode() function so that it is a value of the string data type (assume that stringTypeArgument below refers to a value of the string data type):

Note that, in this case, the tostring() method could also be used to convert the argument to a string, if appropriate:

Change #5: Convert Integer Arguments to Doubles for the ExecuteCommand Method

All ExecuteCommand methods used in ILLiad client or system addons that take an integer value as an argument will now need to have that value converted to a double in order to work. Failure to convert the integer value will result in the following error when using the addon:

Required code updates

All ExecuteCommand methods included in the addon code should be reviewed and modified if necessary to ensure that integer arguments passed to these methods are first converted to doubles.

Example

Assuming that tn is a variable holding an integer value for the ILLiad transaction number, the following is an example of the ExecuteCommand method using an integer value as an argument for the AddNote command:

To avoid errors, the value in the tn variable must first be converted to a double before it is passed to the ExecuteCommand method following the steps below:

1. Place the following line of code at the top of the file, if it is not already present:

2. Use the ToDouble method to convert the integer value in the tn variable to a double and then store this value in a new variable that will be used with the ExecuteCommand method:

Change #6: Byte arrays passed to .NET methods are converted to null due to an NLua bug

A bug present in the latest NLua engine used by Ares, ILLiad, and Aeon will now cause byte arrays (commonly written as Byte[]) to be converted to null when passed as arguments to .NET methods, which will cause those methods to fail.

Required code updates

All byte arrays used in the addon code should be reviewed and the addon code modified if necessary to avoid passing those values as arguments to any .NET methods used in the code.

Example

In the example below, the UploadValues WebClient method will return a Byte[] value and store it in the result variable. However, due to the NLua bug, the Byte[] value in the result variable will be converted to null when passed to the GetString method, causing it to fail:

Specific workarounds for issues caused by this bug will vary based on the context of how the Byte[] value is being used in the code. One workaround for this particular issue is to use the UploadString method instead of UploadValues, as the UploadString method will return a string and avoid using the Byte[] value altogether: