Concept

Introduction

Connection to the server

Connect

This is what happens when you call the Connect method:

1. The client checks whether a server address is set (property ServerAddress). If it is missing, Connect throws an InvalidOperationException.
2. The client changes its state (property OpcClient.State) to the value Connecting. If the client is not in the Created or Disconnected state, the call has no effect.
3. The client checks its configuration for validity and consistency.
4. Next, the client searches for a suitable endpoint. For this, it uses the OpcDiscoveryClient class. It compares the endpoints with the requested endpoint configuration and selects the endpoint that matches the configuration or at least satisfies it. The criteria the client uses to select an endpoint depend on its settings. The Connection parameters section describes these criteria.
5. Then the client creates the configuration for a new session.
6. The client checks the instance certificates:
   • the certificate of the client (depending on the security configuration used)
   • the certificate of the server (the certificate that the endpoint provides)
7. Finally, the client creates a channel that serves as the connection between client and server.
8. The client tries to create a session through the channel.
9. After further session data has been exchanged and checked, the client activates the session.
10. The client retrieves the available namespaces.
11. The client sets up connection monitoring:
    • KeepAlive tracking to detect connection breaks
    • notification tracking to receive notifications
12. If data type resolution is enabled (for example through OpcClient.UseDynamic), the client also loads the type system of the server.
13. The client changes its state (property OpcClient.State) to the value Connected.

If any of these steps fails, the client returns to its previous state.

Disconnect

This is what happens when you call the Disconnect method:

1. The client changes its state (property OpcClient.State) to the value Disconnecting.
2. The client releases all acquired resources, for example file handles to file nodes.
3. The client stops connection monitoring and cancels a running attempt to restore the connection. It removes the subscriptions from OpcClient.Subscriptions.
4. The client closes the active session.
5. The client closes the channel it created when connecting and discards it.
6. The client changes its state (property OpcClient.State) to the value Disconnected.

Detect connection breaks

Break detection (BreakDetection) detects breaks in the connection to the server. It uses the KeepAlive mechanism: the client sends a KeepAlive request to the server at regular intervals to check and maintain the connection. The OpcClient.KeepAlive.Interval property sets the interval, 5000 milliseconds by default. The OpcClient.KeepAlive property provides the result of the last request (for example Status, ServerState, and Time). The OpcClient.KeepAlive.Updated event reports every new response.

If a KeepAlive request fails, the client assumes that the connection is interrupted. The same applies at once, without waiting for the next KeepAlive, if a service call as a whole fails with a status that indicates a lost connection, for example BadConnectionClosed or BadSessionIdInvalid. The call itself still throws its exception:

1. The client changes its state to the value Reconnecting (event OpcClient.Reconnecting).
2. Then it tries to restore the existing session at fixed intervals. The OpcClient.ReconnectInterval property sets the interval, 10000 milliseconds by default. If this is no longer possible within the session lifetime (property OpcClient.SessionTimeout), the client creates a new session and re-creates the subscriptions in it.
3. If it restores the existing session, the client changes its state to the value Reconnected (event OpcClient.Reconnected). If it has created a new session, it changes its state to the value Connected (event OpcClient.Connected).
4. The OpcClient.MaxReconnectDuration property sets how long the client tries at most. It is 0 by default, so the attempts are unlimited. If this time elapses before an attempt succeeds, the client changes its state to the value Disconnected and raises the OpcClient.BreakDetected event. After that, it no longer reconnects by itself; only a call to Connect establishes the connection again.

If the OpcClient.ReconnectInterval property is set to the value 0, the client does not try to restore the connection. Instead, it changes its state to the value Disconnected and raises the OpcClient.BreakDetected event. Break detection is enabled by default. The OpcClient.UseBreakDetection property turns it on and off. If it is disabled, the client does not monitor the connection. The Connection monitoring section shows how to configure break detection.

Connection parameters

To let the client connect to the server, set the right parameters. The client always needs the address at which the server is reachable (property OpcClient.ServerAddress). The address is a URI (Uniform Resource Identifier) and gives the client all essential information about the server. For example, the server address opc.tcp://192.168.0.80:4840 contains the scheme opc.tcp. The scheme defines the protocol and the way the data is exchanged. The possible schemes are opc.tcp and https. For OPC UA servers in the local network, we recommend opc.tcp. For servers outside the local network, https can be a good choice. The address also states that the server runs on the computer with the IP address 192.168.0.80 and listens for requests on port 4840. This is the default port for OPC UA, and custom port numbers are possible as well. Instead of the static IP address, you can also use the DNS name of the computer, for example localhost instead of 127.0.0.1.

