OPC Studio User's Guide and Reference
SubscribeDataSetField(IEasyUASubscriber,UAPubSubResolverDescriptor,UAPubSubConnectionDescriptor,UASubscribeDataSetFilter,UADataSetFieldDescriptor,EasyUADataSetFieldMessageEventHandler) Method
Example 



OpcLabs.EasyOpcUA Assembly > OpcLabs.EasyOpc.UA.PubSub Namespace > IEasyUASubscriberExtension Class > SubscribeDataSetField Method : SubscribeDataSetField(IEasyUASubscriber,UAPubSubResolverDescriptor,UAPubSubConnectionDescriptor,UASubscribeDataSetFilter,UADataSetFieldDescriptor,EasyUADataSetFieldMessageEventHandler) Method
The subscriber object that will perform the operation.

This is typically the EasyUASubscriber object.

The value of this parameter cannot be null (Nothing in Visual Basic).

Describes how the PubSub logical information should be resolved to physical.

The value of this parameter cannot be null (Nothing in Visual Basic).

The PubSub connection descriptor.

Because the UAPubSubConnectionDescriptor has an implicit conversion from OpcLabs.BaseLib.Networking.ResourceAddress and System.String, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a OpcLabs.BaseLib.Networking.ResourceAddress object, or a string (the so-called resource description string, usually a resource URL) in place of this parameter, and the corresponding OPC UA PubSub connection descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the UAPubSubConnectionDescriptor.FromResourceAddress or UAWriterGroupDescriptor.FromString static method instead.

Also, because the OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement has an implicit conversion to UAPubSubConnectionDescriptor, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement (from PubSub configuration) in place of this parameter, and the corresponding OPC UA PubSub connection descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can convert a OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement to UAPubSubConnectionDescriptor using the OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement.ToUAPubSubConnectionDescriptor static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

Specifies how the incoming PubSub messages should be filtered before being delivered to the application.

Because the UASubscribeDataSetFilter has an implicit conversion from UAPublisherId, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a UAPublisherId (containing the publisher Id that you want to allow in the filter) in place of this parameter, and the corresponding OPC UA subscribe dataset filter will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the UASubscribeDataSetFilter.FromUAPublisherId static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

The descriptor for the dataset field.

Because the UADataSetFieldDescriptor has implicit conversions from System.Guid and System.String, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a GUID (representing the dataset field Id), or a string (representing the name of the dataset field) in place of this parameter, and the corresponding OPC UA dataset field descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the UADataSetFieldDescriptor.FromGuid or UADataSetFieldDescriptor.FromString static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

A callback method to be invoked for each time a dataset field is received.

The value of this parameter cannot be null (Nothing in Visual Basic).

Subscribes to a single dataset field from a logical dataset, using a PubSub resolver descriptor, PubSub connection descriptor, specified filter, a field name, and a callback.
Syntax
'Usage
 
Dim subscriber As IEasyUASubscriber
Dim pubSubResolverDescriptor As UAPubSubResolverDescriptor
Dim pubSubConnectionDescriptor As UAPubSubConnectionDescriptor
Dim subscribeDataSetFilter As UASubscribeDataSetFilter
Dim dataSetFieldDescriptor As UADataSetFieldDescriptor
Dim callback As EasyUADataSetFieldMessageEventHandler
Dim value As Integer
 
value = IEasyUASubscriberExtension.SubscribeDataSetField(subscriber, pubSubResolverDescriptor, pubSubConnectionDescriptor, subscribeDataSetFilter, dataSetFieldDescriptor, callback)

Parameters

subscriber
The subscriber object that will perform the operation.

This is typically the EasyUASubscriber object.

The value of this parameter cannot be null (Nothing in Visual Basic).

pubSubResolverDescriptor
Describes how the PubSub logical information should be resolved to physical.

The value of this parameter cannot be null (Nothing in Visual Basic).

pubSubConnectionDescriptor
The PubSub connection descriptor.

Because the UAPubSubConnectionDescriptor has an implicit conversion from OpcLabs.BaseLib.Networking.ResourceAddress and System.String, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a OpcLabs.BaseLib.Networking.ResourceAddress object, or a string (the so-called resource description string, usually a resource URL) in place of this parameter, and the corresponding OPC UA PubSub connection descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the UAPubSubConnectionDescriptor.FromResourceAddress or UAWriterGroupDescriptor.FromString static method instead.

Also, because the OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement has an implicit conversion to UAPubSubConnectionDescriptor, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement (from PubSub configuration) in place of this parameter, and the corresponding OPC UA PubSub connection descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can convert a OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement to UAPubSubConnectionDescriptor using the OpcLabs.EasyOpc.UA.PubSub.Configuration.UAPubSubConnectionElement.ToUAPubSubConnectionDescriptor static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

subscribeDataSetFilter
Specifies how the incoming PubSub messages should be filtered before being delivered to the application.

