You can install the Pulsar C# client library either through the dotnet CLI or through the Visual Studio. This section describes how to install the Pulsar C# client library through the dotnet CLI. For information about how to install the Pulsar C# client library through the Visual Studio , see .

Install the .NET Core SDK, which provides the dotnet command-line tool. Starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads.

Procedures

To install the Pulsar C# client library, following these steps:

  1. Create a project.

    1. Create a folder for the project.

    2. Open a terminal window and switch to the new folder.

    3. Create the project using the following command.

    4. Use to test that the app has been created properly.

  2. Add the Newtonsoft.Json NuGet package.

    1. Use the following command to install the Newtonsoft.json package:

      1. dotnet add package Newtonsoft.Json

    2. After the command completes, open the .csproj file to see the added reference:

      1. <ItemGroup>
      2. <PackageReference Include="Newtonsoft.Json" Version="12.0.1" />
      3. </ItemGroup>

  3. Use the Newtonsoft.Json API in the app.

    1. Open the Program.cs file and add the following line at the top of the file:

      1. using Newtonsoft.Json;

    2. Add the following code before the class Program line:

      1. public class Account
      2. {
      3. public string Name { get; set; }
      4. public string Email { get; set; }
      5. public DateTime DOB { get; set; }
      6. }

    3. Replace the Main function with the following:

      1. static void Main(string[] args)
      2. {
      3.     Account account = new Account
      4.     {
      5.         Name = "John Doe",
      6.         Email = "john@nuget.org",
      7.         DOB = new DateTime(1980, 2, 20, 0, 0, 0, DateTimeKind.Utc),
      8.     };
      10.     string json = JsonConvert.SerializeObject(account, Formatting.Indented);
      11.     Console.WriteLine(json);

    4. Build and run the app by using the dotnet run command. The output should be the JSON representation of the Account object in the code:

      1. {
      2. "Name": "John Doe",
      3. "Email": "john@nuget.org",
      4. "DOB": "1980-02-20T00:00:00Z"
      5. }

Client

This section describes some configuration examples for the Pulsar C# client.

Create client

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

To create a Pulsar C# client by using the builder, you need to specify the following options:

Create producer

This section describes how to create a producer.

  • Create a producer by using the builder.

    1. var producer = client.NewProducer()
    2.                     .Topic("persistent://public/default/mytopic")
    3.                     .Create();

  • Create a producer without using the builder.

Create consumer

This section describes how to create a consumer.

  • Create a consumer by using the builder.

    1. var consumer = client.NewConsumer()
    2.                     .SubscriptionName("MySubscription")
    3.                     .Topic("persistent://public/default/mytopic")
    4.                     .Create();

  • Create a consumer without using the builder.

    2. var consumer = client.CreateConsumer(options);

This section describes how to create a reader.

  • Create a reader by using the builder.

    1. var reader = client.NewReader()
    2.                 .StartMessageId(MessageId.Earliest)
    3.                 .Topic("persistent://public/default/mytopic")
    4.                 .Create();

  • Create a reader without using the builder.

    1. var options = new ReaderOptions(MessageId.Earliest, "persistent://public/default/mytopic");
    2. var reader = client.CreateReader(options);

Configure encryption policies

The Pulsar C# client 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.

This example shows how to set the EnforceUnencrypted encryption policy.

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

Configure authentication

Currently, the Pulsar C# client supports the TLS (Transport Layer Security) and JWT (JSON Web Token) authentication.

If you have followed Authentication using TLS, you get a certificate and a key. To use them from the Pulsar C# client, follow these steps:

  1. Create an unencrypted and password-less pfx file.

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

  2. Use the admin.pfx file to create an X509Certificate2 and pass it to the Pulsar C# client.

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

A producer is a process that attaches to a topic and publishes messages to a Pulsar broker for processing. This section describes some configuration examples about the producer.

Send data

  1. var data = Encoding.UTF8.GetBytes("Hello World");
  2. await producer.Send(data);

Send messages with customized metadata

  • Send messages with customized metadata by using the builder.

  • Send messages with customized metadata without using the builder.

    1. var data = Encoding.UTF8.GetBytes("Hello World");
    2. var metadata = new MessageMetadata();
    3. metadata["SomeKey"] = "SomeValue";
    4. var messageId = await producer.Send(metadata, data));

A consumer is a process that attaches to a topic through a subscription and then receives messages. This section describes some configuration examples about the consumer.

Receive messages

This example shows how a consumer receives messages from a topic.

  1. await foreach (var message in consumer.Messages())
  2. {
  3.     Console.WriteLine("Received: " + Encoding.UTF8.GetString(message.Data.ToArray()));
  4. }

Messages can be acknowledged individually or cumulatively. For details about message acknowledgement, see acknowledgement.

  • Acknowledge messages individually.

    1. await foreach (var message in consumer.Messages())
    2.     Console.WriteLine("Received: " + Encoding.UTF8.GetString(message.Data.ToArray()));
    3. }

  • Acknowledge messages cumulatively.

    1. await consumer.AcknowledgeCumulative(message);

Unsubscribe from topics

This example shows how a consumer unsubscribes from a topic.

  1. await consumer.Unsubscribe();

Note

Reader

A reader is actually just a consumer without a cursor. This means that Pulsar does not keep track of your progress and there is no need to acknowledge messages.

This example shows how a reader receives messages.

  1. await foreach (var message in reader.Messages())
  2. {
  3.     Console.WriteLine("Received: " + Encoding.UTF8.GetString(message.Data.ToArray()));
  4. }

This section describes how to monitor the producer, consumer, and reader state.

Monitor producer

The following table lists states available for the producer.

This example shows how to monitor the producer state.

  1. private static async ValueTask Monitor(IProducer producer, CancellationToken cancellationToken)
  2. {
  3.     var state = ProducerState.Disconnected;
  5.     while (!cancellationToken.IsCancellationRequested)
  6.     {
  7.         state = await producer.StateChangedFrom(state, cancellationToken);
  9.         var stateMessage = state switch
  10.         {
  11.             ProducerState.Connected => $"The producer is connected",
  12.             ProducerState.Disconnected => $"The producer is disconnected",
  13.             ProducerState.Closed => $"The producer has closed",
  14.             ProducerState.Faulted => $"The producer has faulted",
  15.             _ => $"The producer has an unknown state '{state}'"
  16.         };
  18.         Console.WriteLine(stateMessage);
  20.         if (producer.IsFinalState(state))
  21.             return;
  22.     }
  23. }

Monitor consumer state

The following table lists states available for the consumer.

This example shows how to monitor the consumer state.

  1. private static async ValueTask Monitor(IConsumer consumer, CancellationToken cancellationToken)
  2. {
  3.     var state = ConsumerState.Disconnected;
  5.     while (!cancellationToken.IsCancellationRequested)
  6.     {
  7.         state = await consumer.StateChangedFrom(state, cancellationToken);
  9.         var stateMessage = state switch
  10.         {
  11.             ConsumerState.Active => "The consumer is active",
  12.             ConsumerState.Inactive => "The consumer is inactive",
  13.             ConsumerState.Disconnected => "The consumer is disconnected",
  14.             ConsumerState.Closed => "The consumer has closed",
  15.             ConsumerState.ReachedEndOfTopic => "The consumer has reached end of topic",
  16.             ConsumerState.Faulted => "The consumer has faulted",
  17.             _ => $"The consumer has an unknown state '{state}'"
  18.         };
  20.         Console.WriteLine(stateMessage);
  22.         if (consumer.IsFinalState(state))
  23.             return;

Monitor reader state

The following table lists states available for the reader.