Client class for Simple DUT Remote. More...

Public Member Functions
	RpcClient (string serverAddress, int serverPort, int timeout=5000)
	Create a new RPC client. More...

bool	Run (string command, string args=null)
	Run a command on the remote machine, and return immediately. More...

string	RunJob (string command, string args=null, int pollingInterval=60, int timeout=0, int pollingDelay=60)
	Run a command on the remote machine, wait for completion, and return stdout and stderr. More...

Task< string >	RunJobAsync (string command, string args=null, int pollingInterval=60, int timeout=0, int pollingDelay=60, CancellationToken? cancellationToken=null)
	Runs a job on the remote machine without blocking, and return the result. More...

Task< string >	RunJobAsyncEx (string command, string args=null, int pollingInterval=60, int timeout=0, int pollingDelay=60, CancellationToken? cancellationToken=null)
	Runs a job on the remote machine without blocking, and return a json object with results. More...

int	StartJob (string command, string args=null)
	Start a job on the remote system. More...

int	StartJobWithNotification (string command, string args, Action< int > callback, IPAddress localIP=null)
	Start job, and call a provided callback function once it completes. More...

int	StartJobWithProgress (string command, string args, Action< string > progressCallback, Action< int > completionCallback, IPAddress localIP=null)
	Start job, and stream standard out from the called process to the client. More...

bool	CheckJobCompletion (int jobId)
	Determine if a job has finished executing. More...

Dictionary< long, bool >	GetAllJobs ()
	Return all jobs on the remote system. More...

string	GetJobResult (int jobId)
	Get the output from a completed job (stdout + stderr). More...

string	GetJobResultEx (int jobId)
	Get the output and additional information from a completed job. More...

bool	StopJob (int jobId)
	Stop a job and kill the underlying process on the remote machine. More...

long	Upload (string localPath, string remoteDirPath, bool overwrite=false, int portNumber=0)
	Upload a directory or file to the server. More...

Task< long >	UploadAsync (string localPath, string remoteDirPath, bool overwrite=false, int portNumber=0)
	Upload a file or folder to the server without blocking. More...

long	Download (string remotePath, string localDirPath, bool overwrite=false, int portNumber=0)
	Download a file or folder from the server. More...

Task< long >	DownloadAsync (string remotePath, string localDirPath, bool overwrite=false, int portNumber=0)
	Download a file or folder from the server without blocking. More...

bool	KillProcess (string processName)
	Kill a running process on the remote machine. More...

string	GetVersion ()
	Return the server's version number. More...

bool	GetHeartbeat ()
	Get a heartbeat from the server. More...

bool	GetIsRunningAsAdmin ()
	Return if the server process is running as an Administrator. More...

string	GetServerLocation ()
	Return the location of the SimpleRemote server library on the DUT. More...

bool	PluginLoad (string identifier, string className, string dllPath)
	Load a plugin on the server. More...

T	PluginCallMethod< T > (string identifier, string methodName, params object[] args)
	Call a method on a loaded plugin. More...

bool	PluginUnload (string identifier)
	Unload a loaded plugin class. More...

Static Public Member Functions
static IPEndPoint[]	GetAllServersOnSubnet (int broadcastPort=8001, IPAddress broadcastAddress=null, int timeToWait=5000, IPAddress localAdapterAddress=null)
	Get all systems running SimpleRemote on this subnet. More...

Properties
IPEndPoint	ServerEndpoint `[get]`
	Get the server's endpoint information for this client instance. More...

Detailed Description

Client class for Simple DUT Remote.

Once created, the RpcClient class enables consumers of this library to easily control a remote system running the associated server program.

Constructor & Destructor Documentation

◆ RpcClient()

SimpleDUTClientLibrary.RpcClient.RpcClient	(	string	serverAddress,
		int	serverPort,
		int	timeout = `5000`
	)

inline

Create a new RPC client.

Note that creating a client object does not connect to the server - it simply gathers all the required information for future connections.

Parameters

serverAddress	IP address or hostname of rpc server.
serverPort	Server port number.
timeout	Timeout (in ms) for all send and receive operations.

