| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=9"/> |
| <meta name="generator" content="Doxygen 1.9.1"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <title>Proton DotNet: Getting started with the Qpid proton-dotnet Client Library</title> |
| <link href="tabs.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="jquery.js"></script> |
| <script type="text/javascript" src="dynsections.js"></script> |
| <link href="search/search.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="search/searchdata.js"></script> |
| <script type="text/javascript" src="search/search.js"></script> |
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| </head> |
| <body> |
| <div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| <div id="titlearea"> |
| <table cellspacing="0" cellpadding="0"> |
| <tbody> |
| <tr style="height: 56px;"> |
| <td id="projectalign" style="padding-left: 0.5em;"> |
| <div id="projectname">Proton DotNet |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.9.1 --> |
| <script type="text/javascript"> |
| /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ |
| var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); |
| /* @license-end */ |
| </script> |
| <script type="text/javascript" src="menudata.js"></script> |
| <script type="text/javascript" src="menu.js"></script> |
| <script type="text/javascript"> |
| /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ |
| $(function() { |
| initMenu('',true,false,'search.php','Search'); |
| $(document).ready(function() { init_search(); }); |
| }); |
| /* @license-end */</script> |
| <div id="main-nav"></div> |
| <!-- window showing the filter options --> |
| <div id="MSearchSelectWindow" |
| onmouseover="return searchBox.OnSearchSelectShow()" |
| onmouseout="return searchBox.OnSearchSelectHide()" |
| onkeydown="return searchBox.OnSearchSelectKey(event)"> |
| </div> |
| |
| <!-- iframe showing the search results (closed by default) --> |
| <div id="MSearchResultsWindow"> |
| <iframe src="javascript:void(0)" frameborder="0" |
| name="MSearchResults" id="MSearchResults"> |
| </iframe> |
| </div> |
| |
| </div><!-- top --> |
| <div class="PageDoc"><div class="header"> |
| <div class="headertitle"> |
| <div class="title">Getting started with the Qpid proton-dotnet Client Library </div> </div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="textblock"><p>This client provides an imperative API for AMQP messaging applications</p> |
| <p>Below are some quick pointers you might find useful.</p> |
| <h1><a class="anchor" id="autotoc_md22"></a> |
| Adding the client to your .NET application</h1> |
| <p>Using the <code>dotnet</code> CLI you can add a reference to the 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 you project file is saved. </p><pre class="fragment">dotnet add package Apache.Qpid.Proton.Client --version 1.0.0-M9 |
| </pre><p> 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: </p><pre class="fragment"><ItemGroup> |
| <PackageReference Include="Apache.Qpid.Proton.Client" Version="1.0.0-M9" /> |
| </ItemGroup> |
| </pre><p> Users can manually add this reference as well and use the <code>dotnet restore</code> command to fetch the artifacts from the Nuget gallery.</p> |
| <h1><a class="anchor" id="autotoc_md23"></a> |
| Creating a connection</h1> |
| <p>The entry point for creating new connections with the proton-dotnet client is the Client type which provides a simple static factory method to create new instances.</p> |
| <div class="fragment"><div class="line">IClient container = IClient.Create();</div> |
| </div><!-- fragment --><p>The <code>IClient</code> instance serves as a container for connections created by your application and can be used to close all active connections and provides the option of adding configuration to set the AMQP container Id that will be set on connections created from a given client instance.</p> |
| <p>Once you have created a Client instance you can use that to create new connections which will be of type <code>IConnection</code>. The Client instance provides API for creating a connection to a given host and port as well as providing connection options that carry a large set of connection specific configuration elements to customize the behavior of your connection. The basic create API looks as follows:</p> |
| <div class="fragment"><div class="line">IConnection connection = container.Connect(remoteAddress, remotePort, new ConnectionOptions());</div> |
| </div><!-- fragment --><p>The above code provides host, port and connection options however you may omit the options and proceed using client defaults which will be suitable for many applications. From your connection instance you can then proceed to create sessions, senders and receivers that you can use in your application.</p> |
| <h2><a class="anchor" id="autotoc_md24"></a> |
| Sending a message</h2> |
| <p>Once you have a connection you can create senders that can be used to send messages to a remote peer on a specified address. The connection instance provides methods for creating senders and is used as follows:</p> |
| <div class="fragment"><div class="line">ISender sender = connection.OpenSender("address");</div> |
| </div><!-- fragment --><p>A message instance must be created before you can send it and the Message interface provides simple static factory methods for comon message types you might want to send, for this example we will create a message that carries text in an AmqpValue body section:</p> |
| <div class="fragment"><div class="line">IMessage<string> message = IMessage<string>.Create("Hello World");</div> |
| </div><!-- fragment --><p>Once you have the message that you want to send the previously created sender can be used as follows:</p> |
| <div class="fragment"><div class="line">ITracker tracker = sender.Send(message);</div> |
| </div><!-- fragment --><p>The Send method of a sender will attempt to send the specified message and if the connection is open and the send can be performed it will return a <code>ITracker</code> instance to provides API for checking if the remote has accepted the message or applied other AMQP outcomes to the sent message. The send method can block if the sender lacks credit to send at the time it is called, it will await credit from the remote and send the message once credit is granted.</p> |
| <h3><a class="anchor" id="autotoc_md25"></a> |
| Creating a message</h3> |
| <p>The application code can create a message to be sent by using static factory methods in the <code>IMessage</code> type that can later be sent using the <code>ISender</code> type. These factory methods accept a few types that map nicely into the standard AMQP message format body sections. A typical message creation example is shown below.</p> |
| <div class="fragment"><div class="line">IMessage<string> message = IMessage<string>.Create("Hello World");</div> |
| </div><!-- fragment --><p>The above code creates a new message object that carries a string value in the body of an AMQP message and it is carried inside an <code>AmqpValue</code> section. Other methods exist that wrap other types in the appropriate section types, a list of those is given below:</p> |
| <ul> |
| <li><b>IDictionary</b> The factory method creates a message with the Map value wrapped in an <code>AmqpValue</code> section.</li> |
| <li><b>IList</b> The factory method creates a message with the List value wrapped in an <code>AmqpSequence</code> section.</li> |
| <li><b>byte[]</b> The factory method creates a message with the byte array wrapped in an <code>Data</code> section.</li> |
| <li><b>Object</b> All other objects are assumed to be types that should be wrapped in an <code>AmqpValue</code> section.</li> |
| </ul> |
| <p>It is also possible to create an empty message and set a body and it will be wrapped in AMQP section types following the same rules as listed above. Advanced users should spend time reading the API documentation of the <code>IMessage</code> type to learn more.</p> |
| <h2><a class="anchor" id="autotoc_md26"></a> |
| Receiving a message</h2> |
| <p>To receive a message sent to the remote peer a <code>IReceiver</code> instance must be created that listens on a given address for new messages to arrive. The connection instance provides methods for creating receivers and is used as follows:</p> |
| <div class="fragment"><div class="line">IReceiver receiver = connection.OpenReceiver("address");</div> |
| </div><!-- fragment --><p>After creating the receiver the application can then call one of the available receive APIs to await the arrival of a message from a remote sender.</p> |
| <div class="fragment"><div class="line">IDelivery delivery = receiver.Receive();</div> |
| </div><!-- fragment --><p>By default receivers created from the client API have a credit window configured and will manage the outstanding credit with the remote for your application however if you have configured the client not to manage a credit window for you then your application will need to provide receiver credit before invoking the receive APIs.</p> |
| <div class="fragment"><div class="line">receiver.AddCredit(1);</div> |
| </div><!-- fragment --><p>Once a delivery arrives an <code>IDelivery</code> instance is returned which provides API to both access the delivered message and to provide a disposition to the remote indicating if the delivered message is accepted or was rejected for some reason etc. The message is obtained by calling the message API as follows:</p> |
| <div class="fragment"><div class="line">IMessage<object> received = delivery.Message();</div> |
| </div><!-- fragment --><p>Once the message is examined and processed the application can accept delivery by calling the accept method from the delivery object as follows:</p> |
| <div class="fragment"><div class="line">delivery.Accept();</div> |
| </div><!-- fragment --><p>Other settlement options exist in the delivery API which provide the application wil full access to the AMQP specification delivery outcomes for the received message.</p> |
| <h1><a class="anchor" id="autotoc_md27"></a> |
| Examples</h1> |
| <p>First build and install all the modules as detailed above (if running against a source checkout/release, rather than against released binaries) and then consult the README in the Examples directory. </p> |
| </div></div><!-- contents --> |
| </div><!-- PageDoc --> |
| <!-- start footer part --> |
| <hr class="footer"/><address class="footer"><small> |
| Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 |
| </small></address> |
| </body> |
| </html> |
