# Introduction

> Concept: The concepts that every client development with the OPC UA .NET SDK builds on: connecting, connection parameters, endpoints, and security.

> This content was machine translated and may contain errors. [Read in German](https://www.traeger.de/docs/development/opcua/client/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](https://www.traeger.de/en/docs/development/opcua/client/introduction#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](https://www.traeger.de/en/docs/development/opcua/client/configuration#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](https://www.traeger.de/en/docs/development/opcua/security/client#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](https://en.wikipedia.org/wiki/Spike_%28software_development%29), you should turn to security:

- The [Understand certificates](https://www.traeger.de/en/docs/development/opcua/security/certificates) page describes how certificates identify client and server, where they are stored, and how the applications check them.
- The [Users and roles](https://www.traeger.de/en/docs/development/opcua/security/users-roles) page describes how users log on and which permissions they receive.
- The [Harden for production](https://www.traeger.de/en/docs/development/opcua/security/client#harden-for-production) section contains all settings for production and a checklist.