![](dotnetdiagramimages/OpcLabs_EasyOpcUA_OpcLabs_EasyOpc_UA_PubSub_OperationModel_EasyUASubscribeDataSetArguments.png)
'Declaration
<CLSCompliantAttribute(True)> <ComDefaultInterfaceAttribute(OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._EasyUASubscribeDataSetArguments)> <ComVisibleAttribute(True)> <GuidAttribute("0DF356DA-30CF-48D1-AE01-9626CDBE4155")> <TypeConverterAttribute(System.ComponentModel.ExpandableObjectConverter)> <ValueControlAttribute("OpcLabs.BaseLib.Forms.Common.UniversalValueControl, OpcLabs.BaseLibForms, Version=5.80.82.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", Export=True, PageId=0)> <SerializableAttribute()> Public NotInheritable Class EasyUASubscribeDataSetArguments Inherits UASubscribeDataSetArguments Implements LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, OpcLabs.BaseLib.OperationModel.ComTypes._OperationArguments, OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._EasyUASubscribeDataSetArguments, OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._UASubscribeDataSetArguments, System.ICloneable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable
'Usage
Dim instance As EasyUASubscribeDataSetArguments
[CLSCompliant(true)] [ComDefaultInterface(OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._EasyUASubscribeDataSetArguments)] [ComVisible(true)] [Guid("0DF356DA-30CF-48D1-AE01-9626CDBE4155")] [TypeConverter(System.ComponentModel.ExpandableObjectConverter)] [ValueControl("OpcLabs.BaseLib.Forms.Common.UniversalValueControl, OpcLabs.BaseLibForms, Version=5.80.82.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", Export=true, PageId=0)] [Serializable()] public sealed class EasyUASubscribeDataSetArguments : UASubscribeDataSetArguments, LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, OpcLabs.BaseLib.OperationModel.ComTypes._OperationArguments, OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._EasyUASubscribeDataSetArguments, OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._UASubscribeDataSetArguments, System.ICloneable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable
[CLSCompliant(true)] [ComDefaultInterface(OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._EasyUASubscribeDataSetArguments)] [ComVisible(true)] [Guid("0DF356DA-30CF-48D1-AE01-9626CDBE4155")] [TypeConverter(System.ComponentModel.ExpandableObjectConverter)] [ValueControl("OpcLabs.BaseLib.Forms.Common.UniversalValueControl, OpcLabs.BaseLibForms, Version=5.80.82.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", Export=true, PageId=0)] [Serializable()] public ref class EasyUASubscribeDataSetArguments sealed : public UASubscribeDataSetArguments, LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, OpcLabs.BaseLib.OperationModel.ComTypes._OperationArguments, OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._EasyUASubscribeDataSetArguments, OpcLabs.EasyOpc.UA.PubSub.OperationModel.ComTypes._UASubscribeDataSetArguments, System.ICloneable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable
If you are on Windows, you can also use the OPC UA PubSub Demo Application to experiment with various settings. This allows you to try out and determine the correct parameters before you put them into the code.
A subscription is initiated by calling the SubscribeDataSet Method on the EasyUASubscriber Class. In its basic form, the method takes a single argument which is an instance of the EasyUASubscribeDataSetArguments Class, and this argument contains all the information necessary to perform the subscription. The object and all the sub-objects it contains are rather complex.
The picture below is meant to give you at least a general overview about what this object contains. There are more "smaller" properties to the individual objects on the picture, but we do not care about them for now.
The main parts of the EasyUASubscribeDataSetArguments is the DataSetSubscriptionDescriptor: it describes the dataset(s) you want to subscribe to.
The ResolverDescriptor in the DataSetSubscriptionDescriptor is for OPC UA PubSub logical resolution, if used.
Inside the dataset subscription descriptor, you always need to specify the PubSub connection, using the ConnectionDescriptor Property. You will typically also need to fill in data in the Filter Property (see Message Filtering (OPC UA PubSub)), and sometimes provide the DataSetMetaData Property (see Dataset Metadata (OPC UA PubSub)). The CommunicationParameters Property is used to specify details about the communication, message receive timeout, and parameters specific to message or transport protocol mapping.
There are many (extension method) overloads of the SubscribeDataSet Method, with various combinations of arguments. These overloads allow you to bypass the construction of the whole EasyUASubscribeDataSetArguments hierarchy, and pass in simply the parts you need.
The example below subscribes to all dataset messages on an OPC-UA PubSub connection with UDP UADP mapping. The connection is specified by its physical parameters, using the scheme name "opc.udp" and the IP address of the multicast group to listen on.
The example specifies just the PubSub connection, and receives all PubSub messages it encounters. In .NET, it illustrates the use of a SubscribeDataSet Method overload that takes just the PubSub connection descriptor as an input.
The information you pass in to the SubscribeDataSet Method may either be used "as is", or it may be subject to OPC UA PubSub logical resolution first. As explained in OPC UA PubSub Descriptors, you can pass in the physical identifiers, the logical identifiers, or both. The OPC UA PubSub logical resolution mechanism will be invoked if the dataset subscription descriptor requires resolution (this term is explained in OPC UA PubSub Descriptors).
We can reformulate it so: If you have specified physical identifiers everywhere, they will be directly used, and no logical resolution will take place - even if there are logical identifies filled in as well. If, however, you have a PubSub object somewhere in the descriptors that is only specified by its logical identifier but no physical identifier, the logical resolution mechanism will be used.
There are two ways your program can be informed about dataset messages that you have subscribed to:
It is also possible to specify a non-null callback parameter, and hook an event handler as well. In this case, the callback method will be invoked in addition to the event handlers.
The event arguments of the DataSetMessage Event are of type EasyUADataSetMessageEventArgs. Because it is indirectly derived from the OperationEventArgs, it contains the Exception Property which is null for success notifications, and non-null in case of failure. You can use the Succeeded Property to make the corresponding test. The actual data of the dataset, if available, is in the DataSetData Property.
The EasyUADataSetMessageEventArgs also contain, in their Arguments Property, a copy of the arguments (EasyUASubscribeDataSetArguments Class) you have used when making the dataset subscription that caused this event or callback. You can use this property to identify the dataset subscription, in case you are using event handlers and have made more subscriptions on the same object, or if you have used the same callback methods with multiple subscriptions. Specifically, the State Property in the EasyUASubscribeDataSetArguments can be used for any information you need to pass from the code that makes the subscription to the code that handles the dataset messages.
The EasyUASubscriber invokes the DataSetMessage event or callback when a new dataset message (you have subscribed to) arrives, but also in some other cases. Below is a list of possible property value combinations and their meaning.
The main causes for failures are
If the OPC UA PubSub logical resolution took place, the ResolvedDataSetSubscriptionDescriptor Property is filled in with a dataset subscription descriptor that is derived from the one you have specified when calling the SubscribeDataSet Method, but with the logical identifiers resolved to physical ones.
The dataset message event notification has a PubSubLocators Property. This property is always non-null (even in case of errors), and contains the information that allows to relate the event to its "source" in the OPC UA PubSub model. The object (UAPubSubLocators Class) has properties for a publisher Id, writer group Id, writer group name, dataset writer Id, and dataset writer name. The component will fill in as many of these properties as possible, given the circumstances. Knowing such relation comes handy when the dataset subscription filter is not for a single dataset, but for multiple datasets. Note that all information contained in the PubSubLocators Property is also available inside the dataset data. The difference is that the PubSubLocators object is present even in cases when there is dataset data - such as in case of errors. The PubSubLocators thus allow to determine the "source" of the error programmatically.
A typical task when processing the dataset message is to extract one or more fields from the dataset and process them further. The field is identified by its name (or an index in its string form, such "#0", if field names are not available) in the FieldDataDictionary. The example below shows how it can be done.
If metadata is available, you can alternatively use the FieldDataDictionaryById Property, which also contains the data for each field of the dataset message, but keyed by a datasetfield Id (a GUID).
Depending how OPC UA PubSub is configured, the publisher might be always sending all fields of the dataset with every dataset message, or it may use a combination of key frames and delta frames. While the key frame dataset message includes values for all fields of the dataset, the delta frame only contains values of the fields that have changed since the previous dataset message.
Key frames and delta frames are a concept that exists purely to spare the network bandwidth. When you subscribe with QuickOPC, the delta frames are interpreted internally, and a full dataset is always shipped to you in the dataset message event or callback. This way, you do not have to put in any additional code to handle the distinction between key frames and delta frames.
It is not necessary to unsubscribe and subscribe again, if you want to change some parameters of existing subscription, such as its filter (Message Filtering (OPC UA PubSub)) or the associated metadata (Dataset Metadata (OPC UA PubSub)). You change the parameters by calling the ChangeDataSetSubscription Method, passing it the dataset subscription handle, and the new parameters in form of an instance of the EasyUADataSetSubscriptionChangeArguments Class.
There is also an extension method (an overload - with the same name) that allows you to easily pass in just the dataset subscription handle, and a new filter.
If you no longer want to receive dataset messages, you need to unsubscribe. This is achieved by calling the UnsubscribeDataSet Method, passing it the dataset subscription handle obtained when calling the SubscribeDataSet Method.
Example:
You can also unsubscribe from all dataset messages you have previously subscribed to (on the same instance of the EasyUASubscriber Class) by calling the UnsubscribeAllDataSets Method.
QuickOPC merges together requests to the same PubSub objects. If, for example, you make multiple dataset subscriptions and they all use the same PubSub connection, QuickOPC will only make the connection once.
This merging is performed among all subscriptions on all EasyUASubscriber objects that have their Isolated Property set to 'false' (the default). If you set the Isolated Property on some EasyUASubscriber object to 'true', the merging is then performed on the subscriptions made on that object only.
Newer versions of OPC UA specification allow the publishers to inform interested parties about their status, either cyclically, or when the status changes. OPC Studio recognizes and processes the publisher status messages in UADP and JSON message mappings. Any non-operational publisher status is reported as an error through the dataset subscription event handler or callback.
This functionality is commonly used with OPC UA PubSub Topic Tree, in which case the topic tree rules prescribe the name of the topic where the status messages for a particular publisher are located.
System.Object
OpcLabs.BaseLib.Object2
OpcLabs.BaseLib.Info
OpcLabs.BaseLib.OperationModel.OperationArguments
OpcLabs.EasyOpc.UA.PubSub.OperationModel.UASubscribeDataSetArguments
OpcLabs.EasyOpc.UA.PubSub.OperationModel.EasyUASubscribeDataSetArguments