Build an Agent using .NET SDK
Prerequisites
Before you create an agent using .NET, ensure that you have the following prerequisites set on your system:
• Visual Studio 2013 +, preferably Visual Studio 2015
• NuGet packages for log4net
The NuGet packages can also be downloaded and added as references by using Add Reference in Visual Studio.
• Libraries to communicate with your own analysis software
Build an agent by using the .NET SDK
Complete the following steps to build an analysis agent by using .NET:
1. Extract the TWX_AS-<version n.n.n>-dotnet-service-sample zip to the AnalysisSDK-dotnet-service-sample folder. The following image shows the directory structure after the zip file is extracted:
The purpose of different files in the zip is described below:
◦ The AnalysisSDKSample.sln contains a single C# console project. It depends on libraries available in the libs directory.
◦ The AnalysisServiceDemoApp.csproj is a C# project.
◦ The App.config is the configuration file for the demo application.
◦ The config.properties includes configuration properties for the agent.
◦ The log4net.dll is used to configure logging.
◦ The MyAnalysisServiceImpl.cs contains methods to manage models and jobs within the Analytics Manager framework.
◦ The packages.config contains a list of NuGet packages that are required to build the application.
◦ The Program.cs file contains the driver program for starting the agent and registering the analysis service implementation with it.
◦ The AssemblyInfo.cs provides properties for the assembly. For example: version number, name, and so on.
◦ The AnalysisSDKAgentLib.dll contains code for starting an agent and registering the analysis service with it. This library acts as an interface between the connector and your analysis service implementation.
◦ The sigar.dll is used to gather health information of the system and the specific analysis tool.
◦ The thingworx-dotnet-common.dll and the twApi.dll libraries are required to communicate with the ThingWorx server over a web socket connection.
◦ The TWXLauncher.exe is used internally. This must be present in the applications directory.
◦ The TWXLauncher.exe.config is the application-specific configuration file.
◦ The TWX_AS_SDKAgent.exe is used to run the agent in standalone mode.
◦ The TWX_AS_SDKAgent.exe.config is the application-specific configuration file.
◦ The MyAnalysisServiceImpl.cs file contains the implementation of IAnalysisService.
The sample is a fully functional implementation of the analysis agent and can execute mock analysis. To test it out of the box, update the app.config file to suit your requirements. Ensure that you use the Analysis Main mashup for testing and deploy a model called addition.
2. Modify IAnalysisService (MyAnalysisServiceImpl) to communicate with your analysis software. You can either include the SDK of your analysis software or incorporate a particular protocol by using appropriate libraries.
3. Configure the AnalysisSDKAgent library by setting properties in the configuration file for your application in the appSettings section. The following table provides information about the properties that you might need to change:
The following table provides information about the mandatory properties. If you want, you can change the values of these properties as per your requirement:
Property | Description |
URI | Specifies the URI of the ThingWorx server where the Analytics Manager framework is running. For example: ws://localhost:8080/Thingworx/WS |
UserId | Specifies the ID of the user that is used to establish connection to the server. |
Password | Specifies the password of the user that is provided for connection. |
AppKey | Instead of using a user ID and password for authentication, you can use the application key that you have created on the ThingWorx server. |
ConnectorName | Specifies the name of the connector instance that is created for interacting with an analysis provider and is used while configuring the analysis provider on the server side. For example: TW.AnalysisServices.TestSDKConnector |
AppImplClass | Specifies the fully qualified name of the class that implements the application interface. This class contains the bridging code between the agent and the analysis provider. This class must be in the classpath provided to the JVM when running the agent. | You do not need to specify this property when the agent is being run on a deployer agent. |
For example: AnalysisServiceDemoApp.MyAnalysisServiceImpl,AnalysisServiceDemoApp |
UseProxy | Set to true, if a proxy is used to connect to the ThingWorx server. |
ProxyHost | Specifies the proxy host used, if the UseProxy property is set to true. |
ProxyPort | Specifies the proxy port used, if the UseProxy property is set to true. |
AgentWorkDir | Specifies the directory used by the agent to store model files, temporary files, result files, and data files. The default AgentFiles folder is created in the installation directory of the agent. The following subdirectories are created under this directory: • Models • TempFiles • Results • DataFiles |
RetainResultFiles | Set to true so that the agent saves the result files after completing a job. This can be used for debugging purposes. |
log4net_config | Specifies the configuration file that controls the logging information of the agent. For example: log4net.config |
QueueLengthUpperBound | Specifies the number of jobs that can be queued for execution by the agent. |
The following table provides information about the optional properties of the agent. If you want, you can change the values of these properties, as per your requirement:
Property | Description | Default Value |
AgentId | Specifies a unique string that is used for identification of an agent to the ThingWorx server. If the value is not specified, a unique ID is generated automatically and is reused until a different one is provided using this property. | MyAgent |
UseRedundantAgent | Used to monitor the primary agent for crashes. If the value is set to true, a secondary agent is launched at startup. This secondary agent monitors the primary agent. If the primary agent crashes, it is restarted automatically. If the secondary agent fails, the primary agent restarts it. | false |
GatherClientHealthData | Set the value to true to monitor the health of the client. | false |
ClientHealthDataInterval | Specifies the time interval in milliseconds after which the agent SDK polls the system and its clients for health information. | 60000 |
ClientInstanceInitCount | Specifies the number of client instances that start when the agent is started. | 1 |
ClientInstanceMaxCount | Specifies the maximum number of client instances that this agent can start. Specify a value greater than 0 to provide a fixed maximum value for the number of clients. | -1 | This value specifies that the agent can start an unlimited number of clients. |
|
CallTimeout | Specifies the time in milliseconds that a server call waits before failing with a time-out error. Set this value according to the latency of the network. | 90000 |
SimulationInterval | Specifies the agent wait time between simulation jobs. If an existing simulation job is running, and a new job comes in before this specified interval, then the agent skips the execution of the job. | -1 | This value specifies that all jobs are executed without any interval check. |
|
Run the Agent
Use one of the following methods to run the agent:
• Standalone Mode — Use this mode when you cannot modify the analysis tool. In this mode, the Analysis SDK agent library is the main program. It loads the service implementation as needed. To run the SDK in standalone mode, launch the TWX_AS_SDKAgent.exe file. The property should be added to the config.propeties file present in the same directory as the executable file. The above referenced class should be present in a .dll file in the path.
• Embedded Mode — Use this mode when you can modify the analysis tool. In this mode, the Analysis SDK agent library is loaded by the analysis software that has also been developed using the .NET framework. The program.cs file is used to start and stop the agent. Ensure that all libraries and configuration files are present in the applications directory.
Configure SSL
1. Configure Tomcat to use a self-signed SSL certificate. For information about how to do this, follow the steps at
PTC Support.
2. Update the URI to use the HTTPS port, usually 8443 on Tomcat.
For example, wss://mymachine:8443/Thingworx/WS. Since the agent code allows communication with sites with self-signed certificates, the communication works automatically.
