Using Qpid Proton DotNet

Red Hat build of Apache Qpid Proton DotNet supports the following industry-recognized standards and network protocols:

Refer to Red Hat AMQ Supported Configurations on the Red Hat Customer Portal for current information regarding Red Hat build of Apache Qpid Proton DotNet supported configurations.

This section introduces the core API entities and describes how they operate together.

Red Hat build of Apache Qpid Proton DotNet sends and receives Messages. Messages are transferred to Brokers via Senders and from Brokers using Receivers. Received Messages are wrapped in a Delivery which can be Accepted, Rejected or Released.

Senders and Receivers are created using Connections which are in turn created using Clients. Sessions are established over Connections.

The sudo command

In this document, sudo is used for any command that requires root privileges. Exercise caution when using sudo because any changes can affect the entire system. For more information about sudo, see Using the sudo command.

File paths

In this document, all file paths are valid for Linux, UNIX, and similar operating systems (for example, /home/andrea). On Microsoft Windows, you must use the equivalent Windows paths (for example, C:\Users\andrea).

Variable text

This document contains code blocks with variables that you must replace with values specific to your environment. Variable text is enclosed in arrow braces and styled as italic monospace. For example, in the following command, replace <project-dir> with the value for your environment:

$ cd <project-dir>

When you extract the contents of the .zip file, a directory named amq-dotnet-1.0.0 is created. This is the top-level directory of the installation and is referred to as <install-dir> throughout this document.

Using the dotnet CLI you can add a reference to the Red Hat build of Apache Qpid Proton DotNet client to your application which will also download release binaries from the Nuget gallery. The following command should be run (with the appropriate version updated) in the location where your project file is saved.

dotnet add package Apache.Qpid.Proton.Client --version 1.0.0

Following this command your csproj file should be updated to contain a reference to to the proton-dotnet client library and should look similar to the following example:

<ItemGroup>
  <PackageReference Include="Apache.Qpid.Proton.Client" Version="1.0.0" />
</ItemGroup>

Users can manually add this reference as well and use the dotnet restore command to fetch the artifacts from the Nuget gallery.

$ git clone https://github.com/apache/qpid-proton-dotnet.git

Change to the qpid-proton-dotnet directory and use the git checkout command to checkout the commit associated with this release:

$ cd qpid-proton-dotnet
$ git checkout 1.0.0

The resulting local directory is referred to as <source-dir> in this guide.

The Hello World example creates a connection to the broker, sends a message containing a greeting to the hello-world-example queue, and receives it back. On success, it prints the received message to the console.

Change to the <source-dir>/examples/Example.HelloWorld/ and use dotnet run to build and execute the program.

$ cd <source-dir>/examples/Example.HelloWorld/
$ dotnet run
Received message with body: Hello World

The Hello World example creates a connection to the broker, sends a message containing a greeting to the hello-world-example queue, and receives it back. On success, it prints the received message to the console.

This client program connects to a server using <serverHost> and <serverPort>, creates a sender for target <address>, sends 100 messages containing String and exits.

using System;
using Apache.Qpid.Proton.Client;                                                        

namespace Apache.Qpid.Proton.Examples.HelloWorld
{
   class Program
   {
      private static readonly int MessageCount = 100;                                   

      static void Main(string[] args)
      {
         string serverHost =
            Environment.GetEnvironmentVariable("HOST") ?? "localhost";                  

         int serverPort =
            Convert.ToInt32(Environment.GetEnvironmentVariable("PORT") ?? "5672");      

         string address =
            Environment.GetEnvironmentVariable("ADDRESS") ?? "send-receive-example";

         IClient client = IClient.Create();                                             

         ConnectionOptions options = new ConnectionOptions();                           

         options.User = Environment.GetEnvironmentVariable("USER");
         options.Password = Environment.GetEnvironmentVariable("PASSWORD");

         using IConnection connection = client.Connect(serverHost, serverPort, options);

         using ISender sender = connection.OpenSender(address);                         

         for (int i = 0; i < MessageCount; ++i)
         {
            IMessage<string> message =
                IMessage<string>.Create(string.Format("Hello World! [{0}]", i));        

            ITracker tracker = sender.Send(message);                                    

            tracker.AwaitSettlement();                                                  

            Console.WriteLine(string.Format("Sent message to {0}: {1}",
                sender.Address, message.Body));
         }
      }
   }
}

