Introduction

EPLAN Remoting

EPLAN Remoting is a part of API which enables user to connect to an EPLAN Platform variant and control it in remote way. 

Internally it uses gRPC and protocol buffers (protobuf) technology. 

How to connect

The connection is established form client application (a .NET program written by API user) to existing EPLAN instance which is available in network. 

Condition of use

The condition is that the EPLAN variant is started as a remoting server (without the  /NoRemoting  parameter). 

Libraries

EPLAN Remoting consist of following internal libraries:

• Eplan.EplApi.RemoteClientu.dll  (namespace Eplan.EplApi.RemoteClient)
• Eplan.EplApi.Remotingu.dll  (namespace Eplan.EplApi.Remoting)

external libraries:

• Google.Protobuf.dll
• Grpc.Core.Api.dll
• Grpc.Core.dll
• Grpc_csharp_ext.x64.dll

 and .NET System libraries 

• System.Runtime.CompilerServices.Unsafe
• System.Runtime.Remoting

The – Grpc_csharp_ext.x64.dll – is a runtime dll that is used by the Grpc.Core and it is necessary to integrate it to the project.  

There are two ways to integrate it correctly. Either you copy it into the build folder or it is added to the project as an "existing item".

Add -> Existing item… (Shift + Alt + A)  

When added, please set the property “Copy to Output Directory” to “Copy always”:

All the dlls are stored in  EPLAN Platform  BIN  folder. Below are examples how to use it. 

EPLAN Remoting overview

EPLAN Remoting allows you to execute actions and some P8 operations in the remote way.
To open a new session, you have to connect your client to one of the existing P8 instance (the gRPC server that is embedded inside it).
The server could run locally or remotely.

After that, you can run P8 actions synchronously or asynchronously.
You can also pass or get parameters using action contex.
Finally, to close your remote session, you have to disconnect.

Below examples show how to use EPLAN Remoting:

Getting installed local servers:

List<EplanServerData> oInstalledEplanVersions = new List<EplanServerData>();
oClient.GetInstalledEplanVersionsOnLocalMachine(out oInstalledEplanVersions);
foreach (EplanServerData oVersion in oInstalledEplanVersions)
   Console.WriteLine(oVersion.EplanVariant + "," + oVersion.EplanVersion + "," + (oVersion.Is64Bit ? "64" : "32");

Listing servers on a local machine:

List<EplanServerData> oActiveEplanVersions = new List<EplanServerData>();
oClient.GetActiveEplanServersOnLocalMachine(out oActiveEplanVersions);
foreach (EplanServerData oVersion in oActiveEplanVersions)
   Console.WriteLine(oVersion.EplanVariant + "," + oVersion.EplanVersion + "," + oVersion.ServerPort);

Start an EPLAN instance locally from a client:

List<EplanServerData> oInstalledEplanVersions = new List<EplanServerData>();
oClient.GetInstalledEplanVersionsOnLocalMachine(out oInstalledEplanVersions);
EplanServerData oConnected = oClient.StartEplan(oInstalledEplanVersions[0].EplanPath);

To make sure that the EPLAN server was started, please check the registry key  HKEY_CURRENT_USER\Software\EPLAN\RemoteServer\<port_number>. 

Establishing a connection with the localhost:

EplanRemoteClient oClient = new EplanRemoteClient();
bool bConnected = oClient.Connect("localhost", "49155");   // Default port for EPLAN instance is 49155

Establishing a connection with a remote server:

EplanRemoteClient oClient = new EplanRemoteClient();
bool bConnected = oClient.Connect("remote_server", "49155", new TimeSpan(0, 0, 0, 5));   // Wait 5 seconds                                                

Calling an action:

bool oResp = oClient.ExecuteAction("XPartsManagementStart");

Calling an action in an asynchronous mode:

oClient.SynchronousMode = false;
oClient.ResponseArrivedFromEplanServer += onCallbackArrivedFromEplan;
oClient.ExecuteAction("XPartsManagementStart");

In this case, the program starts an action and continues running. onCallbackArrivedFromEplan method is called after action finished. 

Calling an action in synchronous mode:

This example shows how to get input from a user using context:

oClient.SynchronousMode = true;
CallingContext oCallingContext = new CallingContext();
oClient.ExecuteAction("XPamSelectPart", ref oCallingContext);

In this case, the program waits until the action execution is finished.

Making a selection:

StringCollection oObjects = new StringCollection();
oObjects.Add(@"17/688");
EplanResponse oResponse = oClient.SelectEplanObjects(@"$(MD_PROJECTS)\EPLAN_Sample_Project.elk", oObjects, true);

Disconnection:

oClient.Disconnect();

It is important to close the connection when operations are finished.