If no endpoint policy is set (property OpcClient.Security.EndpointPolicy), the client selects the endpoint automatically. Of the endpoints with the scheme of the server address, it takes the one with the lowest policy level, a number that the server assigns. This is usually an endpoint with the security mode None. The other possible modes are Sign and SignAndEncrypt. If the server does not offer such an endpoint, the client automatically selects the next one, for example one with Sign. The client skips endpoints with the security mode None whose security algorithm is not None, and endpoints with an unknown security algorithm. If it does not find a suitable endpoint, Connect throws an OpcException with the status BadSecurityChecksFailed.

You can restrict the automatic selection to encrypted endpoints (property OpcClient.Security.UseOnlySecureEndpoints, disabled by default). Then only endpoints with the security mode SignAndEncrypt qualify. The client can also select the endpoint as the OPC Foundation specifies: the endpoint with the highest policy level then automatically counts as the best one for data exchange. This behavior is disabled by default. You enable it with the OpcClient.Security.UseHighLevelEndpoint property.

If the client must enforce a specific endpoint policy, set it with the OpcClient.Security.EndpointPolicy property. The client then uses only an endpoint with exactly this security mode and security algorithm. With the OpcClient.Security.AutoUpgradeEndpointPolicy property, the client switches to the next better endpoint if the server does not offer the specified policy. The OpcClient.UsedEndpoint property returns the endpoint that the client actually uses.

If the server uses access control, for example through an ACL (access control list), the client must send valid user data to the server before a connection is established. With this data, the server determines the identity of the user who operates the client. The user identity can be a user name and password pair (class OpcClientIdentity) or a certificate (class OpcCertificateIdentity). Pass the identity to the client with the OpcClient.Security.UserIdentity property. The client then sends it to the server when it connects. The section Authenticate users describes how to change the identity of an existing session.

Endpoints

The endpoints result from the cross product of the base addresses of the server and the security policies that the server supports. Each base address results from a supported pair of scheme and port, and the host (IP address or DNS name). For data exchange, you can set several schemes (opc.tcp and https are possible) on different ports. The policies combined with them define how data is exchanged. Each policy consists of the policy level, the security mode, and the security algorithm, and so defines the kind of secure data exchange.

Suppose the server supports two security policies:

• Security policy A: level 0, security mode None, security algorithm None
• Security policy B: level 1, security mode Sign, security algorithm Basic256Sha256

In addition, there are three base addresses for different schemes:

• Base address A: https://mydomain.com/
• Base address B: opc.tcp://192.168.0.123:4840/
• Base address C: opc.tcp://192.168.0.123:12345/

The cross product results in the following endpoint descriptions:

• Endpoint 1: address https://mydomain.com/, level 0, security mode None, security algorithm None
• Endpoint 2: address https://mydomain.com/, level 1, security mode Sign, security algorithm Basic256Sha256
• Endpoint 3: address opc.tcp://192.168.0.123:4840/, level 0, security mode None, security algorithm None
• Endpoint 4: address opc.tcp://192.168.0.123:4840/, level 1, security mode Sign, security algorithm Basic256Sha256
• Endpoint 5: address opc.tcp://192.168.0.123:12345/, level 0, security mode None, security algorithm None
• Endpoint 6: address opc.tcp://192.168.0.123:12345/, level 1, security mode Sign, security algorithm Basic256Sha256

The client always needs the address part of the endpoint, either through the constructor or through the ServerAddress property. Of the endpoints with the scheme of this address, the client selects the one with the lowest level by default. In the example above, this is endpoint 3 for the address opc.tcp://192.168.0.123:4840/. If the client should use endpoint 4 instead, set its policy with the OpcClient.Security.EndpointPolicy property.

Certificates and security

The SDK aims to make getting started with OPC UA as easy as possible. For this reason, the connection between client and server is not fully secured unless you configure the client further. As soon as you have implemented and tested the final spike, you should turn to security:

• The Understand certificates page describes how certificates identify client and server, where they are stored, and how the applications check them.
• The Users and roles page describes how users log on and which permissions they receive.
• The Harden for production section contains all settings for production and a checklist.