C# SDK

The Iggy SDK for C# is a modern, async-first client library for interacting with an Iggy message streaming server from your .NET applications. It supports TCP and HTTP transports. The package is available on NuGet and the source code lives on GitHub.

The SDK is built around the IIggyClient interface, which aggregates every feature (publishing, consuming, stream/topic management, users, offsets, consumer groups, and system operations). For the low-level per-call API and the full configuration reference, see the Guide. For the ergonomic, batteries-included producer/consumer abstractions, see the High-level SDK.

Installation

dotnet add package Apache.Iggy

Supported protocols

The SDK supports two transport protocols:

TCP — binary protocol for optimal performance and lower latency (recommended)
HTTP — RESTful JSON API for stateless operations

Some operations are TCP-only and throw FeatureUnavailableException on HTTP: joining/leaving a consumer group, GetMeAsync, and DeleteSegmentsAsync.

Creating a client

Create a client with IggyClientFactory.CreateClient, then call ConnectAsync:

using Apache.Iggy.Configuration;
using Apache.Iggy.Enums;
using Apache.Iggy.Factory;

var client = IggyClientFactory.CreateClient(new IggyClientConfigurator
{
    BaseAddress = "127.0.0.1:8090",
    Protocol = Protocol.Tcp
});

await client.ConnectAsync();
await client.LoginUserAsync("iggy", "iggy");

Optionally, provide an ILoggerFactory for diagnostics (defaults to NullLoggerFactory.Instance):

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("Apache.Iggy", LogLevel.Information)
        .AddConsole();
});

var client = IggyClientFactory.CreateClient(new IggyClientConfigurator
{
    BaseAddress = "127.0.0.1:8090",
    Protocol = Protocol.Tcp,
    LoggerFactory = loggerFactory
});

IggyClientConfigurator also exposes buffer sizes, TLS, automatic reconnection with exponential backoff, auto-login (so you can skip the explicit LoginUserAsync call), and client-side message encryption. See Client configuration for the full reference.

Quick start

These samples use the High-level SDK — the recommended way to build producers and consumers. For the equivalent low-level, per-call flow, see the Guide.

Producer

using System.Text;
using Apache.Iggy;
using Apache.Iggy.Configuration;
using Apache.Iggy.Enums;
using Apache.Iggy.Extensions;
using Apache.Iggy.Factory;
using Apache.Iggy.Messages;

var client = IggyClientFactory.CreateClient(new IggyClientConfigurator
{
    BaseAddress = "127.0.0.1:8090",
    Protocol = Protocol.Tcp
});

await client.ConnectAsync();
await client.LoginUserAsync("iggy", "iggy");

var publisher = client.CreatePublisherBuilder(
        Identifier.String("sample-stream"),
        Identifier.String("sample-topic"))
    .CreateStreamIfNotExists("sample-stream")
    .CreateTopicIfNotExists("sample-topic")
    .Build();

await publisher.InitAsync();

for (var i = 0; i < 10; i++)
{
    var payload = Encoding.UTF8.GetBytes($"message-{i}");
    await publisher.SendMessagesAsync(new List<Message> { new(Guid.NewGuid(), payload) });
}

await publisher.DisposeAsync();

Consumer

using System.Text;
using Apache.Iggy;
using Apache.Iggy.Configuration;
using Apache.Iggy.Consumers;
using Apache.Iggy.Enums;
using Apache.Iggy.Extensions;
using Apache.Iggy.Factory;
using Apache.Iggy.Kinds;

var client = IggyClientFactory.CreateClient(new IggyClientConfigurator
{
    BaseAddress = "127.0.0.1:8090",
    Protocol = Protocol.Tcp
});

await client.ConnectAsync();
await client.LoginUserAsync("iggy", "iggy");

var consumer = client.CreateConsumerBuilder(
        Identifier.String("sample-stream"),
        Identifier.String("sample-topic"),
        Consumer.New(1))
    .WithPollingStrategy(PollingStrategy.Next())
    .WithAutoCommitMode(AutoCommitMode.AfterReceive)
    .Build();

await consumer.InitAsync();

await foreach (var message in consumer.ReceiveAsync())
{
    var payload = Encoding.UTF8.GetString(message.Message.Payload);
    Console.WriteLine($"Offset {message.CurrentOffset}: {payload}");
}

ReceiveAsync polls indefinitely — pass a CancellationToken or break out of the loop to stop.

Next steps

Guide — client configuration reference and the full API surface: auth, streams, topics, partitions, publishing, consuming, offsets, consumer groups, system operations
High-level SDK — IggyPublisher / IggyConsumer with background sending, retries, auto-commit, typed (de)serialization, and pooled (rented) buffers for allocation-free hot paths
Examples — producer, consumer-group, and typed-message samples, plus links to runnable projects