- Generated by
1.13.2
|
Corelink C# Client Library
|
These documents are a work in progress, and we are trying to improve upon them on a daily basis. However, given our capacity and workload, there are bound to be things which get missed or checked in which should not have been checked in. If you find mistakes or documents wanting information, and you would like to help, you can do so in two ways
- Submit corrections. When you update anything and submit a PR, we will review it and if all looks good, it will be added. This is the fastest way that one can expect changes to be in.
- Submit tickets. If you are not sure how to make updates, or if you are short on time, please raise an issue in the repo, with details and what you think needs to be the expected text. We will try and update the literature to reflect any changes that we feel are merited. Note that this route will take longer than the first approach and there are no guarantees on the timeline.
The Corelink C# client is the official client library for using the Corelink low-latency messaging platform with C#.
The client functions as the interface layer between the applications and the server, and is where you create sender and receiver streams which communicate with the server and subsequently with other clients.
Corelink C# utilizes C#'s async/await and the Task Parallel Library (TPL) to perform non-blocking IO operations, allowing for sending and receiving messages to occur asynchronously. This ensures that the main application continues running without waiting for these operations to complete, improving the overall efficiency and responsiveness of the application.
The C# client is designed mainly around the principle that one can create many "channels", possibly to multiple corelink peer services. These channels could be for control, reporting, heart beating, synchronizing, or for data transfer. However, it is important to note that this distinction is largely logical and only pertinent to Corelink, not the networking layer.
It is important to realize that almost all that the Corelink client does is provide one with a framework to connect to the Corelink server with appropriate messaging and alleviating the need for one to use bare sockets. Hence, if done correctly, we can make this data transport largely independent of the underlying network protocol. Hence, we separate concerns. We first start by writing a base model for data exchange, and implement this interface for any specific protocol that we might have. All protocols which are meant to exchange data (this includes all IP based protocols) provide a uniform API.
It now allows us to support more data exchange protocols while still maintaining the same interface, mostly.
In the client, we coin the term channel to represent an entity which is responsible for doing some action. This could be moving data, driving control events, monitoring etc. Think of it similar to those of event streams, albeit much simpler. In the current context that channels are written, they are meant to have certain attributes and certain functions basis the protocols that they support for "doing" things e.g. message transfer.
We have now a solid bedrock to implement a client, which is essentially a group of channels, some utility functions and largely just Corelink logic put together, while being hooked in to the underlying networking interfaces and exposing only a lucid API, which might seem verbose at first, but is extremely expressive and intuitive.
Corelink client and server communicate in a largely RESTful fashion. The preferred way of connecting to Corelink control services is via a bidirectional secure WebSocket channel. Since .NET provides first-class WebSocket support via System.Net.WebSockets, this is the only supported control channel in the C# client.
With the client, one can manage multiple streams within the same client instance, all auto managed through the static CorelinkClient class.
As is with control channels, the client instance exposes the necessary API for sending and receiving data, fault reporting and graceful shutdowns. You can have multiple data channels which are not strictly tied to the control channel, however, we highly recommend not crossing auth tokens. It can result in server dropping your packets and giving you an impression that the client does not work.
The C# client supports three data channel protocols:
CorelinkDataXchgWSProtocolManager) — binary WebSocket frames, recommended for general useCorelinkDataXchgTcpProtocolManager) — raw TCP socket with framed packetsCorelinkDataXchgUdpProtocolManager) — UDP datagrams with framed packetsThe client exposes default configuration constants via CorelinkDefaults, which you are free to override in your application. Things like the default endpoint, control port, workspace, and protocol are defined there.
The C# client provides two levels of API:
Modern API (recommended): CorelinkClient exposes typed async methods such as ConnectAsync, SenderAsync, ReceiverAsync, SubscribeAsync, and the full suite of workspace, user, and group management functions. These return Task<JObject> or specific typed results and are designed to be composed with async/await.
Legacy API: A set of older methods (Connect, Request, CreateSender) are retained for backward compatibility. These wrap the modern API internally. New code should prefer the modern async methods.
For a complete example of the recommended integration pattern, see Example/MyAppClass.cs in the repository.
1.13.2