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.
An NLua bug present in the NLua engine used by Ares, ILLiad, and Aeon will affect addons installed for ILLiad Client v9.2.4 or later and Ares Client/Server v5.0.9 or later, and also affects addons installed for Aeon Client/Server v5.1 or later. See Change #6 below for more information.
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.
If unsure about the required casing for a specific .NET property, please refer to Microsoft’s documentation on .NET classes.
Example
Incorrect format
Previously, an XmlElement's InnerXml property could be accessed using improper casing, such as the following camel case format:
element.innerXML
Corrected format
To avoid breaking changes, the property name should be adjusted to use Pascal case as follows:
element.InnerXml
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\?”):
local isRecordPage = RegEx.Match("fulldisplay\?", pageUrl).Length > 0;
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:
After updating the type to “string,” please review your code and ensure that any code using this value in a comparison with a number uses tonumber() function to change the string value to a number for the purposes of comparison.
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:
Place the following line of code at the top of the file, if it is not already present:
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: