QueryApplications Method (IEasyUAGlobalDiscoveryClient)

Finds client or server applications that meet the specified filters.

Syntax

Visual Basic
C#
C++/CLI

'Declaration
 
Sub QueryApplications( _
   ByVal gdsEndpointDescriptor As UAEndpointDescriptor, _
   ByVal startingRecordId As Long, _
   ByVal maximumRecordsToReturn As Long, _
   ByVal applicationName As String, _
   ByVal applicationUriString As String, _
   ByVal applicationTypes As UAApplicationTypes, _
   ByVal productUriString As String, _
   ByVal serverCapabilities As IEnumerable(Of String), _
   ByRef lastCounterResetTime As Date, _
   ByRef nextRecordId As Long, _
   ByRef applications() As UAApplicationDescription _
)

'Usage
 
Dim instance As IEasyUAGlobalDiscoveryClient
Dim gdsEndpointDescriptor As UAEndpointDescriptor
Dim startingRecordId As Long
Dim maximumRecordsToReturn As Long
Dim applicationName As String
Dim applicationUriString As String
Dim applicationTypes As UAApplicationTypes
Dim productUriString As String
Dim serverCapabilities As IEnumerable(Of String)
Dim lastCounterResetTime As Date
Dim nextRecordId As Long
Dim applications() As UAApplicationDescription
 
instance.QueryApplications(gdsEndpointDescriptor, startingRecordId, maximumRecordsToReturn, applicationName, applicationUriString, applicationTypes, productUriString, serverCapabilities, lastCounterResetTime, nextRecordId, applications)

void QueryApplications( 
   UAEndpointDescriptor gdsEndpointDescriptor,
   long startingRecordId,
   long maximumRecordsToReturn,
   string applicationName,
   string applicationUriString,
   UAApplicationTypes applicationTypes,
   string productUriString,
   IEnumerable<string> serverCapabilities,
   out DateTime lastCounterResetTime,
   out long nextRecordId,
   out UAApplicationDescription[] applications
)

void QueryApplications( 
   UAEndpointDescriptor^ gdsEndpointDescriptor,
   int64 startingRecordId,
   int64 maximumRecordsToReturn,
   String^ applicationName,
   String^ applicationUriString,
   UAApplicationTypes applicationTypes,
   String^ productUriString,
   IEnumerable<String^>^ serverCapabilities,
   [Out] DateTime lastCounterResetTime,
   [Out] int64 nextRecordId,
   [Out] array<UAApplicationDescription^>^ applications
)

Parameters

gdsEndpointDescriptor

Endpoint descriptor. Identifies the OPC-UA server. The server must be a Global Directory Server (GDS).

Because the OpcLabs.EasyOpc.UA.UAEndpointDescriptor has implicit conversions from System.String and System.Uri, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a string (representing the endpoint URL, or a so-called OPC UA endpoint descriptor string), or a System.Uri object, in place of this parameter, and the corresponding endpoint descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the OpcLabs.EasyOpc.UA.UAEndpointDescriptor.FromString or OpcLabs.EasyOpc.UA.UAEndpointDescriptor.FromUri static method instead.

Also, because the OpcLabs.EasyOpc.UA.Discovery.UAApplicationElement and OpcLabs.EasyOpc.UA.Discovery.UADiscoveryElement have an implicit conversion to OpcLabs.EasyOpc.UA.UAEndpointDescriptor, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a OpcLabs.EasyOpc.UA.Discovery.UAApplicationElement or OpcLabs.EasyOpc.UA.Discovery.UADiscoveryElement (results from OPC UA discovery) in place of this parameter, and the corresponding endpoint descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can convert a (non-null) OpcLabs.EasyOpc.UA.Discovery.UAApplicationElement or OpcLabs.EasyOpc.UA.Discovery.UADiscoveryElement to OpcLabs.EasyOpc.UA.UAEndpointDescriptor using the ToUAEndpointDescriptor or ToUAEndpointDescriptor method instead.

If you are using OPC Wizard (for server development), an implicit conversion from OpcLabs.EasyOpc.UA.EasyUAServerCore can be used in the same way to simply pass the server object in place of this parameter, which will use its OpcLabs.EasyOpc.UA.EasyUAServerCore.EffectiveServerDescriptor property for the connection.

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

startingRecordId

Only records with an identifier greater than this number will be returned. Specify 0 to start with the first record in the database.