Because the UASubscribeDataSetFilter has an implicit conversion from UAPublisherId, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a UAPublisherId (containing the publisher Id that you want to allow in the filter) in place of this parameter, and the corresponding OPC UA subscribe dataset filter will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the UASubscribeDataSetFilter.FromUAPublisherId static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

dataSetFieldDescriptor
The descriptor for the dataset field.

Because the UADataSetFieldDescriptor has implicit conversions from System.Guid and System.String, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a GUID (representing the dataset field Id), or a string (representing the name of the dataset field) in place of this parameter, and the corresponding OPC UA dataset field descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the UADataSetFieldDescriptor.FromGuid or UADataSetFieldDescriptor.FromString static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

callback
A callback method to be invoked for each time a dataset field is received.

The value of this parameter cannot be null (Nothing in Visual Basic).

Return Value

Returns a dataset field subscription handle that can be used to change the subscription, obtain its arguments, or unsubscribe.
Exceptions
ExceptionDescription

A null reference (Nothing in Visual Basic) is passed to a method that does not accept it as a valid argument.

This is a usage error, i.e. it will never occur (the exception will not be thrown) in a correctly written program. Your code should not catch this exception.

Remarks

There is no corresponding method in COM.

This is an extension method (info: C#, VB.NET). In languages that have support for extensions methods (such as C# and VB.NET), you can use the extension method as if it were a regular method on the object that is its first parameter. In other languages (such as with Python.NET), you will call the extension as a static method, and pass it the object on which it acts as its first parameter.

Example
// This example shows how to subscribe to a single dataset field, resolving logical parameters to physical from an OPC-UA
// PubSub configuration file in binary format. The metadata obtained through the resolution is used to decode fixed layout
// messages with RawData field encoding.
//
// In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
// https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-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 System.Threading;
using OpcLabs.EasyOpc.UA.PubSub;

namespace UASubscriberDocExamples.PubSub._EasyUASubscriber
{
    class SubscribeDataSetField
    {
        public static void Main1()
        {
            // Define the PubSub resolver. We want the information be resolved from a PubSub binary configuration file that
            // we have. The file itself at the root of the project, and we have specified that it has to be copied to the
            // project's output directory.
            var pubSubResolverDescriptor = UAPubSubResolverDescriptor.File("UADemoPublisher-Default.uabinary");

            // Define the PubSub connection we will work with, using its logical name in the PubSub configuration.
            var pubSubConnectionDescriptor = new UAPubSubConnectionDescriptor { Name = "FixedLayoutConnection" };
            // In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
            // the statement below. Your actual interface name may differ, of course.
            //pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet";

            // Define the filter. The writer group and the dataset writer are specified using their logical names in the
            // PubSub configuration. The publisher Id in the filter will be taken from the logical PubSub connection.
            var filter = new UASubscribeDataSetFilter("FixedLayoutGroup", "SimpleWriter");

            // Instantiate the subscriber object.
            var subscriber = new EasyUASubscriber();

            Console.WriteLine("Subscribing...");
            int fieldHandle = subscriber.SubscribeDataSetField(
                pubSubResolverDescriptor, 
                pubSubConnectionDescriptor,
                filter,
                "Int32Fast",
                (sender, args) => { Console.WriteLine(args); });

            Console.WriteLine("Processing dataset message events for 20 seconds...");
            Thread.Sleep(20 * 1000);

            Console.WriteLine("Unsubscribing...");
            subscriber.UnsubscribeDataSetField(fieldHandle);

            Console.WriteLine("Waiting for 1 second...");
            // Unsubscribe operation is asynchronous, messages may still come for a short while.
            Thread.Sleep(1 * 1000);

            Console.WriteLine("Finished.");
        }

        // Example output:
        //
        //Subscribing...
        //Processing dataset message events for 20 seconds...
        //Success
        //Success; 1626 {System.Int32}; Good
        //Success; 1711 {System.Int32}; Good
        //Success; 1741 {System.Int32}; Good
        //Success; 1837 {System.Int32}; Good
        //Success; 1897 {System.Int32}; Good
        //Success; 1993 {System.Int32}; Good
        //Success; 2082 {System.Int32}; Good
        //Success; 2135 {System.Int32}; Good
        //Success; 2185 {System.Int32}; Good
        //Success; 2241 {System.Int32}; Good
        //Success; 2324 {System.Int32}; Good
        //Success; 2368 {System.Int32}; Good
        //Success; 2423 {System.Int32}; Good
        //Success; 2445 {System.Int32}; Good
        //Success; 2497 {System.Int32}; Good
        //Success; 2584 {System.Int32}; Good
        //Success; 2608 {System.Int32}; Good
        //...
    }
}
' This example shows how to subscribe to a single dataset field, resolving logical parameters to physical from an OPC-UA
' PubSub configuration file in binary format. The metadata obtained through the resolution is used to decode fixed layout
' messages with RawData field encoding.
'
' In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
' https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' 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.EasyOpc.UA.PubSub

Namespace PubSub._EasyUASubscriber
    Friend Class SubscribeDataSetField
        Public Shared Sub Main1()

            ' Define the PubSub resolver. We want the information be resolved from a PubSub binary configuration file that
            ' we have. The file itself is at the root of the project, and we have specified that it has to be copied to the
            ' project's output directory.
            Dim pubSubResolverDescriptor = UAPubSubResolverDescriptor.File("UADemoPublisher-Default.uabinary")

            ' Define the PubSub connection we will work with, using its logical name in the PubSub configuration.
            Dim pubSubConnectionDescriptor = New UAPubSubConnectionDescriptor
            pubSubConnectionDescriptor.Name = "FixedLayoutConnection"
            ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
            ' the statement below. Your actual interface name may differ, of course.
            ' pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet"

            ' Define the filter. The writer group and the dataset writer are specified using their logical names in the
            ' PubSub configuration. The publisher Id in the filter will be taken from the logical PubSub connection.
            Dim filter = New UASubscribeDataSetFilter("FixedLayoutGroup", "SimpleWriter")

            ' Instantiate the subscriber object.
            Dim subscriber = New EasyUASubscriber()

            Console.WriteLine("Subscribing...")
            Dim fieldHandle = subscriber.SubscribeDataSetField(
                pubSubResolverDescriptor,
                pubSubConnectionDescriptor,
                filter,
                "Int32Fast",
                Sub(sender, eventArgs)
                    Console.WriteLine(eventArgs)
                End Sub)

            Console.WriteLine("Processing dataset message events for 20 seconds...")
            Threading.Thread.Sleep(20 * 1000)

            Console.WriteLine("Unsubscribing...")
            subscriber.UnsubscribeAllDataSets()

            Console.WriteLine("Waiting for 1 second...")
            ' Unsubscribe operation is asynchronous, messages may still come for a short while.
            Threading.Thread.Sleep(1 * 1000)

            Console.WriteLine("Finished...")
        End Sub
    End Class

    ' Example output
    '
    'Subscribing...
    'Processing dataset message events for 20 seconds...
    'Success
    'Success; 1626 {System.Int32}; Good
    'Success; 1711 {System.Int32}; Good
    'Success; 1741 {System.Int32}; Good
    'Success; 1837 {System.Int32}; Good
    'Success; 1897 {System.Int32}; Good
    'Success; 1993 {System.Int32}; Good
    'Success; 2082 {System.Int32}; Good
    'Success; 2135 {System.Int32}; Good
    'Success; 2185 {System.Int32}; Good
    'Success; 2241 {System.Int32}; Good
    'Success; 2324 {System.Int32}; Good
    'Success; 2368 {System.Int32}; Good
    'Success; 2423 {System.Int32}; Good
    'Success; 2445 {System.Int32}; Good
    'Success; 2497 {System.Int32}; Good
    'Success; 2584 {System.Int32}; Good
    'Success; 2608 {System.Int32}; Good
    '...

End Namespace
# This example shows how to subscribe to dataset messages on an OPC-UA PubSub connection, and then unsubscribe from that
# dataset.
#
# In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
# https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# 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.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc
import time

# Import .NET namespaces.
from OpcLabs.BaseLib import *
from OpcLabs.EasyOpc.UA.PubSub import *
from OpcLabs.EasyOpc.UA.PubSub.OperationModel import *


# Define the PubSub resolver. We want the information be resolved from a PubSub binary configuration file that
# we have. The file itself is in this script's directory.
pubSubResolverDescriptor = UAPubSubResolverDescriptor.File(ResourceDescriptor('UADemoPublisher-Default.uabinary'))

# Define the PubSub connection we will work with, using its logical name in the PubSub configuration.
pubSubConnectionDescriptor = UAPubSubConnectionDescriptor()
pubSubConnectionDescriptor.Name = 'FixedLayoutConnection'
# In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
# the statement below. Your actual interface name may differ, of course.
#pubSubConnectionDescriptor.ResourceAddress.InterfaceName = 'Ethernet'

# Define the filter. The writer group and the dataset writer are specified using their logical names in the
# PubSub configuration. The publisher Id in the filter will be taken from the logical PubSub connection.
filter = UASubscribeDataSetFilter(
    UAWriterGroupDescriptor('FixedLayoutGroup'),
    UADataSetWriterDescriptor('SimpleWriter'))

# Instantiate the subscriber object.
subscriber = EasyUASubscriber()

print('Subscribing...')
fieldHandle = IEasyUASubscriberExtension.SubscribeDataSetField(subscriber,
    pubSubResolverDescriptor,
    pubSubConnectionDescriptor,
    filter,
    UADataSetFieldDescriptor('Int32Fast'),
    EasyUADataSetFieldMessageEventHandler(lambda sender, args: print(args)))

print('Processing dataset message events for 20 seconds...')
time.sleep(20)

print('Unsubscribing...')
IEasyUASubscriberExtension.UnsubscribeDataSetField(subscriber, fieldHandle)

print('Waiting for 1 second...')
# Unsubscribe operation is asynchronous, messages may still come for a short while.
time.sleep(1)

print('Finished.')
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