Reading Legacy PlugExtraData

In the HS3 legacy API the PlugExtraData class permitted Objects of any type to be saved. This created some issues when data was stored by a plugin that has since been deleted/uninstalled. To remedy this, in the HS4 Plugin SDK, the PlugExtraData Class has been modified to only work with Strings. This eliminates these reference issues while still permitting plugins to store data of any type, as long as it has been serialized to a String using any number of serialization libraries like Newtonsoft.

This page covers the process for enabling your HS4 plugin to read objects that were stored in the PlugExtraData Class with the legacy API.

On this page:

Primitive Data Types

Primitive data types, strings, and Enums are not serialized or converted in any way and are stored as is in the new format. You can cast the data to the appropriate type by using the relevant Convert method or Enum.Parse method.

C# Example

C#

var ped = (PlugExtraData) HomeSeerSystem.GetPropertyByRef(devOrFeatRef, EProperty.PlugExtraData);
var mySavedString = ped("mySavedStringKey");
var mySavedInt = Convert.ToInt32(ped("mySavedIntKey"));
var mySavedByte = Convert.ToByte(ped("mySavedByteKey"));
var mySavedBool = Convert.ToBoolean(ped("mySavedBoolKey"));
var mySavedEnum As EMyExampleEnum = Enum.Parse(typeof(EMyExampleEnum), ped("mySavedEnumKey"));

VB.NET Example

VB

Dim ped As PlugExtraData = HomeSeerSystem.GetPropertyByRef(devOrFeatRef, EProperty.PlugExtraData)
Dim mySavedString As String = ped("mySavedStringKey")
Dim mySavedInt As Integer = Convert.ToInt32(ped("mySavedIntKey"))
Dim mySavedByte As Byte = Convert.ToByte(ped("mySavedByteKey"))
Dim mySavedBool As Boolean = Convert.ToBoolean(ped("mySavedBoolKey"))
Dim mySavedEnum As EMyExampleEnum = [Enum].Parse(GetType(EMyExampleEnum), ped("mySavedEnumKey"))

Objects

Any data that is not a primitive type or Enum is serialized to a JSON or Base64 string before it is transmitted to the plugin. If you serialized your data using a BinaryFormatter, follow the instructions in the Binary Data section. If you did not serialize your data at all, follow the instructions in the JSON Data section.

Binary Data

If you previously used a BinaryFormatter to serialize your objects to a byte array before saving them you can read them by converting them to a Base64 String and then proceeding with your original deserialization procedure using a BinaryFormatter. You may need to trim excess quotes or backslashes added on by the serializer.

C# Example

C#

var bts = Convert.FromBase64String(ped.Item("myObjectKey").Trim('\"', '\\'));
if (bts != null) {
	MyObjectClass desiredObject;
	var bf = new BinaryFormatter();
	using (var ms = new MemoryStream(bts)) {
		desiredObject = (MyObjectClass) bf.Deserialize(ms);
	}
}

VB.NET Example

VB

Dim bts = Convert.FromBase64String(ped.Item("myObjectKey").Trim(Chr(34), "\"))
If bts IsNot Nothing
	Dim desiredObject As MyObjectClass
	Dim bf = New BinaryFormatter()
	Using ms = New MemoryStream(bts)
		desiredObject = DirectCast(bf.Deserialize(ms), MyObjectClass)
	End Using
End If

JSON Data

If you did not serialize your data prior to saving it to the PlugExtraData class using the legacy API the data has been serialized as a JSON string. Deserialize it using a JSON serializer like NewtonSoft.

C# Example

C#

//Use the provided method
MyObjectClass myObject = ped<MyObjectClass>("myObjectKey");

//or do it yourself
var objectString = ped("myObjectKey").Trim('\"', '\\');
myObject = JsonConvert.DeserializeObject<MyObjectClass>(objectString);

VB.NET Example

VB

'Use the provided method
Dim myObject As MyObjectClass = ped(Of MyObjectClass)("myObjectKey")

'or do it yourself
Dim objectString As String = ped("myObjectKey").Trim(Chr(34), "\")
myObject = JsonConvert.DeserializeObject(Of MyObjectClass)(objectString)