Running the example

To run the example program, compile it and execute it from the command line. For more information, see Chapter 3, Getting started.

<source-dir>\bin\Debug>Example.Send

This client program connects to a server using <connection-url>, creates a receiver for source <address>, and receives messages until it is terminated or it reaches <count> messages.

using System;
using Apache.Qpid.Proton.Client;                                                        

namespace Apache.Qpid.Proton.Examples.HelloWorld
{
   class Program
   {
      private static readonly int MessageCount = 100;                                   

      static void Main(string[] args)
      {
         string serverHost =
            Environment.GetEnvironmentVariable("HOST") ?? "localhost";                  

         int serverPort =
            Convert.ToInt32(Environment.GetEnvironmentVariable("PORT") ?? "5672");      

         string address =
            Environment.GetEnvironmentVariable("ADDRESS") ?? "send-receive-example";

         IClient client = IClient.Create();                                             

         ConnectionOptions options = new ConnectionOptions();                           

         options.User = Environment.GetEnvironmentVariable("USER");
         options.Password = Environment.GetEnvironmentVariable("PASSWORD");

         using IConnection connection = client.Connect(serverHost, serverPort, options);

         using IReceiver receiver = connection.OpenReceiver(address);                   

         for (int i = 0; i < MessageCount; ++i)
         {
            IDelivery delivery = receiver.Receive();                                    

            IMessage<object> received = delivery.Message();                             

            Console.WriteLine("Received message with body: " + received.Body);
         }
      }
   }
}

Running the example

To run the example program, compile it and execute it from the command line. For more information, see Chapter 3, Getting started.

<source-dir>\bin\Debug>Example.Receive

This section describes how to configure how to configure connections.

The ConnectionOptions object can be provided to a Client instance when creating a new connection and allows configuration of several different aspects of the resulting Connection instance.

ConnectionOptions can be passed in the connect method on IClient and are used to configure

ConnectionOptions connectionOptions = new ConnectionOptions();
connectionOptions.User = "user"
connectionOptions.Password = "password"
IConnection connection = client.Connect(serverHost, serverPort, connectionOptions);

For a definitive list of options refer to Connection Options

ConnectionOptions connectionOptions = new ConnectionOptions();
connectionOptions.TransportOptions.TcpNoDelay = false;
IConnection connection = client.Connect(serverHost, serverPort, connectionOptions);

When creating a new connection it is possible to configure that connection to perform automatic connection recovery.

ConnectionOptions connectionOptions = new ConnectionOptions();
connectionOptions.ReconnectOptions.ReconnectEnabled = true;
connectionOptions.ReconnectOptions.ReconnectDelay = 30_000;
connectionOptions.ReconnectOptions.AddReconnectLocation(<hostname>, <port>);
IConnection connection = client.Connect(serverHost, serverPort, connectionOptions);

For a definitive list of options refer to Reconnect and failover

Red Hat build of Apache Qpid Proton DotNet can authenticate connections with a user and password.

To specify the credentials used for authentication, set the Username and Password fields on the ConnectionOptions object

    ConnectionOptions connectionOptions = new();
    connectionOptions.User = "user";
    connectionOptions.Password = "pass";

Client connections to remote peers may exchange SASL user name and password credentials. The presence of the user field in the connection URI controls this exchange. If user is specified then SASL credentials are exchanged; if user is absent then the SASL credentials are not exchanged.

Various SASL mechanisms are supported, please see SASL Reference

Secure communication with servers is achieved using SSL/TLS. A client may be configured for SSL/TLS Handshake only or for SSL/TLS Handshake and client certificate authentication. See the Managing Certificates section for more information.

Some message servers support on-demand creation of queues and topics. When a sender or receiver is attached, the server uses the sender target address or the receiver source address to create a queue or topic with a name matching the address.

The message server typically defaults to creating either a queue (for one-to-one message delivery) or a topic (for one-to-many message delivery). The client can indicate which it prefers by setting the queue or topic capability on the source or target.

To select queue or topic semantics, follow these steps:

SenderOptions senderOptions = new SenderOptions();
senderOptions.TargetOptions.Capabilities = new String []{"queue"};
ISender sender = connection.OpenSender(address, senderOptions);

