ThingWorx Edge .NET SDK Reference > .NET SDK: ClientConfigurator Class
.NET SDK: ClientConfigurator Class
The ClientConfigurator class contains settings that the ConnectedThingClient uses to connect to the ThingWorx Platform and control its behavior. It also contains configuration options used for the following subsystems:
File Transfer
Tunneling
Proxy Servers
Client/Server Certificate validation
X.509 Field validation
Duty Cycle modulation
Offline Message Storage
TLS Host Name Validation
As of v.5.8.2, the .NET SDK supports TLS host name validation. TLS host name validation compares the requested host name with the CN field on the server certificate. If they do not match exactly, the TLS handshake fails and the connection fails.
TLS host-name validation occurs during the TLS Handshake. When host name validation is enabled, if the host name on the server certificate does not match the host provided to the .NET SDK, the handshake and connection fail, with the error, TW_SOCKET_INIT_ERROR. Check the logs of your application for an ERROR-level log message that notes the cause as host name validation failed.
* 
Partial wildcards in the CN field of the host certificate are not currently supported in TLS host name validation. The host certificate must match the destination host name exactly. For example, a host certificate with CN=platform.domain.com can be validated, but CN=*.domain.com cannot. If your host is using certificates with wildcards, host name validation must be disabled.
Properties of the ClientConfigurator Class
The following table lists and briefly describes the properties available on the ClientConfigurator class:
Properties of the ClientConfigurator Class
Property
Description
AllowSelfSignedCertificates(Boolean)
The default value is false. Set to true to accept self-signed certificates. Do NOT use this setting in a production environment.
AutoReconnect(Boolean)
The default value is false. If you want to reconnect automatically to the ThingWorx Platform when a connection is lost, set this property to true.
ClientKeyFileInfo.Claims
Through the use of a password callback function, stores the passphrase for a client key file.
ConnectRetries(String value)
Specify the number of retries when trying to establish a WebSocket connection. The Connect call returns an error after the retries are exhausted.
ConnectTimeout(String value)
Specify the number of milliseconds to wait for the WebSocket connection to be established.
DisableCertValidation(Boolean)
The default value is false. Set to true to notify the TLS library to not validate the server certificate. Do NOT use the true value in a production environment.
Enab leTlsHostnameValidation(Boolean)
Setting this value to true enables TLS host name validation. Setting it to false disables it. The default value is true.
ForceConnectOnFireEvent(Boolean)
Set to true to force a reconnect to send the message when in the disconnected state of the duty cycle,
ForceConnectOnInvokeServiceBoolean)
Set to true to force a reconnect to send the message when in the disconnected state of the duty cycle,
ForceConnectOnReadProperty(Boolean)
Set to true to force a reconnect to send the message when in the disconnected state of the duty cycle,
ForceConnectOnWriteProperty(Boolean)
Set to true to force a reconnect to write a property when in the disconnected state of the duty cycle.
IdlePingRate(String value)
Set the WebSocket keep alive rate. Used to ensure the connection stays open. Measured in seconds. This value should never be greater than the ThingWorx Platform side setting, which defaults to 60 seconds.
MaxConnectDelay(String value)
Set the maximum delay before connecting. Measured in milliseconds.
MaxMessages(String value)
Set the maximum number of messages that have not been processed to allow in the message queue.
MaxMessageSize(String value)
Set the maximum size of a complete message whether it is broken up as a multipart message or not. Messages larger than this will be rejected. Measured in bytes.
MaxMsgHandlerThreadCount and MaxApiTaskerThreadCount
REQUIRED. Set the maximum size of the thread pools. For example, 8 threads for each property.
MessageChunkSize(String value)
Set the maximum size of a message chunk, in bytes. Messages large than this will be broken up into a multipart message. This value should be the same as the ThingWorx Platform side configuration which defaults to 8192.
MessageFrameSize(String value)
Set the maximum size of a message frame (in bytes).
MessageTimeout(String value)
Set the number of milliseconds to wait for the ThingWorx platform to respond to a ping message.
Name(String value)
Optional. Set the name of the client. For example:
Name = "SteamSensorGateway",
If the name property is not set, the .NET SDK will use a prefixed GUID for the gateay name BIND requests.
* 
This value is used for the gateway name in BIND requests. If you are using a Gateway Name, make sure that it is unique to your specific agent instance. Your entire BIND request may be declined if another client has already claimed your Gateway Name.
OfflineMsgStoreDir
REQUIRED IF using the Offline Message Store. Setting this property tells the SDK where to put the offline message store. The directory specified must be writable from the application. Here is an example:
OfflineMsgStoreDir = Environment.CurrentDirectory = Environment.GetEnvironmentVariable("userprofile")
For details about the Offline Message Store, refer to .NET SDK ClientConfigurator: Offline Message Store.
PongTimeout(String value)
Set the number of milliseconds to wait for the ThingWorx platform to respond to a ping message.
ReconnectInterval(String value)
REQUIRED. Set the number of seconds to wait before retrying the connection. For example:
ReconnectInterval = 15,
SecurityClaims
REQUIRED. Pass the appKeyCallback function to the Claims object of the ClientConfigurator. This function should retrieve an application key from a secure source at runtime. The application will need the application key to acces the ThingWorx Platform. For more information and an example, refer to Encrypting Passwords and application keys and Security Claims and Encrypted application key (v.5.8.0+). Refer to .NET SDK: SecurityClaims Class.
setType(String value)
Set the type of the client.
SocketReadTimeout(String value)
Set the socket read timeout. The default value of this property is 0, which is recommended as a best practice to achieve optimal performance when transferring large files. Refer to Best Practices for Transferring Large Files.
StaleMsgCleanupRate
Set the rate of periodic cleanup rate multipart messages that never receive all of the expected number of message chunks. Measured in milliseconds.
StreamBlockSize
Set the incremental block size for dynamically allocated stream (byte array) variables. When adding bytes to a stream, this is the size of memory allocated if more memory is needed.
Uri(String uri)
REQUIRED. Set the URI to use for connecting to the ThingWorx Platform. This URI is in the following form for secure websockets:
wss://<server>:<port>/ThingWorx/WS
Where <server> is the IP address or domain name of the ThingWorx Platform and <port> is the port that the ThingWorx Platform is listening on.
The SteaamSensorClient.cx example pulls this URI from the command line property values for the application, as shown here:
Uri = args[0],
Here is an example of a ClientConfigurator from the SteamSensorClient.cs example:

