Client

Client

The first thing we need is a client and from the client, we can create consumers, producers and readers. Every client has its own connection pool, so consumers, producers and readers will share connections to Pulsar brokers. If, for performance reasons, we need a dedicated connection for a consumer/producer/reader to a broker, just create a client only for that consumer/producer/reader.

Creating a client

When creating a client, there are actually no required options:

var client = PulsarClient.Builder().Build();

The code above will create a client connection to "pulsar://localhost:6650" and will assume that "localhost" is a standalone cluster.

Using the builder, we can specify these two options:

• ServiceUrl - The service URL for the Pulsar cluster. The default is "pulsar://localhost:6650".
• RetryInterval - The time to wait before retrying an operation or a reconnect. The default is 3 seconds.

The client supports service discovery, so any broker can be the entry point.

TLS connection

DotPulsar supports four kinds of encryption policies:

• EnforceUnencrypted (always use unencrypted connections)
• EnforceEncrypted (always use encrypted connections)
• PreferUnencrypted (use unencrypted connections if possible)
• PreferEncrypted (use encrypted connections if possible)

var client = PulsarClient.Builder()
                         .ConnectionSecurity(EncryptionPolicy.EnforceEncrypted)
                         .Build();

If the encryption policy is not set explicitly, it will default to 'EnforceEncrypted' if the service url scheme is 'pulsar+ssl' and 'EnforceUnencrypted' if it's 'pulsar'.

When establishing an encrypted connection, we have some options regarding verification of the CA and certificate name:

var certificate = new X509Certificate2("ca.cert.pem");
var client = PulsarClient.Builder()
                         .TrustedCertificateAuthority(certificate) //If the CA is not trusted on the host, we can add it explicitly.
                         .VerifyCertificateAuthority(true) //Default is 'true'
                         .VerifyCertificateName(false)     //Default is 'false'
                         .Build();

Authentication

Apache Pulsar supports TLS, Athenz, Kerberos and JSON Web Token authentication. Currently, DotPulsar supports TLS and JSON Web Token authentication.

TLS authentication

If TLS authentication have been setup up following Authentication using TLS then we end up with a certificate and a key. If we want to use these from .NET/DotPulsar, then the easiest way is to create an unencrypted and passwordless pfx file.

openssl pkcs12 -export -keypbe NONE -certpbe NONE -out admin.pfx -inkey admin.key.pem -in admin.cert.pem -passout pass:

Use admin.pfx to create an X509Certificate2 and pass it to DotPulsar.

var clientCertificate = new X509Certificate2("admin.pfx");
var client = PulsarClient.Builder()
                         .AuthenticateUsingClientCertificate(clientCertificate)
                         .Build();

JSON Web Token authentication

There's really nothing to it:

var client = PulsarClient.Builder()
                         .AuthenticateUsingToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")
                         .Build();

Disposing the client

Just call await client.DisposeAsync(), but beware that all its consumers, producers and readers will also be disposed.