Exceptions

TimeoutException	Thown if unable to resolve hostname within 10 seconds.
SocketException	Thownn if DNS lookup fails

Member Function Documentation

◆ CheckJobCompletion()

bool SimpleDUTClientLibrary.RpcClient.CheckJobCompletion ( int jobId )

inline

Determine if a job has finished executing.

Parameters

jobId Job id provided by StartJob()

Returns: True if job is finished, false otherwise.

◆ Download()

long SimpleDUTClientLibrary.RpcClient.Download	(	string	remotePath,
		string	localDirPath,
		bool	overwrite = `false`,
		int	portNumber = `0`
	)

inline

Download a file or folder from the server.

Parameters

remotePath	Path to file or folder on server.
localDirPath	Path to write received file on local machine (should be a directory, regardless if receiving files).
overwrite	Indicates if a file should be overwritten, if it already exists.
portNumber	If provided, request the server use the specified port for the transfer.

Returns: Size (in bytes) of files downloaded.

◆ DownloadAsync()

Task<long> SimpleDUTClientLibrary.RpcClient.DownloadAsync	(	string	remotePath,
		string	localDirPath,
		bool	overwrite = `false`,
		int	portNumber = `0`
	)

inline

Download a file or folder from the server without blocking.

Parameters

remotePath	Path to file or folder on server.
localDirPath	Path to write received file on local machine (should be a directory, regardless if receiving a file).
overwrite	Indicates if a file should be overwritten, if it already exists.
portNumber	If provided, request the server use the specified port for the transfer.

Returns: Task, returns size of files downloaded (in bytes) once it completes.

◆ GetAllJobs()

Dictionary<long, bool> SimpleDUTClientLibrary.RpcClient.GetAllJobs ( )

inline

Return all jobs on the remote system.

Return all jobs that are either running, or are completed, but their output hasn't been read yet.

Returns: Dictionary containing job ids, and a bool indicating if the job has completed.

◆ GetAllServersOnSubnet()

static IPEndPoint [] SimpleDUTClientLibrary.RpcClient.GetAllServersOnSubnet	(	int	broadcastPort = `8001`,
		IPAddress	broadcastAddress = `null`,
		int	timeToWait = `5000`,
		IPAddress	localAdapterAddress = `null`
	)

inlinestatic

Get all systems running SimpleRemote on this subnet.

Send a UDP broadcast packet to the current network, and return an array of IPEndPoint objects, each containing the IPAddress and Port of a system running SimpleRemote.

Parameters

broadcastPort	Port to use for the UDP broadcast.
broadcastAddress	IP Address to use for the broadcast. Defaults to 255.255.255.255
timeToWait	Time to wait for all responses before returning (in milliseconds)
localAdapterAddress	IP Address of the local adapter to use for the broadcast. Only needed if you have multiple active network adapters on the system.

Returns: An array of IPEndPoints, one for each SimpleRemote server.

◆ GetHeartbeat()

bool SimpleDUTClientLibrary.RpcClient.GetHeartbeat ( )

inline

Get a heartbeat from the server.

Returns true if the server responded to the heartbeat command. Throws otherwise.

◆ GetIsRunningAsAdmin()

bool SimpleDUTClientLibrary.RpcClient.GetIsRunningAsAdmin ( )

inline

Return if the server process is running as an Administrator.

This function only works if the server is running on a Windows system. It will throw a PlatformNotSupportedException if the server is running on Linux or MacOS.

Returns: True if server is running as an administrator. False otherwise.

◆ GetJobResult()

string SimpleDUTClientLibrary.RpcClient.GetJobResult ( int jobId )

inline

Get the output from a completed job (stdout + stderr).

Parameters

jobId Job id provided by StartJob()

Returns: Standard output and error from the job.

◆ GetJobResultEx()

string SimpleDUTClientLibrary.RpcClient.GetJobResultEx ( int jobId )

inline

Get the output and additional information from a completed job.

Parameters

jobId Job id provided by StartJob()