// Set the required configuration information
var config = new ClientConfigurator
{
// Set the size of the threadpools
MaxMsgHandlerThreadCount = 8,
MaxApiTaskerThreadCount = 8,

/***** WARNING: For Development purposes only. Do not use these settings in a production environment. *****/
//config.AllowSelfSignedCertificates = true;
DisableCertValidation = true,
/***** WARNING *****/

// The uri for connecting to Thingworx
Uri = args[0],

// Reconnect every 15 seconds if a disconnect occurs or if initial connection cannot be made
ReconnectInterval = 15,

// Give the appKeyCallback function to the ClientConfigurator's Claims object, to use as needed
Claims = SecurityClaims.fromAppKeyCallback(appKeyCallback),

// Set the name of the client
Name = "SteamSensorGateway",

// Put the offline message store into a writable directory
OfflineMsgStoreDir = Environment.CurrentDirectory = Environment.GetEnvironmentVariable("userprofile")
};
* 
To learn how to bind entities to ThingWorx, refer to ConnectedThingClient Methods.
Encrypting Passwords and application keys (v.5.8.0+)
As of v.5.8.0 of the .NET SDK, password protection is your responsibility. For the SDK to use a password such as a proxy password or a passphrase, you need to develop a way for the password to be provided securely to the a callback function. The affected PASSWORD types are proxy passwords and digests, certificate passwords and passphrases for key files,
The application key callback can be used to supply an application key whenever an application requires it for authentication with a ThingWorx Platform. This callback usage applies to all .NET SDK functions that require an application key as input. For example, it supplies an application key to the TunnelManager.
* 
In production, the callback should obtain an application key or other required PASSWORD from a secure source.
Here is an example of using the appKeyCallback() function from the SteamSensorClient.cs file:

// Application key to connect to the Thingworx instance
var appKey = args[1];

// This example pulls the appkey from the command line properties
// In production, this callback should obtain an app key from a secure source.
TwPasswordDelegate appKeyCallback = (password, maxLength) =>
{
string safePassword = appKey;
if (safePassword.Length > maxLength - 1)
{
safePassword = safePassword.Substring(0, maxLength - 1);
}
IntPtr stringPointer = (IntPtr)Marshal.StringToHGlobalAnsi(safePassword);
twCopyMemory(password, stringPointer, (uint)safePassword.Length);
Marshal.FreeHGlobal(stringPointer);
};
Refer to .NET SDK: SecurityClaims Class for more information and examples.
Security Claims and Encrypted Application Keys (v.5.8.0+)
Use the method, fromAppKeyCallback(TwPasswordDelegate appKeyCallback), to return a SecurityClaims object whose security is based on an application key. The TwPasswordDelegate Type is a customization of the .NET delegate Type.
Here is an example from the SteamSensorClient.cs file:

// Give the appKeyCallback function to the ClientConfigurator's Claims object, to use as needed
Claims = SecurityClaims.fromAppKeyCallback(appKeyCallback),
. . .
* 
For information on the C# delegate type, visit Delegates (C# Programming Guide).
Refer to .NET SDK: SecurityClaims Class for more information.
For information on the older versions of the .NET SDK and in particular, Security Claims, refer to the topic, .NET SDK: ClientConfoigurator Class in the original ThingWorx Edge SDKs and WS EMS Help Center.
Was this helpful?