KubeMQ.SDK.CSharp 3.0.0

KubeMQ .NET SDK

Description

KubeMQ is a Kubernetes-native messaging platform. This SDK provides a .NET client for publishing and consuming messages across all KubeMQ messaging patterns: Events (pub/sub), Events Store (persistent pub/sub), Queues (pull-based with acknowledgment), and RPC (Commands and Queries).

For the full API reference, see the API Documentation.

Table of Contents

• Installation
• Quick Start
  • Prerequisites
  • Send an Event
  • Receive Events
  • Expected Output
  • More Quick Starts
• Messaging Patterns
  • Events (Pub/Sub)
  • Events Store (Persistent Pub/Sub)
  • Queues
  • Commands (RPC)
  • Queries (RPC)
• Configuration
  • ASP.NET Core / Dependency Injection
• Error Handling
  • Retry Policy
• Troubleshooting
  • Connection refused
  • Authentication failed
  • More issues
• Server Compatibility
• Deprecation Policy
• Version Lifecycle
  • Support Policy
  • Upgrading
• Security
• Additional Resources
• Contributing
• License

Installation

dotnet add package KubeMQ.SDK.CSharp

Or via PackageReference:

<PackageReference Include="KubeMQ.SDK.CSharp" Version="3.*" />

Prerequisites:

• .NET 8.0 (LTS)
• A running KubeMQ server (≥3.0) (Docker quick start)

Note: SDK v3.x requires .NET 8.0 (LTS). For .NET Framework or older runtimes, use SDK v2.x (EOL — security patches only).

Quick Start

Prerequisites

• .NET 8.0 (LTS)
• KubeMQ server (≥3.0) running on localhost:50000

  docker run -d -p 50000:50000 kubemq/kubemq-community:latest
  

• Install the SDK: dotnet add package KubeMQ.SDK.CSharp

Send an Event

using KubeMQ.Sdk.Client;
using KubeMQ.Sdk.Events;
using System.Text;

await using var client = new KubeMQClient(new KubeMQClientOptions());
await client.ConnectAsync();

await client.SendEventAsync(new EventMessage
{
    Channel = "my-channel",
    Body = Encoding.UTF8.GetBytes("Hello, KubeMQ!")
});

Receive Events

Note: Start the receiver before the sender. Events are not persisted — only subscribers connected at publish time receive the message. For persistent delivery, use Events Store with EventStoreStartPosition.StartFromFirst.

using KubeMQ.Sdk.Client;
using KubeMQ.Sdk.Events;
using System.Text;

await using var client = new KubeMQClient(new KubeMQClientOptions());
await client.ConnectAsync();

await foreach (var msg in client.SubscribeToEventsAsync(
    new EventsSubscription { Channel = "my-channel" }))
{
    Console.WriteLine($"Received: {Encoding.UTF8.GetString(msg.Body.Span)}");
}

Expected Output

Received: Hello, KubeMQ!

More Quick Starts

• Queue Quick Start
• Command Quick Start
• Query Quick Start

Messaging Patterns

KubeMQ supports five messaging patterns. Choose based on your delivery and interaction requirements:

See the examples/ directory for runnable examples of each pattern.

Events (Pub/Sub)

Fire-and-forget messages broadcast to all subscribers on a channel. No persistence or delivery guarantee. Use for real-time notifications where occasional message loss is acceptable.

→ Events Examples

Events Store (Persistent Pub/Sub)

Persistent events stored by the server. Subscribers can replay from a sequence number, timestamp, or time delta. Use for audit trails and event sourcing.

→ Events Store Examples

Queues

Pull-based message delivery with explicit acknowledgment. Each message is processed by exactly one consumer. Supports delayed delivery, expiration, and dead letter queues.

→ Queue Examples

Commands (RPC)

Request/reply pattern where the sender expects confirmation that the action was executed. The responder returns a success/failure indicator with no response payload.

→ Command Examples

Queries (RPC)

Request/reply pattern where the sender expects a data response. Supports server-side caching with configurable TTL.

→ Query Examples

Configuration

var client = new KubeMQClient(new KubeMQClientOptions
{
    Address = "kubemq-server:50000",
    ClientId = "my-service",
    DefaultTimeout = TimeSpan.FromSeconds(10),
    Tls = new TlsOptions { Enabled = true, CaFile = "/certs/ca.pem" },
    Retry = new RetryPolicy { MaxRetries = 5 },
});

ASP.NET Core / Dependency Injection

builder.Services.AddKubeMQ(opts =>
{
    opts.Address = "kubemq-server:50000";
});

Or bind from configuration:

builder.Services.AddKubeMQ(builder.Configuration);

{
  "KubeMQ": {
    "Address": "kubemq-server:50000",
    "DefaultTimeout": "00:00:10"
  }
}

Error Handling

All SDK methods throw typed exceptions derived from KubeMQException. The exception hierarchy enables precise error handling:

try
{
    await client.SendEventAsync(new EventMessage
    {
        Channel = "events",
        Body = Encoding.UTF8.GetBytes("hello")
    });
}
catch (KubeMQTimeoutException ex)
{
    // Operation exceeded deadline — may succeed on retry
    Console.WriteLine($"Timeout: {ex.Message}");
}
catch (KubeMQAuthenticationException ex)
{
    // Invalid or expired credentials — do not retry
    Console.WriteLine($"Auth failed: {ex.Message}");
}
catch (KubeMQConnectionException ex)
{
    // Not connected — auto-reconnection in progress
    Console.WriteLine($"Connection lost: {ex.Message}");
}
catch (KubeMQException ex)
{
    // Catch-all for any SDK error
    Console.WriteLine($"Error [{ex.ErrorCode}]: {ex.Message}");
    Console.WriteLine($"Retryable: {ex.IsRetryable}");
}

Retry Policy

Operations are retried automatically for transient errors:

Disable retry:

var client = new KubeMQClient(new KubeMQClientOptions
{
    Retry = new RetryPolicy { Enabled = false }
});

Troubleshooting

Connection refused

Error: KubeMQConnectionException: Failed to connect to localhost:50000

Verify the KubeMQ server is running and accessible:

docker run -d --name kubemq -p 50000:50000 kubemq/kubemq-community:latest

Authentication failed

Error: KubeMQAuthenticationException: Authentication failed

Verify your token is valid and not expired. See the Authentication Guide.

More issues

See the full Troubleshooting Guide for solutions to 11+ common issues.

Server Compatibility

On ConnectAsync, the SDK pings the server and logs a warning if the server version is outside the tested range. The connection proceeds normally — no error is thrown.

For the full compatibility matrix including platform support, see COMPATIBILITY.md.

Deprecation Policy

When an API is deprecated in the KubeMQ C# SDK:

1. The API is annotated with [Obsolete("Use {replacement} instead. Will be removed in v{version}.")]
2. The deprecation is documented in the CHANGELOG
3. The deprecated API continues to function for at least 2 minor versions or 6 months (whichever is longer)
4. After the notice period, the API may be removed in a subsequent minor or major release

Version Lifecycle

Support Policy

• When a new major SDK version reaches GA, the previous major version receives security patches only for 12 months
• After the 12-month window, the previous version is marked End-of-Life and receives no further updates
• Bug fixes and new features are only added to the active major version
• Security patches for EOL versions are applied on a best-effort basis and limited to critical/high CVEs

Upgrading

See MIGRATION-v3.md for the v2 → v3 migration guide.

Security

See SECURITY.md for vulnerability reporting. The SDK supports TLS and mTLS connections — for configuration details, see How to Connect with TLS.

Additional Resources

• KubeMQ Documentation — Official KubeMQ documentation and guides
• Full Documentation Index — Complete SDK documentation index
• KubeMQ Concepts — Core KubeMQ messaging concepts
• SDK Feature Parity Matrix — Cross-SDK feature comparison
• CHANGELOG.md — Release history
• TROUBLESHOOTING.md — Common issues and solutions
• Examples — Runnable code examples for all patterns

Community & Support

• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions, ideas, and community help
• KubeMQ Slack — Real-time chat with the KubeMQ team and community

Contributing

See CONTRIBUTING.md for build instructions, code style, and PR requirements.

License

Apache License 2.0 — see LICENSE.