Skip to content

README.md

Latest commit

 

History

History
192 lines (130 loc) · 5.98 KB

README.md

File metadata and controls

192 lines (130 loc) · 5.98 KB
Raw

Ably Pub/Sub Dotnet Header NuGet version License

Ably Pub/Sub .NET SDK

Build any realtime experience using Ably’s Pub/Sub .NET SDK. Supported on all popular platforms and frameworks, including Unity and MAUI.

Ably Pub/Sub provides flexible APIs that deliver features such as pub-sub messaging, message history, presence, and push notifications. Utilizing Ably’s realtime messaging platform, applications benefit from its highly performant, reliable, and scalable infrastructure.

Find out more:

Getting started

Everything you need to get started with Ably:

Supported platforms

Platform Support
.NET Standard 2.0+
.NET 6.0+, .NET Core 2.0+
.NET Framework 4.6.2+
Mono 5.4+
Xamarin.Android 8.0+
Xamarin.iOS 10.14+
Xamarin.Mac 3.8+
Unity 2019.x+
MAUI .NET 6.0+

Important

SDK versions < 1.2.12 will be deprecated from November 1, 2025.

Installation

The SDK is available as a nuget package. To get started with your project, install the package from the Package Manager Console or the .NET CLI.

Package Manager Console:

PM> Install-Package ably.io

.NET CLI in your project directory:

dotnet add package ably.io

Device and server packages

Two companion packages provide entry points named for where your code runs. They are thin: the clients they return are the ones documented below, with the same API key, options and API surface.

Package Install when your code runs on Entry point
ably.io.pubsub.device An end-user device: mobile, desktop, browser or embedded app PubSubDevice.CreateClient(...)
ably.io.pubsub.server A server you run: ASP.NET, Azure, a worker or a console app PubSubServer.CreateRealtimeClient(...), PubSubServer.CreateHttpClient(...) 
dotnet add package ably.io.pubsub.server
using IO.Ably.PubSub.Server;

var realtime = PubSubServer.CreateRealtimeClient("<API_KEY>");
var rest = PubSubServer.CreateHttpClient("<API_KEY>");
using IO.Ably.PubSub.Device;

var realtime = PubSubDevice.CreateClient("<API_KEY>");

Neither package is required. Applications using AblyRealtime and AblyRest from ably.io directly continue to work unchanged.

MAUI configuration

When using Ably in a MAUI project, be aware of potential issues caused by assembly trimming, as ably-dotnet relies on the reflection API.

Add the following to your .csproj file to prevent trimming of the IO.Ably assembly:

<ItemGroup>
  <TrimmerRootAssembly Include="IO.Ably" />
</ItemGroup>

Usage

The following code connects to Ably's realtime messaging service, subscribes to a channel to receive messages, and publishes a test message to that same channel:

// Initialize Ably Realtime client
var realtime = new AblyRealtime("your-ably-api-key");

// Wait for connection to be established
realtime.Connection.On(ConnectionEvent.Connected, args =>
{
   Console.WriteLine("Connected to Ably");
});

// Get a reference to the 'test' channel
IRealtimeChannel channel = realtime.Channels.Get("test");

// Subscribe to all messages published to this channel
channel.Subscribe(message =>
{
   Console.WriteLine($"Received message: {message.Data}");
});

// Publish a test message to the channel
await channel.PublishAsync("test-event", "Hello World!");

Enable logging using a new class that implements ILoggerSink interface.

class CustomLogHandler : ILoggerSink
{
    public void LogEvent(LogLevel level, string message)
    {
        Console.WriteLine($"Handler LogLevel : {level}, Data :{message}");
    }
}

Update clientOptions for LogLevel and LogHandler.

clientOpts.LogLevel = LogLevel.Debug;
clientOpts.LogHandler = new CustomLogHandler();

Unity usage

  • Download latest ably.io.*.unitypackage from releases section and include it in the unity project.
  • For more information, check Unity README

Releases

The CHANGELOG.md contains details of the latest releases for this SDK. You can also view all Ably releases on changelog.ably.com.

Contributing

Read the CONTRIBUTING.md guidelines to contribute to Ably.

Support, feedback and troubleshooting

For help or technical support, visit Ably's support page or GitHub Issues for community-reported bugs and discussions.

Increasing transport send and receive buffers for .NET framework

In high-throughput scenarios, for example, sending messages >50KB, the default WebSocket buffer in the .NET Framework can cause instability or errors. This issue is discussed in GitHub issue #446.

To mitigate this, increase the WebSocket buffer size to the maximum allowed (64KB):

var maxBufferSize = 64 * 1024;

var options = new ClientOptions();
var websocketOptions = new MsWebSocketOptions
{
    SendBufferInBytes = maxBufferSize,
    ReceiveBufferInBytes = maxBufferSize
};

options.TransportFactory = new MsWebSocketTransport.TransportFactory(websocketOptions);

var realtime = new AblyRealtime(options);