In This Topic

QuickOPC manages connections (COM OPC Server object instances in OPC Classic, HTTP in OPC XML-DA, or UA sessions in OPC UA) from the client (your application) to the server automatically, That is, you do not have to do anything explicitly to open the connection, or to close it. QuickOPC opens the connection when it is needed, and it closes it when it is no longer in use for some time. It also keeps the connection open when it is needed to perform some long-running function (such as when you have subscriptions). QuickOPC also attempt to re-establish the connection if it gets broken by circumstances external to your application, such as network disruptions, or problems on the server side. All of this happens automatically and "behind the scenes".

In some cases, however, you may want a better control of the OPC client-server connections.

The features discussed here, or some of them, may not be available in all editions of the product. Check the Product Editions page for differences between the editions. The trial license has all features enabled (and is limited in period for which it provides valid data), but licenses for specific commercial editions may have functionality limitations.

Connection locking

You may want, for example, to assure that the connection stays open, in order to improve perfomance (because opening and closing the connection takes some time). Or, some (relatively rare) concepts work with data that are only valid for a lifetime of a particular connection, and therefore you need to assure that the connection is open during certain period. For example, in OPC UA, the file handle is "tied" to a UA session that created it.

Locking a connection assures that the component will attempt to keep the connection open. Unlocking the connection, however, does not always mean that the connection will be closed, because there may be other reasons to keep it open.

OPC UA Client-Server

In OPC UA, you can control the client-server connections using the IEasyUAClientConnectionControl service that you obtain from the EasyUAClient component.

The LockConnection Method on the IEasyUAClientConnectionControl Interface locks a connection to the specified endpoint descriptor. This means that the component will attempt to open the connection and keep it open, until it is explicitly unlocked. While the connection is locked, operations with the same endpoint descriptor will use the connection that is locked and already open. The method returns a lock handle (an integer) that can be later used to unlock the connection. It is not an error to lock the connection with the same endpoint descriptor multiple times; each of these will return its own, different lock handle. The component keeps an internal count of locks with the same endpoint descriptor, and the connection is effectively unlocked only if there are no existing locks with that endpoint descriptor. You eventually need to unlock each of the obtained lock handles (in any order).

The UnlockConnection Method on the IEasyUAClientConnectionControl Interface unlocks a connection that has previously been locked. You need to pass it a lock handle obtained previously from the LockConnection Method. If there are no other locks with the same endpoint descriptor, the connection will no longer be locked, and the component can close it (if not in conflict with other ruels - such as that the connection is kept open for any existing subscriptions). The lock handle you pass to the UnlockConnection Method becomes invalid and you can no longer use it.

Make sure your code always unlocks the connection it has previously locked.

// This example shows how to lock and unlock connections to an OPC UA server. The component attempts to keep the locked
// connections open, until unlocked.

using System;
using Microsoft.Extensions.DependencyInjection;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.OperationModel;
using OpcLabs.EasyOpc.UA.Services;

namespace UADocExamples._EasyUAClientConnectionControl
{
    class LockAndUnlockConnection
    {
        public static void Main1()
        {
            UAEndpointDescriptor endpointDescriptor =
                "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
            // or "http://opcua.demo-this.com:51211/UA/SampleServer" (currently not supported)
            // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

            // Instantiate the client object and hook events
            using (var client = new EasyUAClient())
            {
                // Obtain the client connection monitoring service.
                IEasyUAClientConnectionMonitoring clientConnectionMonitoring = client.GetService<IEasyUAClientConnectionMonitoring>();
                if (clientConnectionMonitoring is null)
                {
                    Console.WriteLine("The client connection monitoring service is not available.");
                    return;
                }

                // Obtain the client connection control service.
                IEasyUAClientConnectionControl clientConnectionControl = client.GetService<IEasyUAClientConnectionControl>();
                if (clientConnectionControl is null)
                {
                    Console.WriteLine("The client connection control service is not available.");
                    return;
                }

                // Display the server condition changed events.
                clientConnectionMonitoring.ServerConditionChanged += (sender, args) => Console.WriteLine(args);

                int lockHandle = 0;
                bool locked = false;
                try
                {
                    Console.WriteLine("Reading (1)");
                    // The first read will cause a connection to the server.
                    UAAttributeData attributeData1 =
                        client.Read(endpointDescriptor, "nsu=http://test.org/UA/Data/ ;i=10853");
                    Console.WriteLine(attributeData1);

                    Console.WriteLine("Waiting for 10 seconds...");
                    // Since the connection is now not used for some time, and it is not locked, it will be closed.
                    System.Threading.Thread.Sleep(10 * 1000);

                    Console.WriteLine("Locking");
                    // Locking the connection causes it to open, if possible.
                    lockHandle = clientConnectionControl.LockConnection(endpointDescriptor);
                    locked = true;

                    Console.WriteLine("Waiting for 10 seconds...");
                    // The connection is locked, it will not be closed now.
                    System.Threading.Thread.Sleep(10 * 1000);

                    Console.WriteLine("Reading (2)");
                    UAAttributeData attributeData2 =
                        client.Read(endpointDescriptor, "nsu=http://test.org/UA/Data/ ;i=10853");
                    Console.WriteLine(attributeData2);

                    Console.WriteLine("Waiting for 10 seconds...");
                    // The connection is still locked, it will not be closed now.
                    System.Threading.Thread.Sleep(10 * 1000);
                }
                catch (UAException uaException)
                {
                    Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                }
                finally
                {
                    if (locked)
                    {
                        Console.WriteLine("Unlocking");
                        clientConnectionControl.UnlockConnection(lockHandle);
                    }
                }

                Console.WriteLine("Waiting for 10 seconds...");
                // After some delay, the connection will be closed, because there are no subscriptions to the server and no
                // connection locks.
                System.Threading.Thread.Sleep(10 * 1000);

                Console.WriteLine("Finished.");
            }
        }