maximumRecordsToReturn

The maximum number of records to return in the response.
0 indicates that there is no limit.

applicationName

The ApplicationName of the applications to return.
Supports the syntax used by the LIKE FilterOperator described in Part 4.
Not used if an empty string is specified. The filter is only applied to the default ApplicationName.

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

applicationUriString

The ApplicationUri of the applications to return.
Supports the syntax used by the LIKE FilterOperator described in Part 4.
Not used if an empty string is specified.

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

applicationTypes

A mask indicating what types of applications are returned.
If the mask is OpcLabs.EasyOpc.UA.Discovery.UAApplicationTypes.None then all applications are returned.

productUriString

The ProductUri of the applications to return.
Supports the syntax used by the LIKE FilterOperator described in Part 4.
Not used if an empty string is specified.

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

serverCapabilities

The capabilities supported by the applications returned.
The applications returned shall support all the capabilities specified.
If no capabilities are provided this filter is not used.

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

The individual elements of the parameter value cannot be null (Nothing in Visual Basic).

lastCounterResetTime

The last time the counters were reset.

nextRecordId

The identifier of the next record. It is passed as the startingRecordId in subsequent calls to QueryApplications to fetch the next batch of records. It is 0 if there are no more records to return.

applications

A list of Applications (OpcLabs.EasyOpc.UA.Discovery.UAApplicationDescription) which meet the criteria.

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

The individual elements of the parameter value cannot be null (Nothing in Visual Basic).

Exceptions

Exception Description

Exception	Description
System.ArgumentNullException	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.
OpcLabs.EasyOpc.UA.OperationModel.UAException	The OPC UA operation has failed. This operation exception in uniformly used to allow common handling of various kinds of errors. The System.Exception.InnerException always contains information about the actual error cause. This is an operation error that depends on factors external to your program, and thus cannot be always avoided. Your code must handle it appropriately.

System.ArgumentNullException

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.

OpcLabs.EasyOpc.UA.OperationModel.UAException

The OPC UA operation has failed. This operation exception in uniformly used to allow common handling of various kinds of errors. The System.Exception.InnerException always contains information about the actual error cause.

This is an operation error that depends on factors external to your program, and thus cannot be always avoided. Your code must handle it appropriately.

Remarks

There are higher-level methods that are easier to use and can be used instead. Have a look e.g. at:

OpcLabs.EasyOpc.UA.IEasyUAClientExtension.DiscoverGlobalApplications and its overloads,
OpcLabs.EasyOpc.UA.IEasyUAClientExtension.DiscoverGlobalServers and its overloads.
OpcLabs.EasyOpc.UA.IEasyUAClient.Discover and OpcLabs.EasyOpc.UA.Discovery.UAGlobalApplicationDiscoveryQuery.

Example

CSharp
VB.NET
Object Pascal
Visual Basic (VB 6.0)
Python

// Shows how to find client or server applications that meet the specified filters, using the global discovery client.
//
// 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 OpcLabs.EasyOpc.UA.Discovery;
using OpcLabs.EasyOpc.UA.Gds;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Gds._EasyUAGlobalDiscoveryClient
{
    class QueryApplications
    {
        public static void Main1()
        {
            // Instantiate the global discovery client object
            var globalDiscoveryClient = new EasyUAGlobalDiscoveryClient();

            // Find all (client or server) applications registered in the GDS.
            UAApplicationDescription[] applicationDescriptionArray;
            try
            {
                globalDiscoveryClient.QueryApplications(
                    gdsEndpointDescriptor:"opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer",
                    startingRecordId:0,
                    maximumRecordsToReturn:0,
                    applicationName:"",
                    applicationUriString:"",
                    applicationTypes:UAApplicationTypes.All,
                    productUriString:"",
                    serverCapabilities:new string[0],
                    lastCounterResetTime:out _,
                    nextRecordId: out _,
                    applications: out applicationDescriptionArray);
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }

            // Display results
            foreach (UAApplicationDescription applicationDescription in applicationDescriptionArray)
            {
                Console.WriteLine();
                Console.WriteLine("Application name: {0}", applicationDescription.ApplicationName);
                Console.WriteLine("Application type: {0}", applicationDescription.ApplicationType);
                Console.WriteLine("Application URI string: {0}", applicationDescription.ApplicationUriString);
                Console.WriteLine("Discovery URI strings: {0}", applicationDescription.DiscoveryUriStrings);
            }
        }
    }
}