ReceiverOptions receiverOptions = new ReceiverOptions();
receiverOptions.SourceOptions.Capabilities = new String [] {"topic"};
using IReceiver receiver = connection.OpenReceiver(address, receiverOptions);

A durable subscription is a piece of state on the remote server representing a message receiver. Ordinarily, message receivers are discarded when a client closes. However, because durable subscriptions are persistent, clients can detach from them and then re-attach later. Any messages received while detached are available when the client re-attaches.

Durable subscriptions are uniquely identified by combining the client container ID and receiver name to form a subscription ID. These must have stable values so that the subscription can be recovered.

To create a durable subscription, follow these steps:

To detach from a subscription, close the receiver.

if you dont close the receiver then the durable subscription will remain.

A shared subscription is a piece of state on the remote server representing one or more message receivers. Because it is shared, multiple clients can consume from the same stream of messages.

The client configures a shared subscription by setting the shared capability on the receiver source.

Shared subscriptions are uniquely identified by combining the client container ID and receiver name to form a subscription ID. These must have stable values so that multiple client processes can locate the same subscription. If the global capability is set in addition to shared, the receiver name alone is used to identify the subscription.

To create a shared subscription, follow these steps:

To send a message, create a client, connection and a sender

IConnection connection = client.Connect(serverHost, serverPort, options);
SenderOptions senderOptions = new SenderOptions();
ISender sender = connection.OpenSender(address, senderOptions);
IMessage<string> message = IMessage<string>.Create("Hello World!"));
ITracker tracker = sender.Send(message);

For more information, see the Send example.

When the message is sent a Tracker is returned which can be used to track the message or settle it if not using auto settlement

tracker.AwaitSettlement();

tracker.Settle();

To receive a message, create a connection, client and receiver.

IConnection connection = client.Connect(serverHost, serverPort, options);
using IReceiver receiver = connection.OpenReceiver(address);
IDelivery delivery = receiver.Receive();
IMessage<object> received = delivery.Message();

The Receiver.Accept() call tells the remote peer that the message was received and processed.

For more information, see the Receive example.

The IDelivery object can be used to accept, reject modify the delivery.

 ----
 delivery.Accept()
 ----

 ----
 delivery.Reject()
 ----

 ----
 delivery.Release()
 ----

The library emits log traces at different levels:

The lowest log level, Error, traces only error events and produces the fewest log messages. A higher log level includes all the log levels below it and generates a larger volume of log messages.

// Enable Error logs only.
Trace.TraceLevel = TraceLevel.Error

// Enable Verbose logs. This includes logs at all log levels.
Trace.TraceLevel = TraceLevel.Verbose

The Log level Frame is handled differently. Setting trace level Frame enables tracing outputs for AMQP protocol headers and frames.

Logical OR must be used to get normal tracing output and AMQP frame tracing at the same time. For example

// Enable just AMQP frame tracing
Trace.TraceLevel = TraceLevel.Frame;

// Enable AMQP Frame logs, and Warning and Error logs
Trace.TraceLevel = TraceLevel.Frame | TraceLevel.Warning;

The following code writes AMQP frames to the console.

Trace.TraceLevel = TraceLevel.Frame;
Trace.TraceListener = (f, a) => Console.WriteLine(
        DateTime.Now.ToString("[hh:mm:ss.fff]") + " " + string.Format(f, a));

AMQP messages are composed using the AMQP type system. This common format is one of the reasons AMQP clients in different languages are able to interoperate with each other.

When sending messages, Red Hat build of Apache Qpid Proton DotNet automatically converts language-native types to AMQP-encoded data. When receiving messages, the reverse conversion takes place.

AMQP defines a standard mapping to the JMS messaging model. This section discusses the various aspects of that mapping. For more information, see the Red Hat build of Apache Qpid JMS Interoperability chapter.

JMS message types

Red Hat build of Apache Qpid Proton DotNet provides a single message type whose body type can vary. By contrast, the JMS API uses different message types to represent different kinds of data. The table below indicates how particular body types map to JMS message types.

For more explicit control of the resulting JMS message type, you can set the x-opt-jms-msg-type message annotation.

AMQ Broker is designed to interoperate with AMQP 1.0 clients. Check the following to ensure the broker is configured for AMQP messaging: