| <!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: Client Fault Tolerance Configuration</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">Client Fault Tolerance Configuration </div> </div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="textblock"><p>The proton-dotnet client supports configuration to enable a connection to be handle both reestablished after an interruption and handling not being able to initially connect to a remote peer.</p> |
| <h1><a class="anchor" id="autotoc_md37"></a> |
| Enabling Reconnection</h1> |
| <p>By default the client does not attempt to reconnect to the configured remote peer, this can be easily done though by toggling the appropriate configuration option as follows:</p> |
| <div class="fragment"><div class="line">ConnectionOptions connectionOpts = new();</div> |
| <div class="line">connectionOpts.ReconnectEnabled = true;</div> |
| </div><!-- fragment --><p>Once enabled the client will try indefinitely to connect and if disconnected to reconnect to the remote peer that was specified in the connection call that created the connection instance. Additional options exist to control how many attempts to connect or reconnect are performed before the client gives up and marks the connection as failed. An example of configuring reconnection attempt and delays is below, see the full <a class="el" href="md_src_Proton_Client_docs_Configuration.html">configuration</a> document for all the available options and a description of what each does.</p> |
| <div class="fragment"><div class="line">ConnectionOptions options = new();</div> |
| <div class="line">options.ReconnectOptions.ReconnectEnabled = true;</div> |
| <div class="line">options.ReconnectOptions.MaxReconnectAttempts = 5;</div> |
| <div class="line">options.ReconnectOptions.MaxInitialConnectionAttempts = 5;</div> |
| <div class="line">options.ReconnectOptions.ReconnectDelay = 10;</div> |
| </div><!-- fragment --><p>Additional remote locations can be added to the reconnection options to allow for reconnect to an alternative location should the host specified in the connect API be unavailable, these hosts will always be tried after the host specified in the connect API and will be tried in order until a new connection is established.</p> |
| <div class="fragment"><div class="line">ConnectionOptions options = new();</div> |
| <div class="line">options.ReconnectOptions.ReconnectEnabled = true;</div> |
| <div class="line">options.ReconnectOptions.AddReconnectLocation("host2", 5672);</div> |
| <div class="line">options.ReconnectOptions.AddReconnectLocation("host3", 5672);</div> |
| <div class="line">options.ReconnectOptions.AddReconnectLocation("host4", 5672);</div> |
| </div><!-- fragment --><h1><a class="anchor" id="autotoc_md38"></a> |
| Reconnection and Client behavior</h1> |
| <p>The client reconnect handling is transparent in most cases and application code need not be adjusted to handle special case scenarios. In some very special cases the application nay need to make some configuration changes depending on how the client is used which mostly involves choosing timeouts for actions such as send timeouts.</p> |
| <p>A few select client operations and their behaviors during connection interruption as documented below:</p> |
| <ul> |
| <li><b>In Flight Send</b> A message that was sent and a valid tracker instance was returned will throw exception from any of the tracker methods that operate or wait on send outcomes which indicate a failure as the client cannot be certain if the send completed or failed.</li> |
| <li><b>Send blocked on credit</b> A send that is blocked waiting on credit will continue to wait during a connection interruption and only be failed if the client reaches configured reconnect limits, or the configured send timeout is reached.</li> |
| <li><b>Active transactions</b> If the application begins a new transaction and the client connection is interrupted before the transaction is committed the transaction will be marked as invalid and any call to commit will throw an exception, a call to roll back will succeed.</li> |
| <li><b>Handling received messages</b> If the application received a delivery and attempts to accept it (or apply any other outcome) the disposition operation will fail indicating the disposition could not be applied.</li> |
| </ul> |
| <h1><a class="anchor" id="autotoc_md39"></a> |
| Reconnection event notifications</h1> |
| <p>An application can configure event handlers that will be notified for various events related to the reconnection handling of the proton-dotnet client. The events available for subscription consist of following types:</p> |
| <ul> |
| <li><b>Connected</b> The client succeeded in establishing an initial connection to a remote peer.</li> |
| <li><b>Interrupted</b> The client connection to a remote peer was broken it will now attempt to reconnect.</li> |
| <li><b>Reconnected</b> The client succeeded in establishing an new connection to remote peer after having been interrupted.</li> |
| <li><b>Disconnected</b> The client failed to establish a new connection and the configured attempt limit was reached (if set).</li> |
| </ul> |
| <p>To subscribe to one of the above events the application must set an event handler in the connection options instance for the desired event.</p> |
| <p>As an example the client can set a handler to called upon the first successful connection to a remote peer and the event would carry the host and port where the connection was established to in a ConnectionEvent object.</p> |
| <div class="fragment"><div class="line">ConnectionOptions options = new();</div> |
| <div class="line"> </div> |
| <div class="line">options.ConnectedHandler = (conn, location) => ... Your code here ... ;</div> |
| </div><!-- fragment --><p>Then to be notified when an active connection is interrupted a handler is set in the connection which will be called with an disconnection event that carries the host and port that the client was connected to and an exception that provides any available details on the reason for disconnection.</p> |
| <div class="fragment"><div class="line">ConnectionOptions options = new();</div> |
| <div class="line"> </div> |
| <div class="line">options.InterruptedHandler = (conn, location) => ... Your code here ... ;</div> |
| </div><!-- fragment --><p>To be notified when a connection that was previously interrupted is successfully able to reconnect to one of the configured remote peers the reconnection event can be used which will be notified on reconnect and provided a connection event object that carries the host and port that the client reconnected to:</p> |
| <div class="fragment"><div class="line">ConnectionOptions options = new();</div> |
| <div class="line"> </div> |
| <div class="line">options.ReconnectedHandler = (conn, location) => ... Your code here ... ;</div> |
| </div><!-- fragment --><p>To be notified when the client has given up on reconnection due to exceeding the configured reconnection attempt the application can set a handler on the disconnected event which will be given a disconnection event object that carries the host and port of the last location the client was successfully connected to and an exception object that provides any available details on the failure cause.</p> |
| <div class="fragment"><div class="line">ConnectionOptions options = new();</div> |
| <div class="line"> </div> |
| <div class="line">options.DisconnectedHandler = (conn, location) => ... Your code here ... ;</div> |
| </div><!-- fragment --> </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> |
