EasyCore.Pulsar 8.3.0

⚡ EasyCore.Pulsar

EasyCore.Pulsar is an Apache Pulsar infrastructure client for .NET 8. Built on Pulsar.Client, it provides DI registration, connect, topic publish/subscribe, and AcknowledgeAsync. It is not tied to IEvent / EventBus — use it standalone, or via the EasyCore.EventBus.Pulsar adapter.

🌍 Language

• Chinese: README.md
• English (this document)

📚 Table of Contents

• 1. Positioning
• 2. Relation to EventBus
• 3. Requirements
• 4. Installation
• 5. Quick Start
• 6. API Overview
• 7. Options (PulsarOptions)
• 8. FAQ
• 9. License

1. 🎯 Positioning

1.1 Design Principles

2. Relation to EventBus

┌─────────────────────────────┐
│  App code (any payload)     │
└──────────────┬──────────────┘
               │ IPulsarClient
               ▼
┌─────────────────────────────┐
│  EasyCore.Pulsar (this)     │  ← infrastructure client
└──────────────┬──────────────┘
               │ Pulsar.Client
               ▼
          Pulsar Cluster

┌─────────────────────────────┐
│ EasyCore.EventBus.Pulsar    │  ← adapter: IEvent / Handler
│   └── uses this client      │
└─────────────────────────────┘

3. ⚙ Requirements

4. 📥 Installation

dotnet add package EasyCore.Pulsar

5. ⚡ Quick Start

5️⃣.1️⃣ Register DI

using EasyCore.Pulsar;

builder.Services.AddEasyCorePulsar(o =>
{
    o.ServiceUrl = "pulsar://localhost:6650";
    o.TopicPrefix = "persistent://public/default/";
    o.AppName = "MyApp";
    // TLS / auth as needed:
    // o.UseTls = true;
    // o.TlsAllowInsecureConnection = false;
});

5️⃣.2️⃣ Publish

public sealed class InvoicePublisher
{
    private readonly IPulsarClient _client;

    public InvoicePublisher(IPulsarClient client) => _client = client;

    public async Task PublishAsync(string invoiceId, CancellationToken ct = default)
    {
        await _client.ConnectAsync(ct);

        var body = Encoding.UTF8.GetBytes($$"""{"invoiceId":"{{invoiceId}}"}""");
        var properties = new Dictionary<string, string>
        {
            ["EventType"] = "InvoiceCreated"
        };

        // Relative topic names are prefixed with TopicPrefix
        await _client.PublishAsync(
            topic: "invoice.created",
            body: body,
            properties: properties,
            cancellationToken: ct);
    }
}

5️⃣.3️⃣ Subscribe and Acknowledge

public sealed class InvoiceConsumer : BackgroundService
{
    private readonly IPulsarClient _client;

    public InvoiceConsumer(IPulsarClient client) => _client = client;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await _client.ConnectAsync(stoppingToken);

        await _client.SubscribeAsync(
            topics: new[] { "invoice.created" },
            handler: async (msg, ct) =>
            {
                var json = Encoding.UTF8.GetString(msg.Body.Span);
                // handle business…

                await _client.AcknowledgeAsync(msg.MessageId, ct);
            },
            cancellationToken: stoppingToken);
    }
}

PulsarDeliveredMessage fields: Topic, Body, Properties, MessageId.

6. 🧩 API Overview

IPulsarClient implements IAsyncDisposable — dispose on shutdown.

7. Options (PulsarOptions)

TLS / Authentication defaults come from PulsarClientConfiguration.Default.

8. ❓ FAQ

Q: This package vs EasyCore.EventBus.Pulsar?
A: Use the EventBus adapter for IEvent, handlers, and retries. Use this package for raw topic I/O.

Q: Must topics be fully qualified?
A: Relative names are fine (prefixed with TopicPrefix), or use full persistent://tenant/ns/topic.

Q: Must I call ConnectAsync first?
A: Yes — connect before publish or subscribe so the native client is built.

Q: How do I enable TLS?
A: Set UseTls = true and configure certificates, hostname verification, and Authentication as needed.

9. 📄 License

MIT — see the repository LICENSE, or the NuGet package metadata.

🤝 Contributing

Issues and PRs are welcome. After changing this package, verify EasyCore.EventBus.Pulsar and related demos.