👁 Image
OutWit.Communication.Client 2.3.3

OutWit.Communication.Client

Base client library for the WitRPC framework, providing functionality to connect to WitRPC servers and create dynamic proxies for calling remote services over various transports.

Overview

OutWit.Communication.Client is the core client-side library in the WitRPC ecosystem. It enables your application to act as a WitRPC client that can connect to remote services hosted by a WitRPC server. This package provides the fundamental client logic, including managing the connection, sending requests, receiving responses, and generating proxy objects that implement your service interfaces on the client side. Using these proxies, you can call remote methods and handle server events as if they were happening locally.

Key capabilities of this client library include:

• Dynamic Service Proxies: The client produces a proxy for your service interface (e.g. IMyService) via client.GetService<IMyService>(). This proxy forwards your method calls to the server and raises server-sent events on the client, supporting a natural, object-oriented usage of remote services (no need to manually serialize calls).

• Multiple Service Interfaces: When the server hosts multiple service interfaces (using composite services), a single client connection can access all of them. Just call client.GetService<T>() with different interface types to get proxies for each service.

• Transport Agnostic: The client library works with any supported transport (Named Pipes, TCP, WebSocket, Memory-Mapped Files, REST, etc.). The actual transport is provided by a transport-specific package, but the client API remains the same. You simply configure the desired transport during setup (for example, using .WithTcp(...), .WithWebSocket(...), etc.) and the library handles the details.

• Serialization & Encryption: The client supports all WitRPC serialization options (JSON by default, or MessagePack/others) and can enable encryption and authentication to match the server's configuration. These are toggled via builder options like .WithJson(), .WithMessagePack(), .WithEncryption(), and .WithAccessToken("token") for providing credentials.

• Error Handling & Timeouts: You can specify timeouts for connection and calls. The framework will return error statuses or throw exceptions if calls fail or time out, making it easier to handle network issues. The ConnectAsync method allows you to gracefully attempt connections within a specified timeframe.

• Auto-Reconnection: The client supports automatic reconnection with configurable retry strategies using WithAutoReconnect().

• Retry Policies: Failed calls can be automatically retried using configurable retry policies with WithRetryPolicy().

Under the hood, OutWit.Communication.Client works with the core OutWit.Communication components to format requests and decode responses. In most cases, you will use this package by including a transport-specific client package which depends on it, rather than using OutWit.Communication.Client alone.

Installation

Install-Package OutWit.Communication.Client

Note: In practice, you will typically install a specific client transport package (such as OutWit.Communication.Client.Tcp, OutWit.Communication.Client.WebSocket, etc.) which will automatically include this base library. Choose a transport package that matches the server's transport. For example, if the server uses TCP, install OutWit.Communication.Client.Tcp in the client application.

Basic Usage

To use the WitRPC client, first ensure you have a matching server running (using the corresponding OutWit.Communication.Server.* package). In your client code, you build and connect a client as follows:

using OutWit.Communication.Client;
using OutWit.Communication.Client.Pipes; // example transport: Named Pipes
using OutWit.Communication.Serializers;
using OutWit.Communication.Client.Encryption;

var client = WitClientBuilder.Build(options =>
{
 // Configure the transport (Named Pipe in this example):
 options.WithNamedPipe("MyAppPipe");
 // Use JSON serialization and enable encryption to match the server:
 options.WithJson();
 options.WithEncryption();
 // If the server requires an access token for authorization:
 // options.WithAccessToken("SecureTokenValue");
});

bool connected = await client.ConnectAsync(TimeSpan.FromSeconds(5));
if (!connected)
{
 Console.Error.WriteLine("Unable to connect to the RPC server.");
 return;
}

// Obtain a proxy to the remote service interface
IMyService service = client.GetService<IMyService>();

// Now you can call methods on the service and subscribe to events as if it were local:
service.SomeMethod("Hello"); 
service.SomeEvent += data => Console.WriteLine($"Event from server: {data}");

In this example, we built a client to connect via a named pipe called "MyAppPipe". The server must also be configured to listen on "MyAppPipe" (using OutWit.Communication.Server.Pipes) for the connection to succeed. We enabled JSON serialization and encryption in the client to align with the server's settings. We also demonstrate calling a method SomeMethod on the service and subscribing to an event SomeEvent. The call to SomeMethod will be sent to the server's implementation, and any SomeEvent raised on the server will invoke our console WriteLine on the client side.

Transport Selection: The above used Named Pipes for illustration, but you would use the transport relevant to your scenario. For example, to connect via TCP: use options.WithTcp("server-address", port), or for WebSocket: options.WithWebSocket("ws://server:port/path"). Just ensure the server is using the corresponding server transport with matching parameters (pipe name, port number, URL path, etc.).

Dynamic Proxies: After connecting, calling client.GetService<T>() returns an object of interface T that acts as a live proxy to the server. You do not need to write any networking code: simply call methods on this proxy as you would on a local object. The WitRPC client takes care of packaging the call, sending it to the server, and unwrapping the response. If the server triggers an event, the proxy raises that event on the client side.

Tip: This base client library works behind the scenes. In a typical application, you will primarily interact with the builder (to configure transports/security) and the proxy object. The heavy lifting of managing sockets, threads, or pipe streams is handled internally by this library and the transport plugins.

Accessing Multiple Services

When the server hosts multiple service interfaces using composite services, a single client can access all of them:

// Server hosts IUserService, IOrderService, and INotificationService
var client = WitClientBuilder.Build(options =>
{
 options.WithTcp("localhost", 5000);
 options.WithJson();
 options.WithEncryption();
});

await client.ConnectAsync(TimeSpan.FromSeconds(5));

// Get proxies for different service interfaces
var userService = client.GetService<IUserService>();
var orderService = client.GetService<IOrderService>();
var notificationService = client.GetService<INotificationService>();

// Use each service
var user = userService.GetUser(userId);
var orders = orderService.GetOrdersForUser(userId);
notificationService.SendNotification(user.Email, "Your orders are ready!");

Transport Selection

The above used Named Pipes for illustration, but you would use the transport relevant to your scenario:

// TCP
options.WithTcp("server-address", port);

// WebSocket
options.WithWebSocket("ws://server:port/path");

// Named Pipes
options.WithNamedPipe("PipeName");

Just ensure the server is using the corresponding server transport with matching parameters (pipe name, port number, URL path, etc.).

Auto-Reconnection

Enable automatic reconnection for resilient connections:

var client = WitClientBuilder.Build(options =>
{
 options.WithTcp("localhost", 5000);
 options.WithJson();
 options.WithAutoReconnect(reconnect =>
 {
 reconnect.MaxAttempts = 5;
 reconnect.InitialDelay = TimeSpan.FromSeconds(1);
 reconnect.MaxDelay = TimeSpan.FromSeconds(30);
 });
});

Further Documentation

See the WitRPC documentation for advanced client usage, including using the source generator (OutWit.Common.Proxy.Generator) for compile-time proxy generation and debugging tips.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Attribution (optional)

If you use OutWit.Communication.Client in a product, a mention is appreciated (but not required), for example: "Powered by WitRPC (https://witrpc.io/)".

Trademark / Project name

"WitRPC" and the WitRPC logo are used to identify the official project by Dmitry Ratner.

You may:

• refer to the project name in a factual way (e.g., "built with WitRPC");
• use the name to indicate compatibility (e.g., "WitRPC-compatible").

You may not:

• use "WitRPC" as the name of a fork or a derived product in a way that implies it is the official project;
• use the WitRPC logo to promote forks or derived products without permission.