Generate API client libraries from Engineering API

• Overview
• For CSharp Environment
• Prerequisites
• Generate API client libraries using Swagger Codegen CLI
• CSharp client library for PLC Engineering
• CSharp client library for IO Engineering
• Java client library for PLC and IO Engineering
• Client library for other languages
• Create a Test Application
• CSharp console application for PLC Engineering

Overview

This blog will show you how to generate API client libraries. API client libraries is a code or an app that can access the provided REST services. Client code generators are used to create such API Client Libraries. Few well known client code generators are Swagger Codegen CLI, AutoRest, NSwag, and OpenAPI Generator. These tools  require NPM or the Java Runtime Environment to be installed on the developers machine. Alternative Java SDK implementations such as the OpenJDK works fine with this extension. 

The Swagger Codegen CLI and OpenAPI Generator are distributed as JAR files and are downloaded on demand but requires the Java SDK to be installed on the machine. AutoRest is installed on-demand via NPM as a global tool and uses the latest available version.

NSwagStudio is stand alone UI tool for editing a .nswag specification file for generating code. This tool is optional to install and official installation instructions are available on the NSwag Wiki on Github. If NSwagStudio is not installed on the machine then the Visual Studio Extension will install the NSwag CLI via NPM as a global tool using the latest available version.

For CSharp Environment

• The OpenAPI Generator and Swagger Codegen CLI code generators produces code that depends on the RestSharp and JsonSubTypes NuGet packages.
• The AutoRest code generator produces code that depends on the Microsoft.Rest.ClientRuntime and Newtonsoft.Json NuGet packages.
• The NSwag code generator produces code that depends on the Newtonsoft.Json NuGet package.
  
  

Prerequisites