Returns: Json object containing job output and additional information. See SimpleDUTRemote.Functions.GetJobResultEx() for more information.

◆ GetServerLocation()

string SimpleDUTClientLibrary.RpcClient.GetServerLocation ( )

inline

Return the location of the SimpleRemote server library on the DUT.

Returns: Path to SimpleDUTRemote.DLL on Server

◆ GetVersion()

string SimpleDUTClientLibrary.RpcClient.GetVersion ( )

inline

Return the server's version number.

Returns

◆ KillProcess()

bool SimpleDUTClientLibrary.RpcClient.KillProcess ( string processName )

inline

Kill a running process on the remote machine.

Parameters

processName Name of the process, as identified by task manager's detailed view.

Returns: True on success. Throws otherwise.

◆ PluginCallMethod< T >()

T SimpleDUTClientLibrary.RpcClient.PluginCallMethod< T >	(	string	identifier,
		string	methodName,
		params object[]	args
	)

inline

Call a method on a loaded plugin.

Call an arbitrary method on a plugin-loaded class. Before calling this method, you must load the plugin and create an instance of a class with PluginLoad().

Note: If the called function returns void, set the return type to object.

Template Parameters

T	Return type of the called function.

Parameters

identifier	Identifier given to PluginLoad()
methodName	Method to call on the class.
args	Arguments to be fed to the called method.

Returns: Object of type T, returned from called function.

◆ PluginLoad()

bool SimpleDUTClientLibrary.RpcClient.PluginLoad	(	string	identifier,
		string	className,
		string	dllPath
	)

inline

Load a plugin on the server.

Load a class from a .NET (or .NET Core) DLL on the remote server. This allows you to call arbitrary functions from the DLL using the PluginCallMethod() function. Note that the plugin's framework (.NET or .NET Core) must match the framework of the running server. Additionally, the class object created must have a public, parameter-less constructor.

Parameters

identifier	A string to identify the DLL on subsequent method calls.
className	Full name of class to create (Namespace.Class).
dllPath	Path to DLL containing the given class.

Returns: Returns true if successful, throws otherwise.

◆ PluginUnload()

bool SimpleDUTClientLibrary.RpcClient.PluginUnload ( string identifier )

inline

Unload a loaded plugin class.

Given the same identifier used to instantiate a class with PluginLoad(), remove references to the loaded class on the server, allowing it to be garbage collected.

Note: this does not unload the assembly from the running server's app domain, it simply allows the spawned class to be garbage collected.

Parameters

identifier Identifier given to PluginLoad()

Returns: True if successful, throws otherwise.

◆ Run()

bool SimpleDUTClientLibrary.RpcClient.Run	(	string	command,
		string	args = `null`
	)

inline

Run a command on the remote machine, and return immediately.

Parameters

command	Path to command to run (bat/exe/ps1).
args	Arguments to pass to the command.

Returns: True if successful, throws exception otherwise.

◆ RunJob()

string SimpleDUTClientLibrary.RpcClient.RunJob	(	string	command,
		string	args = `null`,
		int	pollingInterval = `60`,
		int	timeout = `0`,
		int	pollingDelay = `60`
	)

inline

Run a command on the remote machine, wait for completion, and return stdout and stderr.

Starts a process, and returns standard output and standard error once the process completes. It internally uses the job system and callbacks to start a process. It then can automatically poll for completion, or wait for a callback. You can also call RunJobAsync() for a non-blocking, cancellable version of this function.

Parameters

command	Path to command to run (bat/exe/ps1).
args	Arguments to pass to the command.
pollingInterval	Polling frequency in seconds, or 0 to only rely on callbacks.
timeout	Time in seconds before throwing a TimeoutException, or 0 for no timeout.
pollingDelay	Delay until polling begins, or 0 to begin polling immediately. Ignored if the polling interval is 0.

Returns: String of standard output and standard error.

◆ RunJobAsync()