        // Example output:
        //
        //Reading (1)
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connecting; Success; Attempt #1
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connected; Success
        //-1.034588E+18 {Single} @2021-11-15T15:26:39.169 @@2021-11-15T15:26:39.169; Good
        //Waiting for 10 seconds...
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnecting; Success
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnected(RetrialDelay=Infinite); Success
        //Locking
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connecting; Success; Attempt #1
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connected; Success
        //Waiting for 10 seconds...
        //Reading (2)
        //2.288872E+21 {Single} @2021-11-15T15:26:59.836 @@2021-11-15T15:26:59.836; Good
        //Waiting for 10 seconds...
        //Unlocking
        //Waiting for 10 seconds...
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnecting; Success
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnected(RetrialDelay=Infinite); Success
        //Finished.
    }
}

# This example shows how to lock and unlock connections to an OPC UA server. The component attempts to keep the locked
# connections open, until unlocked.
import time

# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc

# Import .NET namespaces.
from Microsoft.Extensions.DependencyInjection import *
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.OperationModel import *
from OpcLabs.EasyOpc.UA.Services import *


endpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:51210/UA/SampleServer')
# or 'http://opcua.demo-this.com:51211/UA/SampleServer' (currently not supported)
# or 'https://opcua.demo-this.com:51212/UA/SampleServer/'

# Instantiate the client object and hook events.
client = None
try:
    client = EasyUAClient()

    # Obtain the client connection monitoring service.
    clientConnectionMonitoring = ServiceProviderServiceExtensions.GetService[IEasyUAClientConnectionMonitoring](client)
    if clientConnectionMonitoring is None:
        print('The client connection monitoring service is not available.')
        exit()

    # Obtain the client connection control service.
    clientConnectionControl = ServiceProviderServiceExtensions.GetService[IEasyUAClientConnectionControl](client)
    if clientConnectionControl is None:
        print('The client connection control service is not available.')
        exit()

    # Display the server condition changed events.
    clientConnectionMonitoring.ServerConditionChanged += lambda sender, args: print(args)

    lockHandle = 0
    locked = False
    try:
        print('Reading (1)')
        # The first read will cause a connection to the server.
        attributeData1 = IEasyUAClientExtension.Read(client,
                                                     endpointDescriptor,
                                                     UANodeDescriptor('nsu=http://test.org/UA/Data/ ;i=10853'))
        print(attributeData1)

        print('Waiting for 10 seconds...')
        # Since the connection is now not used for some time, and it is not locked, it will be closed.
        time.sleep(10)

        print('Locking')
        # Locking the connection causes it to open, if possible.
        lockHandle = clientConnectionControl.LockConnection(endpointDescriptor)
        locked = True

        print('Waiting for 10 seconds...')
        # The connection is locked, it will not be closed now.
        time.sleep(10)

        print('Reading (2)')
        attributeData2 = IEasyUAClientExtension.Read(client,
                                                     endpointDescriptor,
                                                     UANodeDescriptor('nsu=http://test.org/UA/Data/ ;i=10853'))
        print(attributeData2)

        print('Waiting for 10 seconds...')
        # The connection is still locked, it will not be closed now.
        time.sleep(10)

    except UAException as uaException:
        print('*** Failure: ' + uaException.GetBaseException().Message)

    finally:
        if locked:
            print('Unlocking')
            clientConnectionControl.UnlockConnection(lockHandle)

    print('Waiting for 10 seconds...')
    # After some delay, the connection will be closed, because there are no subscriptions to the server and no
    # connection locks.
    time.sleep(10)

    print('Finished.')

