Rpc client programming

Content

• Public API
  • RpcClient - Exposes low level synchronous/asynchronous request/notification methods.
  • DynamicRpcProxy - Implements RPC proxy via DynamicObject.
  • RpcClientConfiguration - Configuration API to tweak client side behavior.
• Extension API/SPI
  • ClientTransportManager
  • ClientTransport
  • ClientRequestContext
  • ClientResponseContext

Public API

There are APIs which are used by applications.

RpcClient

RpcClient exposes low level synchronous/asynchronus request/notification methods. Each method takes target method name and arguments (as parameterized MessagePackObject array). Call corresponds to request message and Notify notification message respectedly.

Synchronous Methods

Method without any prefix/suffix is synchronous API. Behind scenes, these are wrapper for asynchronous API, these call asynchronous one and wait for completion. As you can see, these are convinient methods for casual use.

Asynchronous Methods

There are two types of asynchronous methods -- APM based methods (with prefix "Begin"/"End") and TPL based methods (with suffix "Async"). You can select each of them as following:

• If you want to use async/await feature, use -Async methods. This option is prefered .NET 4.5 or later.
• If you avoid AggregateException handling, use Begin/End- methods.
• Otherwise, use -Async methods.

DynamicRpcProxy

DynamicRpcProxy is casual entry point for RpcClient. The invocation of proxy is interpreted as Call methods with dynamic method name as methodName argument. When method name is started with Begin or End, or ended with Async, BeginCall, EndCall, and CallAsync is invoked respectedly.

Example:

`DynamicRpcProxy` call	Underlying `RpcClient` call
Foo(a, b, ...)	Call("Foo", a, b, ...)
BeginFoo(a, b, asyncCallback, state)	BeginCall("Foo", new MessagePackObject[]{ a, b, ... }, asyncCallback, state)
EndFoo(asyncResult)	EndCall(asyncResult)
FooAsync(a, b, ..., state)	CallAsync("Foo", new MessagePackObject[]{ a, b, ... }, state)
Begin(a, b, ...)	Call("Begin", a, b, ...)
End(asyncResult)	(Exception because `IAsyncResult` cannot be converted to `MessagePackObject`)
Async(a, b, ...)	Call("Async", a, b, ...)

Is There StaticRpcProxy?

No, it is reserved for generated proxy from the IDL.

RpcClientConfiguration

RpcClientConfiguration represents configuration settings, that is this is Configuration API. If your application requires file based configuration, build RpcClientConfiguration using your configuration settings (such as custom ConfigurationSection).

You can also set providers for custom Dispatcher, ServiceTypeLocator, and ServerTransportManager on the configuration.

Extension API/SPI

If you want to customize RPC, you can use following APIs (and/or SPIs).

ClientTransportManager

ClientTransportManager manages ClientTransport lifetime. For connection oriented protocol, it handles asynchronous connect operation. Implement it if you want to implement custom transport such as additional transport protocol support. You also must implement own ClientTransport.

ClientTransport

ClientTransport represents transport session between client and server on client side. The base class implements following:

• Asynchronous response callback handling.
• Serialization/deserialization.
• Invalid (corrupt) response handling.
• Orphan message handling (which contains unknown message ID).
• Exception translation.

Implement it if you want to implement custom transport such as additional transport protocol support. You also must implement own ClientTransportManager.

ClientRequestContext/ClientResponseContext

ClientRequestContext and ClientResponseContext encapselates context information of communication. Modifying from custom transports or filters is not supported.

Custom transports use its internal data via SocketContext property which returns SocketAsyncEventArgs.