Getting and setting values - data conversions

The Value property always returns data as a string. If the internal value is not a string, it is converted to a string. Although retrieving a string from the Value property never creates an exception message, setting data into the Value property can cause an exception if the automatic conversion fails.

Conversions to and from strings are performed according to the culture of the current session. If you are working with data types such as dates, decimals, or Booleans, using the Value property can cause your script to behave differently than you expect when it is run in a culture other than the one you used to test the script.

Generally you should avoid using the Value property in your scripts because of possible conversion problems. To access or set data values through a property or a component, use the GetValue, TryGetValue, and SetValue APIs. These APIs work with data in its native format.

GetValue

Use the GetValue API to retrieve data, as shown in this example:


Dim PromiseDate As Date = parms.Item.Properties("PromiseDate").GetValue(Of 
Date)()

Generally, you know the data type associated with the property or component and retrieve it directly. However, if the data stored internally is currently of a different data type that you request, the system attempts to automatically convert it. If it fails, an exception message is issued.

Nulls are common in data but often cannot be converted automatically. A special form of the GetValue API takes a WhenNull parameter and returns the parameter value instead of issuing a conversion exception message, as shown in this example:


Dim qty As Integer = parms.Item.Properties("Qty").GetValue(Of Integer)(0)

A conversion exception is still possible if the data is not null.

TryGetValue

If you are not sure a conversion will succeed, you can use the TryGetValue API, as shown in this example:


Dim PromiseDate As Date
If Not parms.Item.Properties("PromiseDate").TryGetValue(PromiseDate) Then
context.ShowModalMessage(
parms.Item.Properties("PromiseDate").Value 
+ " is not a valid date!")
Else
context.ShowModalMessage("The date is " + PromiseDate.ToString())
End If

This API returns False instead of generating an exception if the conversion attempt fails. If it succeeds, the value is placed in the parameter.

Use TryGetValue when your script is working with user-entered data. For example, a component is enabled for user input, and your script expects a date or decimal value entry. The user might type something that is not convertible. TryGetValue would work for this case. You can still retrieve the user-entered string with the Value property in order to create log messages or user feedback.

Also, be aware that in the case of a bound property, GetValue(Of String)() is not equivalent to the Value property. GetValue(Of String)() can fail because it attempts to convert some invalid user-entered data to the data type of the data source before converting it to a string.

SetValue

Use the SetValue API to place data into a property or component, as shown in this example:


parms.Item.Properties("PromiseDate").SetValue(PromiseDate)

Normally an exception is not issued by this API. SetValue takes whatever data type you give it. However, bound properties are stored internally in the data type of the underlying data source. If you give the API a different type of data, an automatic conversion is attempted. If the conversion fails, an exception is issued.