finally:
    client and client.Dispose()

COM

VBScript

Rem This example shows how to lock and unlock connections to an OPC UA server. The component attempts to keep the locked
Rem connections open, until unlocked.

Option Explicit

Dim endpointDescriptorUrlString: endpointDescriptorUrlString = "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer"
Dim EndpointDescriptor: Set EndpointDescriptor = CreateObject("OpcLabs.EasyOpc.UA.UAEndpointDescriptor")
EndpointDescriptor.UrlString = endpointDescriptorUrlString

' Instantiate the client object.
Dim Client: Set Client = CreateObject("OpcLabs.EasyOpc.UA.EasyUAClient")

' Obtain the client connection monitoring service.
Dim ClientConnectionMonitoring: Set ClientConnectionMonitoring = Client.GetServiceByName("OpcLabs.EasyOpc.UA.Services.IEasyUAClientConnectionMonitoring, OpcLabs.EasyOpcUA")
If ClientConnectionMonitoring Is Nothing Then
    WScript.Echo "The client connection monitoring service is not available."
    WScript.Quit
End If

' Obtain the client connection control service.
Dim ClientConnectionControl: Set ClientConnectionControl = Client.GetServiceByName("OpcLabs.EasyOpc.UA.Services.IEasyUAClientConnectionControl, OpcLabs.EasyOpcUA")
If ClientConnectionControl Is Nothing Then
    WScript.Echo "The client connection control service is not available."
    WScript.Quit
End If

' Display the server condition changed events.
WScript.ConnectObject ClientConnectionMonitoring, "ClientConnectionMonitoring_"

WScript.Echo "Reading (1)"
' The first read will cause a connection to the server.
Dim AttributeData1: Set AttributeData1 = Client.Read(endpointDescriptorUrlString, "nsu=http://test.org/UA/Data/ ;i=10853")
WScript.Echo AttributeData1

WScript.Echo "Waiting for 10 seconds..."
' Since the connection is now not used for some time, and it is not locked, it will be closed.
WScript.Sleep 10*1000

WScript.Echo "Locking..."
' Locking the connection causes it to open, if possible.
Dim lockHandle: lockHandle = ClientConnectionControl.LockConnection(EndpointDescriptor)

WScript.Echo "Waiting for 10 seconds..."
' The connection is locked, it will not be closed now.
WScript.Sleep 10*1000

WScript.Echo "Reading (2)"
' The second read, because it closely follows the first one, will reuse the connection that is already open.
Dim AttributeData2: Set AttributeData2 = Client.Read(endpointDescriptorUrlString, "nsu=http://test.org/UA/Data/ ;i=10853")
WScript.Echo AttributeData2

WScript.Echo "Waiting for 10 seconds..."
' The connection is still locked, it will not be closed now.
WScript.Sleep 10*1000

WScript.Echo "Unlocking..."
ClientConnectionControl.UnlockConnection(lockHandle)

WScript.Echo "Waiting for 10 seconds..."
' After some delay, the connection will be closed, because there are no subscriptions to the server and no
' connection locks.
WScript.Sleep 10*1000

WScript.Echo "Finished."



Sub ClientConnectionMonitoring_ServerConditionChanged(Sender, e)
    WScript.Echo e
End Sub


' Example output:
'
'Reading (1)
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connecting; Success; Attempt #1
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connected; Success
'-1.034588E+18 {Single} @2021-11-15T15:26:39.169 @@2021-11-15T15:26:39.169; Good
'Waiting for 10 seconds...
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnecting; Success
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnected(RetrialDelay=Infinite); Success
'Locking
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connecting; Success; Attempt #1
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connected; Success
'Waiting for 10 seconds...
'Reading (2)
'2.288872E+21 {Single} @2021-11-15T15:26:59.836 @@2021-11-15T15:26:59.836; Good
'Waiting for 10 seconds...
'Unlocking
'Waiting for 10 seconds...
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnecting; Success
'"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnected(RetrialDelay=Infinite); Success
'Finished.

The methods that lock or unlock the connection work asynchronously, i.e. opening or closing the connection may happen after the control has returned from the method back to your code.

The methods do not throw exceptions or return any error indication in case of failure related to locking and unlocking. If you need the information related to such errors situations, you can use the Operation Monitoring Services.

