Plugin SDK
Space shortcuts
Page tree
Skip to end of metadata
Go to start of metadata

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:

We recommend not modifying or updating the data attached to a device or feature previously created using the legacy API unless you plan on upgrading the device/feature's entire configuration to avoid mixed configurations and unnecessary code.




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
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
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
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
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
//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
'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)