' Shows how to find client or server applications that meet the specified filters, using the global discovery client.
'
' 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.Discovery
Imports OpcLabs.EasyOpc.UA.Gds
Imports OpcLabs.EasyOpc.UA.OperationModel

Namespace Gds._EasyUAGlobalDiscoveryClient
    Friend Class QueryApplications
        Public Shared Sub Main1()

            ' Instantiate the global discovery client object
            Dim globalDiscoveryClient = New EasyUAGlobalDiscoveryClient()

            ' Find all (client or server) applications registered in the GDS.
            Dim applicationDescriptionArray() As UAApplicationDescription = Nothing
            Try
                Dim lastCounterResetTime As DateTime
                Dim nextRecordId As Long
                globalDiscoveryClient.QueryApplications(
                    gdsEndpointDescriptor:="opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer",
                    startingRecordId:=0,
                    maximumRecordsToReturn:=0,
                    applicationName:="",
                    applicationUriString:="",
                    applicationTypes:=UAApplicationTypes.All,
                    productUriString:="",
                    serverCapabilities:=New String() {},
                    lastCounterResetTime:=lastCounterResetTime,
                    nextRecordId:=nextRecordId,
                    applications:=applicationDescriptionArray)
            Catch uaException As UAException
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException.Message)
                Exit Sub
            End Try

            ' Display results
            For Each applicationDescription As UAApplicationDescription In applicationDescriptionArray
                Console.WriteLine()
                Console.WriteLine("Application name: {0}", applicationDescription.ApplicationName)
                Console.WriteLine("Application type: {0}", applicationDescription.ApplicationType)
                Console.WriteLine("Application URI string: {0}", applicationDescription.ApplicationUriString)
                Console.WriteLine("Discovery URI strings: {0}", applicationDescription.DiscoveryUriStrings)
            Next applicationDescription
        End Sub
    End Class
End Namespace

// Shows how to find client or server applications that meet the specified filters, using the global discovery client.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in Object Pascal (Delphi) on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-OP .
// 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.

class procedure QueryApplications.Main;
var
  ApplicationDescription: _UAApplicationDescription;
  ApplicationDescriptionArray: OleVariant;
  ApplicationName: WideString;
  ApplicationUriString: WideString;
  GlobalDiscoveryClient: OpcLabs_EasyOpcUA_TLB._EasyUAGlobalDiscoveryClient;
  GdsEndpointDescriptor: _UAEndpointDescriptor;
  I: integer;
  LastCounterResetTime: TDateTime;
  MaximumRecordsToReturn: Integer;
  NextRecordId: Integer;
  ProductUriString: WideString;
  ServerCapabilities: array of string;
  StartingRecordId: Integer;
begin
  // Define which GDS we will work with.
  GdsEndpointDescriptor := CoUAEndpointDescriptor.Create;
  GdsEndpointDescriptor.UrlString := 'opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer';

  // Instantiate the global discovery client object
  GlobalDiscoveryClient := CoEasyUAGlobalDiscoveryClient.Create;

  // Find all (client or server) applications registered in the GDS.
  StartingRecordId := 0;
  MaximumRecordsToReturn := 0;
  ApplicationName := '';
  ApplicationUriString := '';
  ProductUriString := '';
  try
    GlobalDiscoveryClient.QueryApplications(
      GdsEndpointDescriptor,
      StartingRecordId,
      MaximumRecordsToReturn,
      ApplicationName,
      ApplicationUriString,
      UAApplicationTypes_All,
      ProductUriString,
      ServerCapabilities,
      LastCounterResetTime,
      NextRecordId,
      ApplicationDescriptionArray);
  except
    on E: EOleException do
    begin
      WriteLn(Format('*** Failure: %s', [E.GetBaseException.Message]));
    end;
  end;

  // Display results
  for I := VarArrayLowBound(ApplicationDescriptionArray,1) to VarArrayHighBound(ApplicationDescriptionArray,1) do
  begin
    ApplicationDescription := IUnknown(ApplicationDescriptionArray[I]) as _UAApplicationDescription;
    WriteLn;
    WriteLn('Application name: ', ApplicationDescription.ApplicationName);
    WriteLn('Application type: ', ApplicationDescription.ApplicationType);
    WriteLn('Application URI string: ', ApplicationDescription.ApplicationUriString);
    WriteLn('Discovery URI strings: ', ApplicationDescription.DiscoveryUriStrings.ToString);
  end;

