SCM Client .NET Example
This sample application demonstrates how to create a console application that connects to the ThingWorx Platform to expose your device as a target for an SCM deployment. The SCM Client is provided as a binary for you, and can be found in the installation directory, C:\Program Files (x86)\tw-scm-dotnet or c:\Program Files\tw-scm-dotnet). The first section below explains how to run this application. For details on the properties used, see Parameters
to Set.
Running the scm_client Application
The following procedure for running the scm_client.exe example application provides information for Windows users. This procedure assumes that you have imported the ThingWorx Utilities Core and ThingWorx SCM Extension. If you need instructions, see
1. Log in to ThingWorx Composer, and import the XML file that contains the SCM Client ThingWorx Platform Thing; its default installed location is.C:\Program Files (x86)\tw-scm-dotnet\import\Things_SampleScmDevice.xml.
2. Using a text editor, open the C:\Program Files (x86)\tw-scm-dotnet\whitelist.txt file. Make sure that the .bat file extension is in the whitelist:
# This is a sample whitelist
# please review it before using it in production
js,C:\Program Files\node\node.exe
bas,C:\Program Files\cscript.exe
bat,CMD /C
py,C:\Program Files\python\python.exe
# please review it before using it in production
js,C:\Program Files\node\node.exe
bas,C:\Program Files\cscript.exe
bat,CMD /C
py,C:\Program Files\python\python.exe
The whitelist shown above allows the execution of scripts written node.js (js), BASIC (bas), Windows batch (bat), and Python (py).
3. Run the application and specify the proper properties to connect to your ThingWorx SCM-enabled ThingWorx Platform:
Windows Users (Running the binary provided from a Command Prompt)
a. Open a Command Prompt as Administrator, and navigate to the directory in which the SCM Edge Extension was installed:
▪ 32-bit Windows, C:\Program Files (x86)\tw-scm-dotnet
▪ 64-bit Windows, C:\Program Files\tw-scm-dotnet
.
b. Run the application, as follows:
scm_client -h <hostname> -p <port> -k <appkey> -w whitelist.txt
 |
If specifying on the file name for the whitelist does not work, try providing the full path, in double quotation marks: "C:\Program Files (x86)\tw-scm-dotnet\whitelist.txt" (32-bit) or "C:\Program Files\tw-scm-dotnet\whitelist.txt" (64-bit). The double quotation marks are needed because there is a space in the path.
|
◦ Windows Users (Running in Visual Studio)
To run the scm_client from Visual Studio, follow these steps:
1. Right-click the scm_client project in Visual Studio, and select it as your startup project.
2. Configure the properties for the project, and set the command-line properties to
-h <hostname>
-p <port>
-k <appkey>
-w "C:\Program Files (x86)\tw-scm-dotnet\whitelist.txt"
-l <loglevel>
The log levels available are
▪ 0 — None
▪ 1 — ERROR
▪ 2 — WARN
▪ 3 — INFO
▪ 4 — DEBUG (the default level)
▪ 5 — TRACE
3. Start the project in Visual Studio.
|
|
If you want to see the output of a console application but it quits too fast, you can redirect console output to the immediate window. Just do not forget to clear it because the setting persists between runs. The following screen shot shows you how:  |
Parameters to Set
Descriptions of each property that you need to set when running this example follow:
• -h hostname—The name of the computer where your ThingWorx Platform is running. The value for this property is not a URL. It can be a DNS name, localhost, or a numeric IP address.
• -p port—The port that your ThingWorx application is using on your server. Common values are 80, 8080, or 443
• -k appKey —Generate an application key using ThingWorx Composer, encrypt it, and copy it to the value of this property. This key acts as the credentials that this service should use when it connects to the platform. Alternatively, you can store the encrypted Application Key in the environment variable TWX_APP_KEY instead of the -k appKey property.
• -w whitelist—A path to a CSV file listing the extensions and applications used to execute scripts that have this extension.
• -n name—The thing name that you have created in ThingWorx to represent this device. This will be the name of your device in the SCM console. The thing should have the Thing Template, TW.RSM.Template.AssetWithTunnelsAndFileTransfer and the following Thing Shapes applied:
◦ TW.RSM.SFW.ThingShape.Updateable
◦ PTC.Resource.Asset.SCMResourceThingShape
• -l logLevel—You may reduce your log level before you start the service by setting this value. Acceptable values are:
◦ 0 — None
◦ 1 — ERROR
◦ 2 — WARN
◦ 3 — INFO
◦ 4 — DEBUG (the default level)
◦ 5 — TRACE
Your log level will default to 0 if no value is given.
• -s stagingDirectory—A working directory where files will be uploaded to this device and from which the scripts will be run. This directory must be writable from your service.
• -v validationFile—This configuration file is optional and is used to enable digital signature support on the client. Here is an example of the contents of this file:
# Sample Validation File
validationEnabled=true
validatePublicCertificate=no
pathToPublicKeyFile=public_key.pem
requiredCN=
where:
◦ validationEnabled—Allows you to switch on or off the validation of a package using digital signatures.
◦ validatePublicCertificate—Requires that the public certificate come from a known provider through a valid trust chain.
◦ pathToPublicKeyFile—The path on the local file system to the public key file in RSA PEM format to use for validation. Note that this key is not protected by a password and should have restricted access on your file system. Exposure of this public key is not a security risk as it cannot be used to reverse engineer the original private key that was used to sign your package. However, alteration of the public key on the device could allow an unauthorized user to replace the public key and deploy packages in the future.
◦ requiredCN—This property specifies a domain name that must match the CN field of the public certificate for it to be used for validation. If this field is not blank, your public key will be rejected, and no packages will be able to be deployed. If the requiredCN is blank, there are no CN field requirements.