Chapter 5. Using the API

This chapter explains how to use the AMQ .NET API to perform common messaging tasks.

5.1. Network connections

5.1.1. Creating outgoing connections

This section describes the standard format of the Connection URI string used to connect to an AMQP remote peer. 

 scheme = ( "amqp" | "amqps" )
 host = ( <fully qualified domain name> | <hostname> | <numeric IP address> )

 URI = scheme "://" [user ":" [password] "@"] host [":" port]
  • scheme amqp - connection uses TCP transport and sets the default port to 5672.
  • scheme amqps - connection uses SSL/TLS transport and sets the default port to 5671.
  • user - optional connection authentication user name. If the user name is present then the client initiates an AMQP SASL user credential exchange during connection startup.
  • password - optional connection authentication password.
  • host - network host to which the connection is directed.
  • port - optional network port to which the connection is directed. The default port value is determined by the AMQP transport scheme.

Connection URI Examples 

amqp://127.0.0.1
amqp://amqpserver.example.com:5672
amqps://joe:somepassword@bigbank.com
amqps://sue:secret@test.example.com:21000

5.2. Security

5.2.1. Configuring SASL authentication

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.

By default the client supports EXTERNAL, PLAIN, and ANONYMOUS SASL mechanisms.

5.2.2. Configuring an SSL/TLS transport

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.

Note

TLS Server Name Indication (SNI) is handled automatically by the client library. However, SNI is signaled only for addresses that use the amqps transport scheme where the host is a fully qualified domain name or a host name. SNI is not signaled when the host is a numeric IP address.

5.3. Logging

Logging is important in troubleshooting and debugging. By default logging is turned off. To enable logging a user must set a logging level and provide a delegate function to receive the log messages.

5.3.1. Setting the log output level

The library emits log traces at different levels:

  • Error
  • Warning
  • Information
  • Verbose

The lowest log level, Error, will trace only error events and produce 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

5.3.2. Enabling protocol logging

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

Tracing at one of the other log levels must be ORed with Frame 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.

Example: Logging delegate

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

5.4. More information

For more information, see the API reference.