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:email@example.com amqps://sue:firstname.lastname@example.org:21000
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.
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.
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:
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.