Introducing the ThingWorx Edge .NET SDK
This introduction is divided into the following sections for background information about the ThingWorx Edge .NET SDK:
Purpose
The ThingWorx .NET SDK enables developers to write applications that
• Establish and manage a secure AlwaysOn connection with a ThingWorx Platform, including
◦ SSL/TLS negotiation.
◦ Duty-cycle modulation.
◦ Connection maintenance, such as reestablishing a connection after network connectivity is lost and restored.
• Interact with the properties, services, and events that are exposed by entities that exist on a ThingWorx platform.
The .NET SDK implements a callback infrastructure that simplifies exposing a set of properties and services to a ThingWorx Platform. These properties and services can be surfaced from multiple entities. When a request is made from the ThingWorx Platform for a registered property or service, a callback is made to a function that was supplied when the machine/device registered with the ThingWorx Platform.
The SDK uses callback functions to notify your application of requests for property reads and writes, as well as requests for the execution of services. Your application can register the properties and services, along with their metadata, with the API. The metadata is used when browsing remote entities from ThingWorx Composer, making it simple to import functionality created in your application as a Thing or Thing Template into your application model.
ThingWorx Edge .NET SDK and ThingWorx Platform
The ThingWorx Edge .NET SDK provides a mechanism that allows you to create a remote machine/device application that communicates with a ThingWorx Platform. The SDK uses the ThingWorx AlwaysOn™ protocol for communication over websockets. This protocol permits connections to operate through a firewall, making each machine/device two-way addressable, with low latency.
The connection between a remote machine/device and the ThingWorx Platform can be configured to remain open only for specific time periods, or duty cycles, if required.
The SDK supports the following key concepts that characterize a Thing in the ThingWorx environment:
• Remote properties — Items that define the type, identity, and data items for a machine/device.
• Services — Actions that can be performed by a machine/device.
• Events — Data that is sent to a subscribed machine/device once the event is triggered.
Features of the .NET SDK
The .NET SDK supports the following functionality that allows your machine/device application to work with ThingWorx platform:
• Secure Connections — Starting with v.5.8.3 of the .NET SDK, the version of the OpenSSL libraries used by the .NET SDK is 1.1.1j. The .NET SDK supports client and server certificate validation with OpenSSL v.1.1.1j. Note that OpenSSL v.1.1.1 does not support FIPS mode. If you require FIPS mode, you need to obtain version 1.0.2l or earlier of OpenSSL. For security reasons, using older versions of OpenSSL is not recommended.
• Data Shapes — Allow you to create definitions that model the types of metadata for a remote machine/device.
• VirtualThing — A class that represents your machine/device in the .NET SDK. corresponds and is bound to a Thing (with the RemoteThing Thing Template) in ThingWorx Platform. Both entities allow you to define all of the properties, services, and events that are accessible from ThingWorx Composer and from the ThingWorx REST API.
• File transfer — A feature that enables remote directory/file browsing with ThingWorx platform, as well as bidirectional file transfer between a machine/device and the platform.
• Tunneling — A feature that allows you to establish secure, firewall-transparent, application tunnels for TCP client applications, such as VNC and SSH.
• Proxy settings — Support for connections through a proxy server to the platform.
• Client/server certificate validation — Support for enabling and disabling validation of SSL/TLS certificates. If you have the FIPS version of the SDK, the SDK also supports FIPS mode.
• Offline message storage — By default, a queue to hold outgoing messages if the network is down, or if the duty cycle modulation is in the “off” state.
• Version information — On startup, the .NET SDK prints its version number.
Requirements
As of release 5.8.0 of the .NET SDK, you use an installation program to install this SDK.The following additional software is required to develop applications with this SDK:
• Visual Studio 15 2017 (C++ tooling and a Windows SDK)
• .NET Framework, v.4.5.2 or later
As of release 5.8.0, the ThingWorx Edge .NET SDK requires that the C SDK dll be named twCSdk.dll. This dll must exist in one of the following paths:
• x86 Builds—c:\Program Files (x86)\tw-c-sdk\lib
• x64 Builds—c:\Program Files\tw-c-sdk\lib
If you want to load the twCSdk.dll from an alternative location, you must either place it on the PATH environment variable or set a library loading directory by defining the TWX_CSDK_PATH environment variable.
Digital Signing
The
thingworx-dotnet-common.dll is digitally signed as PTC Inc, using SHA256 as the digest algorithm, per the instructions at
https://msdn.microsoft.com/en-us/library/windows/desktop/jj835835%28v=vs.85%29.aspx.