IServerClient

interface thread-safe

namespace AR51.Net;

public interface IServerClient

The AR 51 server machines: see their status, launch or quit the AR 51 server program, and start or stop tracking. Use it through IAR51Client.Servers.

Each machine has two layers: the server program (launch, quit, force quit, relaunch) and tracking inside it (start, stop). Servers follows the system live; all members are safe to use from any thread.

How-to

This page is reference (facts only). For a walkthrough with a complete sample, see the Servers guide.

Properties

Property	Type	Access	Description
Servers	IReadOnlyList<ServerInfo>	get	The AR 51 server machines currently known, one entry per machine. Empty while not connected.

Method summary

Method	Returns
GetStatusAsync	Task<ServerStatus>
LaunchServerAsync	Task
QuitServerAsync	Task
ForceQuitServerAsync	Task
RelaunchServerAsync	Task
StartTrackingAsync	Task
StopTrackingAsync	Task

→ Full descriptions in Method details below.

Events

Standard .NET events (EventHandler<T>): subscribe with +=, unsubscribe with -=. They are raised on a background thread.

Event	Args	Raised when
ServersChanged	ServersChangedEventArgs	Raised when a machine appears in or disappears from Servers. Raised on a background thread.

Example

ar51.Servers.ServersChanged += (_, e) =>
{
    foreach (ServerInfo server in e.Added) Console.WriteLine($"+ {server.Name}");
    foreach (ServerInfo server in e.Removed) Console.WriteLine($"- {server.Name}");
};

Method details

GetStatusAsync

method

Task<ServerStatus> GetStatusAsync(ServerInfo server, CancellationToken cancellationToken = default);

Gets whether the server program is running on a machine, and whether it is tracking.

Parameters

serverServerInfoThe machine, from Servers.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTask<ServerStatus>The machine's current status.

Throws

AR51ExceptionThe machine could not be reached.

Example

foreach (ServerInfo server in ar51.Servers.Servers)
{
    ServerStatus status = await ar51.Servers.GetStatusAsync(server);
    Console.WriteLine($"{server.Name}: server {status.Server}, tracking {status.Tracking}, version {status.Version ?? "-"}");
}

LaunchServerAsync

method

Task LaunchServerAsync(ServerInfo server, CancellationToken cancellationToken = default);

Launches the AR 51 server program on a machine. Does nothing if it is already running.

Parameters

serverServerInfoThe machine, from Servers.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the machine has accepted the request.

Throws

AR51ExceptionThe machine refused (AR51ErrorCode.Rejected, for example "Restart too soon": try again a few seconds later) or could not be reached.

Example

try
{
    await ar51.Servers.LaunchServerAsync(server);
}
catch (AR51Exception exception) when (exception.ErrorCode == AR51ErrorCode.Rejected)
{
    Console.WriteLine(exception.Message);   // e.g. "Restart too soon": try again a few seconds later
}

QuitServerAsync

method

Task QuitServerAsync(ServerInfo server, CancellationToken cancellationToken = default);

Quits the AR 51 server program on a machine, letting it shut down cleanly. Does nothing if it is not running.

Parameters

serverServerInfoThe machine, from Servers.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the machine has accepted the request.

Throws

AR51ExceptionThe machine refused or could not be reached.

Affects every app using the system

Tracking runs on the server, so quitting a machine's server program stops it for every app connected to the AR 51 system, not just yours.

ForceQuitServerAsync

method

Task ForceQuitServerAsync(ServerInfo server, CancellationToken cancellationToken = default);

Ends the AR 51 server program on a machine immediately, without letting it shut down cleanly. Use it when QuitServerAsync does not work.

Parameters

serverServerInfoThe machine, from Servers.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the machine has accepted the request.

Throws

AR51ExceptionThe machine refused or could not be reached.

Affects every app using the system

Ends the server program without a clean shutdown, for every app connected to the AR 51 system. Use it only when QuitServerAsync doesn't work.

RelaunchServerAsync

method

Task RelaunchServerAsync(ServerInfo server, CancellationToken cancellationToken = default);

Quits the AR 51 server program on a machine, waits a few seconds, and launches it again.

Parameters

serverServerInfoThe machine, from Servers.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the program has been launched again.

Throws

AR51ExceptionThe machine refused or could not be reached.

Affects every app using the system

Tracking stops for every app connected to the AR 51 system until the program is running again.

StartTrackingAsync

method

Task StartTrackingAsync(ServerInfo server, CancellationToken cancellationToken = default);

Starts tracking on a machine. The server program must be running.

Parameters

serverServerInfoThe machine, from Servers.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the machine has accepted the request.

Throws

AR51ExceptionThe machine refused or could not be reached.

StopTrackingAsync

method

Task StopTrackingAsync(ServerInfo server, CancellationToken cancellationToken = default);

Stops tracking on a machine. The server program keeps running.

Parameters

serverServerInfoThe machine, from Servers.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the machine has accepted the request.

Throws

AR51ExceptionThe machine refused or could not be reached.

Affects every app using the system

Stops tracking on that machine for every app connected to the AR 51 system, not just yours.

Related types

Small types used by this interface, documented here.

ServerInfo

record · sealed

public sealed record ServerInfo(string Name, string Host, int Port);

An AR 51 server machine.

Property	Type	Description
Name	string	The machine's host name.
Host	string	The machine's IP address.
Port	int	The port of the machine's control service.

ServerStatus

record · sealed

public sealed record ServerStatus(ServerState Server, TrackingState Tracking, int? ProcessId, TimeSpan? Uptime, string? Version);

The status of an AR 51 server machine.

Property	Type	Description
Server	ServerState	Whether the AR 51 server program is running.
Tracking	TrackingState	Whether the program is tracking.
ProcessId	int?	The program's process id, or null when it is not running.
Uptime	TimeSpan?	How long the program has been running, or null when it is not running.
Version	string?	The server program's version, for example "3.2.0.9", or null when the machine does not report it.

ServerState

enum

public enum ServerState

Whether the AR 51 server program is running on a machine.

Value	Meaning
Unknown = 0	The machine did not say.
NotRunning = 1	The program is not running.
Running = 2	The program is running.

TrackingState

enum

public enum TrackingState

Whether the AR 51 server program is tracking.

Value	Meaning
Unknown = 0	The machine did not say.
Idle = 1	Not tracking.
Running = 2	Tracking.

ServersChangedEventArgs

class · sealed

public sealed class ServersChangedEventArgs : EventArgs

Data for IServerClient.ServersChanged.

Property	Type	Access	Description
Added	IReadOnlyList<ServerInfo>	get	Machines that appeared.
Removed	IReadOnlyList<ServerInfo>	get	Machines that disappeared.
Servers	IReadOnlyList<ServerInfo>	get	Every known machine after the change.

Constructor

public ServersChangedEventArgs(IReadOnlyList<ServerInfo> added, IReadOnlyList<ServerInfo> removed, IReadOnlyList<ServerInfo> servers);

Creates the event data.

See also

• Servers guide — walkthrough with a complete, compiled sample
• Class index — every AR51.Net type
• Data conventions, threading and errors