end;

REM Shows how to find client or server applications that meet the specified filters, using the global discovery client.
REM
REM Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
REM OPC client and subscriber examples in Visual Basic on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VB .
REM Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
REM a commercial license in order to use Online Forums, and we reply to every post.

Private Sub EasyUAGlobalDiscoveryClient_QueryApplications_Main_Command_Click()
    OutputText = ""
    
    ' Define which GDS we will work with.
    Dim gdsEndpointDescriptor As New UAEndpointDescriptor
    gdsEndpointDescriptor.UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer"
    
    ' Instantiate the global discovery client object
    Dim globalDiscoveryClient As New EasyUAGlobalDiscoveryClient
    
    ' Find all (client or server) applications registered in the GDS.
    Dim startingRecordId As Long: startingRecordId = 0
    Dim maximumRecordsToReturn As Long: maximumRecordsToReturn = 0
    Dim applicationName As String: applicationName = ""
    Dim applicationUriString As String: applicationUriString = ""
    Dim productUriString As String: productUriString = ""
    Dim serverCapabilities: serverCapabilities = Array()
    Dim lastCounterResetTime As Date
    Dim nextRecordId As Long
    Dim applicationDescriptionArray As Variant
    On Error Resume Next
    Dim applicationId As UANodeId
    Call globalDiscoveryClient.QueryApplications( _
      gdsEndpointDescriptor, _
      startingRecordId, _
      maximumRecordsToReturn, _
      applicationName, _
      applicationUriString, _
      UAApplicationTypes_All, _
      productUriString, _
      serverCapabilities, _
      lastCounterResetTime, _
      nextRecordId, _
      applicationDescriptionArray)
    If Err.Number <> 0 Then
        OutputText = OutputText & "*** Failure: " & Err.Source & ": " & Err.Description & vbCrLf
        Exit Sub
    End If
    On Error GoTo 0
    
    ' Display results
    Dim i: For i = LBound(applicationDescriptionArray) To UBound(applicationDescriptionArray)
        Dim applicationDescription As UAApplicationDescription
        Set applicationDescription = applicationDescriptionArray(i)
        OutputText = OutputText & vbCrLf
        OutputText = OutputText & "Application name: " & applicationDescription.applicationName & vbCrLf
        OutputText = OutputText & "Application type: " & applicationDescription.ApplicationType & vbCrLf
        OutputText = OutputText & "Application URI string: " & applicationDescription.applicationUriString & vbCrLf
        OutputText = OutputText & "Discovery URI strings: " & applicationDescription.DiscoveryUriStrings.ToString & vbCrLf
    Next
End Sub

# Shows how to find all registrations in the GDS.
#
# 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 .NET namespaces.
from System import *
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.Discovery import *
from OpcLabs.EasyOpc.UA.Gds import *
from OpcLabs.EasyOpc.UA.OperationModel import *


# Define which GDS we will work with.
gdsEndpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer')

# Instantiate the global discovery client object.
globalDiscoveryClient = EasyUAGlobalDiscoveryClient()

# Find all (client or server) applications registered in the GDS.
try:
    _, _, _, applicationDescriptionArray = globalDiscoveryClient.QueryApplications(
        gdsEndpointDescriptor,
        0,  # startingRecordId
        0,  # maximumRecordsToReturn
        '', # applicationName
        '', # applicationUriString
        UAApplicationTypes.All, # applicationTypes
        '', # productUriString
        Array.Empty[String](),  # serverCapabilities
        DateTime(), # out lastCounterResetTime
        0,  # out nextRecordId
        Array.Empty[UAApplicationDescription]()) # out applications
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

# Display results.
for applicationDescription in applicationDescriptionArray:
    print()
    print('Application name: ', applicationDescription.ApplicationName, sep='')
    print('Application type: ', applicationDescription.ApplicationType, sep='')
    print('Application URI string: ', applicationDescription.ApplicationUriString, sep='')
    print('Discovery URI strings: ', applicationDescription.DiscoveryUriStrings, sep='')

print()
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

Reference

IEasyUAGlobalDiscoveryClient Interface
IEasyUAGlobalDiscoveryClient Members

Documentation Home, Send Documentation Feedback. Technical Support