In .NET, it is possible to further simplify the connection locking and unlocking code, by using an extension DisposableLockConnection Method. This method locks a connection in the same way as the LockConnection Method does, but instead of returning an integer lock handle that you will later use with the UnlockConnection Method, it returns an IDisposable object, implemented in such a way that disposing of it (using its Dispose Method) unlocks the connection. The underlying functionality is identical, but the disposable lock object plays nicely with language constructs available in most .NET languages, such as the using statement in C# or the Using Statement in VB.NET. Not only allow these language construct for shorter and clearer code, but they also guarantee that the object will be disposed (and therefore the connection unlocked) not only when the control flows normally through the body of the statement block, but also in cases when an exception is thrown and the control leaves the block via the exception. This reduces or eliminates the potential for nasty coding errors which can otherwise leave the connections locked when they should not be.

// This example shows how to obtain lock the OPC UA connection and obtain a disposable object which unlocks the connection
// when it is disposed.

using System;
using Microsoft.Extensions.DependencyInjection;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.OperationModel;
using OpcLabs.EasyOpc.UA.Services;
using OpcLabs.EasyOpc.UA.Services.Extensions;

namespace UADocExamples._EasyUAClientConnectionControl
{
    class DisposableLockConnection
    {
        public static void Main1()
        {
            UAEndpointDescriptor endpointDescriptor =
                "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
            // or "http://opcua.demo-this.com:51211/UA/SampleServer" (currently not supported)
            // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

            // Instantiate the client object and hook events
            using (var client = new EasyUAClient())
            {
                // Obtain the client connection monitoring service.
                IEasyUAClientConnectionMonitoring clientConnectionMonitoring = client.GetService<IEasyUAClientConnectionMonitoring>();
                if (clientConnectionMonitoring is null)
                {
                    Console.WriteLine("The client connection monitoring service is not available.");
                    return;
                }

                // Obtain the client connection control service.
                IEasyUAClientConnectionControl clientConnectionControl = client.GetService<IEasyUAClientConnectionControl>();
                if (clientConnectionControl is null)
                {
                    Console.WriteLine("The client connection control service is not available.");
                    return;
                }

                // Display the server condition changed events.
                clientConnectionMonitoring.ServerConditionChanged += (sender, args) => Console.WriteLine(args);

                try
                {
                    Console.WriteLine("Reading (1)");
                    // The first read will cause a connection to the server.
                    UAAttributeData attributeData1 =
                        client.Read(endpointDescriptor, "nsu=http://test.org/UA/Data/ ;i=10853");
                    Console.WriteLine(attributeData1);

                    Console.WriteLine("Waiting for 10 seconds...");
                    // Since the connection is now not used for some time, and it is not locked, it will be closed.
                    System.Threading.Thread.Sleep(10 * 1000);

                    Console.WriteLine("Locking");
                    // Locking the connection causes it to open, if possible.
                    using (clientConnectionControl.DisposableLockConnection(endpointDescriptor))
                    {
                        Console.WriteLine("Waiting for 10 seconds...");
                        // The connection is locked, it will not be closed now.
                        System.Threading.Thread.Sleep(10 * 1000);

                        Console.WriteLine("Reading (2)");
                        UAAttributeData attributeData2 =
                            client.Read(endpointDescriptor, "nsu=http://test.org/UA/Data/ ;i=10853");
                        Console.WriteLine(attributeData2);

                        Console.WriteLine("Waiting for 10 seconds...");
                        // The connection is still locked, it will not be closed now.
                        System.Threading.Thread.Sleep(10 * 1000);

                        // Unlocking will occur now.
                    }
                    Console.WriteLine("Unlocked");
                }
                catch (UAException uaException)
                {
                    Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                }

                Console.WriteLine("Waiting for 10 seconds...");
                // After some delay, the connection will be closed, because there are no subscriptions to the server and no
                // connection locks.
                System.Threading.Thread.Sleep(10 * 1000);

                Console.WriteLine("Finished.");
            }
        }


        // Example output:
        //
        //Reading (1)
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connecting; Success; Attempt #1
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connected; Success
        //-1.034588E+18 {Single} @2021-11-15T15:26:39.169 @@2021-11-15T15:26:39.169; Good
        //Waiting for 10 seconds...
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnecting; Success
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnected(RetrialDelay=Infinite); Success
        //Locking
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connecting; Success; Attempt #1
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Connected; Success
        //Waiting for 10 seconds...
        //Reading (2)
        //2.288872E+21 {Single} @2021-11-15T15:26:59.836 @@2021-11-15T15:26:59.836; Good
        //Waiting for 10 seconds...
        //Unlocked
        //Waiting for 10 seconds...
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnecting; Success
        //"opc.tcp://opcua.demo-this.com:51210/UA/SampleServer" Disconnected(RetrialDelay=Infinite); Success
        //Finished.
    }
}

OPC Classic

A corresponding service is not currently available for OPC Classic.

Examples - OPC UA Services

Examples - OPC UA Services - Lock and unlock a connection

Examples - OPC UA Services - Disposable object for a connection lock

Reference

IEasyUAClientConnectionControl Interface