Setup Examples

Notes

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

1. 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.
2. 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.

PLEASE NOTE: Corelink can be set up in many ways, and according to your needs, the below examples may not apply.

We cannot provide setup instructions for every single potential application of Corelink, however we have provided an examples repository with some to help you get started.

Including Corelink in Your Project

The C# client library lives in the Core/ directory of the csharp/csharp/ project. There are two ways to consume it.

Option A: Project reference (recommended)

If your application is part of a .NET solution alongside the Corelink client, add a project reference:

<!-- In your application's .csproj -->
<ItemGroup>
  <ProjectReference Include="../path/to/corelink-client/csharp/csharp/csharp.csproj" />
</ItemGroup>

Or via the CLI:

dotnet add reference ../path/to/corelink-client/csharp/csharp/csharp.csproj

Option B: Copy source files

Copy the Core/ directory directly into your project and add the Newtonsoft.Json NuGet package:

dotnet add package Newtonsoft.Json --version 13.0.3

Then include the Core/*.cs files in your build. No additional configuration is needed.

Visual Studio Setup

1. Add reference: Right-click your project in Solution Explorer → Add → Project Reference → browse to csharp.csproj. Alternatively, right-click → Add → Existing Item and select the Core/*.cs files.
2. Add NuGet package: Right-click your project → Manage NuGet Packages → search for Newtonsoft.Json → install version 13.0.3 or later.
3. Target framework: Ensure your project targets .NET 8.0 or later. In project properties, set the target framework to net8.0.

JetBrains Rider / VS Code

The steps are the same as the dotnet CLI options above. Both IDEs pick up <ProjectReference> and NuGet packages declared in .csproj automatically when you open or reload the solution.

Using Corelink in Your Application

Namespaces

using Core;
using Newtonsoft.Json.Linq;

Step 1: Connect and authenticate

bool ok = await CorelinkClient.ConnectAsync(
    "corelink.hsrn.nyu.edu",
    20012,
    "username",
    "password");
 
if (!ok)
    throw new Exception("Failed to connect to Corelink server.");

Step 2: Register server-push callbacks (optional)

Set these up before issuing any stream requests so no notifications are missed.

// Generic catch-all for any server-initiated message
CorelinkClient.OnServerPush = (func, msg) =>
{
    Console.WriteLine($"[Server push] {func}: {msg}");
};
 
// Typed callbacks for specific events
CorelinkClient.OnUpdate = (receiverID, streamID, user, apps, type, meta) =>
{
    Console.WriteLine($"New sender available: {streamID} ({type})");
};
 
CorelinkClient.OnSubscriber = (senderID, receiverID, user, apps, meta) =>
{
    Console.WriteLine($"New subscriber: {receiverID}");
};
 
CorelinkClient.OnStale = streamID => Console.WriteLine($"Stream stale: {streamID}");
CorelinkClient.OnDropped = streamID => Console.WriteLine($"Stream dropped: {streamID}");

Step 3: List workspaces

string[] workspaces = await CorelinkClient.ListWorkspacesAsync();
foreach (var ws in workspaces)
    Console.WriteLine(ws);

Step 4: Create a sender stream

var senderResp = await CorelinkClient.SenderAsync(
    workspace: "MyWorkspace",
    type: "myType",
    proto: "ws",
    alert: true);
 
int senderStreamId = senderResp.Value<int>("streamID");
int senderDataPort = senderResp.Value<int>("port");

Then open a data channel WebSocket to the assigned port:

string dataUrl = $"wss://corelink.hsrn.nyu.edu:{senderDataPort}/";
var senderDataWs = new CorelinkDataXchgWSProtocolManager(new Uri(dataUrl));
await senderDataWs.Init(0);

Step 5: Create a receiver stream and subscribe

var receiverResp = await CorelinkClient.ReceiverAsync(
    workspace: "MyWorkspace",
    proto: "ws",
    types: new[] { "myType" },
    alert: true,
    echo: true);
 
int receiverStreamId = receiverResp.Value<int>("streamID");
int receiverDataPort = receiverResp.Value<int>("port");
 
// Subscribe to available senders
var streamList = receiverResp["streamList"] as JArray;
if (streamList?.Count > 0)
{
    var senderIds = streamList
        .Select(s => s["streamID"].Value<string>())
        .ToArray();
    await CorelinkClient.SubscribeAsync(receiverStreamId.ToString(), senderIds);
}

Step 6: Send data

All data is sent as binary frames using the Corelink packet format: [2B headerLen][2B dataLen][4B streamID][header JSON][payload]

var headers = new JObject { ["counter"] = 1 };
byte[] payload = System.Text.Encoding.UTF8.GetBytes("Hello, Corelink!");
 
await senderDataWs.SendFramedDataAsync(senderStreamId, payload, headers.ToString());

Step 7: Disconnect

await CorelinkClient.DisconnectAsync();

Full Lifecycle Example

For a complete example that ties all of the above together — including opening a receiver data channel, sending a registration ping, running a background receive loop, and properly tearing down — see Example/MyAppClass.cs in the repository.

cd csharp/csharp
dotnet run                                              # Unified mode: full sender+receiver lifecycle
dotnet run -- --username U --password P                # Override credentials
dotnet run sender                                       # Legacy sender only
dotnet run receiver w                                   # Legacy receiver (WebSocket)
dotnet run receiver t                                   # Legacy receiver (TCP)
dotnet run receiver u                                   # Legacy receiver (UDP)
dotnet run control                                      # Run all control function tests

Closing remarks

This concludes a guide on how you can include the Corelink C# client in your application. This is by no means an exhaustive all-inclusive guide. You are free to choose your own project structure as long as the basic requirements (.NET 8.0, Newtonsoft.Json) are met.