• Latest ctrlX WORKS with PLC and IO Engineering is installed
• Visual Studio is installed. (As an alternative Visual Studio Code can be used with extension C# for Visual Studio Code)
• Swagger Codegen CLI is downloaded. For Windows users, you can use Invoke-WebRequest in PowerShell (3.0+) to download swagger-codegen-cli v3.0.33, e.g.
  
  Copy

  Invoke-WebRequest -OutFile swagger-codegen-cli.jar https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.33/swagger-codegen-cli-3.0.33.jar

• If you're looking for the latest stable Swagger Codegen CLI version, you can grab it directly from Maven.org (search for swagger-codegen-cli)

• Swagger Codegen is a Java app, so you must have Java Runtime Environment installed. Additionally JAVA_HOME environment variable, should point to java.exe path
  
  

Generate API client libraries using Swagger Codegen CLI

CSharp client library for PLC Engineering

• Open installed ctrlX WORKS directory and navigate to → Studio\Help\API-CodeGenerator. (For ctrlX WORKS WRK-V-0112.4 version and below,  folder 'API-CodeGenerator' is not available, you can download the files from attachment)
• Copy the contents of API-CodeGenerator and downloaded swagger-codegen-cli.jar to a folder inside your work directory (e.g. D:\CodeGen) as shown below:
  
  

  

• To generate PLC Engineering API client library, run 'Generate_Rexroth_PlcEng_APIClient_CSharp.bat'
• After successful generation, you will see a folder named 'Rexroth_PlcEng_APIClient_CSharp' as shown below:
  
  

  

• Navigate to 'Rexroth_PlcEng_APIClient_CSharp' directory and run 'build.bat'. This downloads required packages and DLLs are available under bin folder as shown below. (The Codegen also creates a README file with all the information for running and building the API)
  
  

• Open 'Rexroth.Api.PlcEngineering.sln', project will be opened in Visual Studio
• In Visual Studio, navigate and open Edit → Find and Replace → Replace in Files
  
• In the editor, enter base(elementType, name, id, children) in find textbox  and enter base(elementType, name) in replace textbox and click on Replace All as shown below. (This step is required to correct few errors caused by Swagger Codegen CLI for CSharp language. Same errors might not occur in different language(s) or with different code generator(s))
  
  

• Again enter base(jobType, id, state, progress, jobResultInfo) in find textbox  and enter base(jobType, jobResultInfo) in replace textbox and click on Replace All as shown below. (This step is required to correct few errors caused by Swagger Codegen CLI for CSharp language. Same errors might not occur in different language(s) or with different code generator(s))
  
  

  

• Only for ctrlX WORKS WRK-V-0112.4 version and below, additional changes are required to the generated file (Rexroth_PlcEng_APIClient_CSharp\src\Rexroth.Api.PlcEngineering\Model\RecipeManager.cs). Changes should match to below shown images (see line number in the below image as reference):
  

  

  

  

• In Visual Studio, navigate and click on Build → Rebuild Solution. (Rebuild Solution should be successful, If you still have build error, ask for help in the comment section)
• After successful build,  DLL's are available (under the `bin` folder) in the C# project as shown below:
  
  

  

• For more information/examples on available API functions, navigate to menu Help → API-reference in ctrlX PLC Engineering
  
  

CSharp client library for IO Engineering

• Run 'Generate_Rexroth_IoEng_APIClient_CSharp.bat' and follow steps similar to client library generation for PLC Engineering
• For more information/examples on available API functions, navigate to menu Help → API-reference in ctrlX IO Engineering
  
  

Java client library for PLC and IO Engineering

• Run 'Generate_Rexroth_PlcEng_APIClient_Java.bat' and 'Generate_Rexroth_IoEng_APIClient_Java.bat'
• To build and install the generated API client, follow the README file inside the created 'Rexroth_PlcEng_APIClient_Java' and 'Rexroth_IoEng_APIClient_Java' folder
  
  

Client library for other languages

• Swagger Codegen CLI also supports many other languages/frameworks. For more information visit there GitHub
  
  

Create a Test Application

CSharp console application for PLC Engineering

• In Visual Studio, navigate and click on File → New → Project. Follow the instructions in the dialog and Create an Console App (.NET Framework)
• Add generated 'Rexroth.Api.PlcEngineering.dll' reference to the created console application as shown below:
  
  

  

• Open Program.cs file and replace existing code with below code:
  Copy

  using System;
  using System.Collections.Generic;
  using System.Diagnostics;
  using System.Threading;
  using Rexroth.Api.PlcEngineering.Api;
  using Rexroth.Api.PlcEngineering.Client;
  using Rexroth.Api.PlcEngineering.Model;
   
  namespace ConsoleApp
  {
    public class Program
    {
      static void Main(string[] args)
      {
        try
        {
          Console.WriteLine("Start PLC Engineering and create a new project");
          //Latest installed or latest used ctrlX WORKS instance will be used to start engineering
          //For ctrlX WORKS version WRK-V-0112.4 and below, protocol 'rexrothstudio://plc/?' to start engineering is not supported, use
          //Process.Start(@"path to engineering exe") and open existing project using 'ProjectJob' in API
          Process.Start("rexrothstudio://plc/?hostname=localhost&newproject=d:\\ctrlX\\Projects");
   
          //Wait till Engineering is ready for input
          Thread.Sleep(20000);
   
          //Set base path to the actual URL with port
          Configuration config = new Configuration {BasePath = "http://localhost:9002/plc/engineering/api/v2"};
   
          //Create new device api instance with the actual URL
          DevicesApi devicesApi = new DevicesApi(config);
   
          //Create a device with mandatory parameters
          Device ctrlXCoreDevice = new Device(name: "ctrlXCoreDevice", elementType: "Device");
          DeviceInfo deviceInfo = new DeviceInfo(deviceType: 4096, id: "1001 0080");
          ctrlXCoreDevice.DeviceInfo = deviceInfo;
   
          BaseElement addedDevice = devicesApi.AddDevices(ctrlXCoreDevice);
          Console.WriteLine($"Device added: {addedDevice.Name}");
   
          //Create and add task configuration
          TaskConfig taskConfigObj = new TaskConfig(elementType: "TaskConfig", name: "Task Configuration");
          devicesApi.AddDevicesByPath(taskConfigObj, "/ctrlXCoreDevice/PLC Logic/Application");
          Console.WriteLine("Task Configuration added");
   
          //Create and add a task
          Task taskObj = new Task(elementType: "Task", name: "MyTask")
          {
            Priority = "30",
            TaskGroup = "IEC-Tasks",
            Type = new TaskType("cyclic", "t#20ms"),
            Watchdog = new TaskWatchdog(false, "", "1"),
            PouCalls = new List<TaskPouCall>()
          {
            new TaskPouCall("Prg1", ""),
            new TaskPouCall("Prg2", "")
          }
          };
          devicesApi.AddDevicesByPath(taskObj, "/ctrlXCoreDevice/PLC Logic/Application/task-config");
          Console.WriteLine("Task added");
   
          Console.ReadLine();
        }
        catch (Exception e)
        {
          Console.WriteLine(e);
          throw;
        }
      }
    }
  }

• After successful Build, Start the console app. This will start the ctrlX PLC Engineering with a new project and a Device, Task Configuration, Task will be added to the project