Task<string> SimpleDUTClientLibrary.RpcClient.RunJobAsync	(	string	command,
		string	args = `null`,
		int	pollingInterval = `60`,
		int	timeout = `0`,
		int	pollingDelay = `60`,
		CancellationToken?	cancellationToken = `null`
	)

inline

Runs a job on the remote machine without blocking, and return the result.

This command is similar to RunJob(), but returns a task instead of a string, and accepts cancellation tolkens. It can be considered a simpler way to launch processes on the remote without worrying about jobs, callbacks, or timeouts.

Parameters

command	Path to command to run (bat/exe/ps1).
args	Arguments to pass to the command.
pollingInterval	Polling frequency in seconds, or 0 to only rely on callbacks.
timeout	Time in seconds before throwing a TimeoutException, or 0 for no timeout.
pollingDelay	Delay until polling begins, or 0 to begin polling immediately. Ignored if the polling interval is 0.
cancellationToken	Optional cancellation token for the task. Can be used to cancel the job.

Returns: Task, populated with the stdout and stderr of the called process on completion.

◆ RunJobAsyncEx()

Task<string> SimpleDUTClientLibrary.RpcClient.RunJobAsyncEx	(	string	command,
		string	args = `null`,
		int	pollingInterval = `60`,
		int	timeout = `0`,
		int	pollingDelay = `60`,
		CancellationToken?	cancellationToken = `null`
	)

inline

Runs a job on the remote machine without blocking, and return a json object with results.

This command is similar to RunJobAsync(), but returns a task containing a json string instead of a string with the Job's output. The json string is the output of the server SimpleDUTRemote.Functions.GetJobResultEx() function, which contains both the output from the called process, as well as additional information, such as the exit code.

Parameters

command	Path to command to run (bat/exe/ps1).
args	Arguments to pass to the command.
pollingInterval	Polling frequency in seconds, or 0 to only rely on callbacks.
timeout	Time in seconds before throwing a TimeoutException, or 0 for no timeout.
pollingDelay	Delay until polling begins, or 0 to begin polling immediately. Ignored if the polling interval is 0.
cancellationToken	Optional cancellation token for the task. Can be used to cancel the job.

Returns: Task, populated with result of GetJobResultEx() on completion.

◆ StartJob()

int SimpleDUTClientLibrary.RpcClient.StartJob	(	string	command,
		string	args = `null`
	)

inline

Start a job on the remote system.

Starts a program on the remote system, and returns a job id, which can be used to track the program and retrieve its output. RunJob() and RunJobAsync() provide a higher level interface to the job system.

Parameters

command	Path to command to run (bat/exe/ps1).
args	Arguments to pass to the command.

Returns: Job id for the newly created job.

◆ StartJobWithNotification()

int SimpleDUTClientLibrary.RpcClient.StartJobWithNotification	(	string	command,
		string	args,
		Action< int >	callback,
		IPAddress	localIP = `null`
	)

inline

Start job, and call a provided callback function once it completes.

Parameters

command	Path to command to run (bat/exe/ps1).
args	Arguments to pass to the command (use null or empty string for no args).
callback	Callback to run once job completes - the completed job number will be provided as a argument to the function.
localIP	Local IP address to use for inbound notification. If null, will let server determine this machine's address.

Returns: Job id for the newly created job.

◆ StartJobWithProgress()

int SimpleDUTClientLibrary.RpcClient.StartJobWithProgress	(	string	command,
		string	args,
		Action< string >	progressCallback,
		Action< int >	completionCallback,
		IPAddress	localIP = `null`
	)

inline

Start job, and stream standard out from the called process to the client.

You should call GetJobResult() on the completed job, even though there will be no output, to acknowledge to the server that you're done with the job and to release resources associated with it on the server.

Because this will result in both network and disk activity on the server, it is not recommended for use while performing power sensitive measurements.

Parameters

command	Path to command to run (bat/exe/ps1).
args	Arguments to pass to the command (use null or empty string for no args).
progressCallback	Callback to run whenever the called process emits a line of text. Emitted text will be an argument for the function.
completionCallback	Callback to run once job completes - the completed job number will be provided as a argument to the function.
localIP	Local IP address to use for inbound notification. If null, will let server determine this machine's address.

