Connectivity Software User's Guide and Reference
SparkplugPayload Class
Members  Example 



OpcLabs.EasySparkplug Assembly > OpcLabs.EasySparkplug Namespace : SparkplugPayload Class
Represent a Sparkplug payload, which contains a collection of Sparkplug metrics, and additional data.
Syntax
'Declaration
 
<ExceptionContractAnnotationAttribute(True)>
<CLSCompliantAttribute(True)>
<TypeConverterAttribute(System.ComponentModel.ExpandableObjectConverter)>
<ValueControlAttribute("OpcLabs.BaseLib.Forms.Common.ObjectSerializationControl, OpcLabs.BaseLibForms, Version=5.83.473.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", 
   DefaultReadWrite=False, 
   Export=True, 
   PageId=10001)>
<SerializableAttribute()>
Public NotInheritable Class SparkplugPayload 
   Inherits OpcLabs.BaseLib.Info
   Implements LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, System.Collections.Generic.IEnumerable(Of KeyValuePair(Of String,SparkplugMetricElement)), System.Collections.IEnumerable, System.ICloneable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable 
'Usage
 
Dim instance As SparkplugPayload
[ExceptionContractAnnotation(true)]
[CLSCompliant(true)]
[TypeConverter(System.ComponentModel.ExpandableObjectConverter)]
[ValueControl("OpcLabs.BaseLib.Forms.Common.ObjectSerializationControl, OpcLabs.BaseLibForms, Version=5.83.473.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", 
   DefaultReadWrite=false, 
   Export=true, 
   PageId=10001)]
[Serializable()]
public sealed class SparkplugPayload : OpcLabs.BaseLib.Info, LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, System.Collections.Generic.IEnumerable<KeyValuePair<string,SparkplugMetricElement>>, System.Collections.IEnumerable, System.ICloneable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable  
[ExceptionContractAnnotation(true)]
[CLSCompliant(true)]
[TypeConverter(System.ComponentModel.ExpandableObjectConverter)]
[ValueControl("OpcLabs.BaseLib.Forms.Common.ObjectSerializationControl, OpcLabs.BaseLibForms, Version=5.83.473.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", 
   DefaultReadWrite=false, 
   Export=true, 
   PageId=10001)]
[Serializable()]
public ref class SparkplugPayload sealed : public OpcLabs.BaseLib.Info, LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, System.Collections.Generic.IEnumerable<KeyValuePair<String,SparkplugMetricElement>>, System.Collections.IEnumerable, System.ICloneable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable  
Remarks

You can either deal with metrics individually, or you can choose to process or generate the whole payload. When you deal with metrics individually, the toolkit will assemble the payload from the metrics for you for sending purposes, and/or it will disassemble the payload to its constituent metrics when receiving. This generally easier gives easier and shorter code. You may want to deal with the payload as a whole e.g. if the payload represents a "dataset" with certain metrics whose data always belong together.

The Sparkplug payload acts as a collection of payload elements. Each payload element is a key-value pair, where the key is the name of the metric, and the value is a metric element. The metric element is represented by the SparkplugMetricElement class, and it comprises the Sparkplug metric data and optionally a Sparkplug metadata (see SparkplugMetricData and SparkplugMetadata). Since this is a generic collection, it is possible that the payload contains multiple occurrences of the same metric (metric with the same name, i.e. the same string in multiple payload element keys). This scenario is allowed in Sparkplug, and can be used e.g. for historical data transfer. However, in most cases, a metric will not appear more than once in the Sparkplug payload. For this reason, the Sparkplug payload also provider properties that allow you to access the metric data and metadata for the metrics as (read-only) dictionaries. The MetricDataDictionary property contains a read-only dictionary of Sparkplug metric data for metrics contained in the payload, keyed by metric name. Similarly, the MetadataDictionary property contains a read-only dictionary of Sparkplug metadata for metrics contained in the payload, keyed by metric name. You can use these dictionaries to easily access metric data and metadata by the metric name.

This class belong to the category of Sparkplug data transfer objects. They encapsulate the data used in Sparkplug, and carry them inside the toolkit and to/from your code. Sparkplug data transfer objects operations do not affect anything external (and not passed) to them; they simply care of their own data for the purpose of storage, retrieval, comparisons, serialization/deserialization and such.

 

Sparkplug is a trademark of Eclipse Foundation, Inc. "MQTT" is a trademark of the OASIS Open standards consortium. Other related terms are trademarks of their respective owners. Any use of these terms on this site is for descriptive purposes only and does not imply any sponsorship, endorsement or affiliation.

Example
// This example shows how to publish a payload with multiple command metrics for a given edge node.
//
// In order to publish or observe messages for this example, start the SparkplugEdgeNodeConsoleDemo program first.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasySparkplug;
using OpcLabs.EasySparkplug.OperationModel;

namespace SparkplugDocExamples.Consumer._EasySparkplugConsumer
{
    class PublishEdgeNodePayload
    {
        public static void Overload1()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the consumer object.
            var consumer = new EasySparkplugConsumer();

            // Create the payload with multiple command metrics.
            var payload = new SparkplugPayload
            {
                { "Simple", new SparkplugMetricData(42) },
                { "Simple2", new SparkplugMetricData(43) }
            };
            
            Console.WriteLine("Publishing...");
            try
            {
                consumer.PublishEdgeNodePayload(hostDescriptor, "easyGroup", "easySparkplugDemo", payload);
            }
            catch (SparkplugException sparkplugException)
            {
                Console.WriteLine($"*** Failure: {sparkplugException.GetBaseException().Message}");
                return;
            }

            Console.WriteLine("Finished.");
        }
    }
}
' This example shows how to publish a payload with multiple command metrics for a given edge node.
'
' In order to publish or observe messages for this example, start the SparkplugEdgeNodeConsoleDemo program first.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug
Imports OpcLabs.EasySparkplug.OperationModel

Namespace Global.SparkplugDocExamples.Consumer._EasySparkplugConsumer
    Class PublishEdgeNodePayload
        Public Shared Sub Overload1()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the consumer object.
            Dim consumer = New EasySparkplugConsumer()

            ' Create the payload with multiple command metrics.
            Dim payload = New SparkplugPayload From
            {
                {"Simple", New SparkplugMetricData(42)},
                {"Simple2", New SparkplugMetricData(43)}
            }

            Console.WriteLine("Publishing...")
            Try
                consumer.PublishEdgeNodePayload(hostDescriptor, "easyGroup", "easySparkplugDemo", payload)
            Catch sparkplugException As SparkplugException
                Console.WriteLine($"*** Failure: {sparkplugException.GetBaseException().Message}")
                Return
            End Try

            Console.WriteLine("Finished.")
        End Sub
    End Class
End Namespace
Inheritance Hierarchy

System.Object
   OpcLabs.BaseLib.Object2
      OpcLabs.BaseLib.Info
         OpcLabs.EasySparkplug.SparkplugPayload

Requirements

Target Platforms: .NET Framework: Windows 10 (selected versions), Windows 11 (selected versions), Windows Server 2016, Windows Server 2022; .NET: Linux, macOS, Microsoft Windows

See Also