Returns: Job id for the newly created job.

◆ StopJob()

bool SimpleDUTClientLibrary.RpcClient.StopJob ( int jobId )

inline

Stop a job and kill the underlying process on the remote machine.

Parameters

jobId Job id provided by StartJob()

Returns: True on success. Throws otherwise.

◆ Upload()

long SimpleDUTClientLibrary.RpcClient.Upload	(	string	localPath,
		string	remoteDirPath,
		bool	overwrite = `false`,
		int	portNumber = `0`
	)

inline

Upload a directory or file to the server.

Warning for Powershell users: Powershell has two "current directories", there's the one you see on your terminal (what you see with cd/pwd), and the current directory of the Powershell process (where you started Powershell, likely your user profile). Unfortunately, when a C# DLL calls GetCurrentDirectory, it gets the process directory. If you try to upload a file, and you get an unexpected System.IO.DirectoryNotFoundException from the server, there's a good chance you've hit this. To resolve, either use forward slashes in your filenames, or explicitly set the process directory using [Environment]::CurrentDirectory = get-location.

See https://stackoverflow.com/questions/18862716/current-directory-from-a-dll-invoked-from-powershell-wrong for additional information.

Parameters

localPath	Path to the directory or file on this machine to send to the server.
remoteDirPath	Location on the server to write data (should be a directory, regardless if sending files).
overwrite	Indicates if the file should be overwritten on the server, if it already exists.
portNumber	If provided, request the server use the specified port for the transfer.

Returns: Size (in bytes) of files uploaded.

◆ UploadAsync()

Task<long> SimpleDUTClientLibrary.RpcClient.UploadAsync	(	string	localPath,
		string	remoteDirPath,
		bool	overwrite = `false`,
		int	portNumber = `0`
	)

inline

Upload a file or folder to the server without blocking.

Warning for Powershell users: Powershell has two "current directories", there's the one you see on your terminal (what you see with cd/pwd), and the current directory of the Powershell process (where you started Powershell, likely your user profile). Unfortunately, when a C# DLL calls GetCurrentDirectory, it gets the process directory. If you try to upload a file, and you get an unexpected System.IO.DirectoryNotFoundException from the server, there's a good chance you've hit this. To resolve, either use forward slashes in your filenames, or explicitly set the process directory using [Environment]::CurrentDirectory = get-location.

See https://stackoverflow.com/questions/18862716/current-directory-from-a-dll-invoked-from-powershell-wrong for additional information.

Parameters

localPath	Path to the file or folder on this machine to send to the server.
remoteDirPath	Location on the server to write the file or folder (should be a directory, regardless if sending files).
overwrite	Indicates if the file should be overwritten on the server, if it already exists.
portNumber	If provided, request the server use the specified port for the transfer.

Returns: Task, returns size (in bytes) of files uploaded once completed.

Property Documentation

◆ ServerEndpoint

IPEndPoint SimpleDUTClientLibrary.RpcClient.ServerEndpoint

get

Get the server's endpoint information for this client instance.

The documentation for this class was generated from the following file:

SimpleDUTClientLibrary/RpcClient.cs

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ RpcClient()

Member Function Documentation

◆ CheckJobCompletion()

◆ Download()

◆ DownloadAsync()

◆ GetAllJobs()

◆ GetAllServersOnSubnet()

◆ GetHeartbeat()

◆ GetIsRunningAsAdmin()

◆ GetJobResult()

◆ GetJobResultEx()

◆ GetServerLocation()

◆ GetVersion()

◆ KillProcess()

◆ PluginCallMethod< T >()

◆ PluginLoad()

◆ PluginUnload()

◆ Run()

◆ RunJob()

◆ RunJobAsync()

◆ RunJobAsyncEx()

◆ StartJob()

◆ StartJobWithNotification()

◆ StartJobWithProgress()

◆ StopJob()

◆ Upload()

◆ UploadAsync()

Property Documentation

◆ ServerEndpoint