Google Git
Sign in
apache / qpid-site / refs/heads/asf-site / . / input / releases / qpid-proton-dotnet-1.0.0-M10 / api / md_src_Proton_Client_docs_Configuration.html
blob: f998a5f3e6eec051d29c89caa48bfefb8d02a4b4 [file] [log] [blame]
<!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: Qpid proton-dotnet Imperative Client 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&amp;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&amp;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">Qpid proton-dotnet Imperative Client configuration </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This file details various configuration options for the Imperative API based .NET client. Each of the resources that allow configuration accept a configuration options object that encapsulates all configuration for that specific resource.</p>
<h1><a class="anchor" id="autotoc_md11"></a>
Client Options</h1>
<p>Before creating a new connection a Client object is created which accepts a ClientOptions object to configure it. </p><pre class="fragment"> ClientOptions clientOptions = new();
clientOptions.Id = "container-name";
IClient client = IClient.Create(clientOptions);
</pre><p> The following options are available for configuration when creating a new <b>Client</b> instance.</p>
<ul>
<li><b>clientOptions.Id</b> Allows configuration of the AMQP Container Id used by newly created Connections, if none is set the Client instance will create a unique Container Id that will be assigned to all new connections.</li>
</ul>
<h1><a class="anchor" id="autotoc_md12"></a>
Connection Configuration Options</h1>
<p>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.</p>
<div class="fragment"><div class="line">ConnectionOptions connectionOptions = new();</div>
<div class="line">connectionOptions.Username = &quot;user&quot;;</div>
<div class="line">connectionOptions.Password = &quot;pass&quot;;</div>
<div class="line">IConnection connection = client.Connect(serverHost, serverPort, connectionOptions);</div>
</div><!-- fragment --><p>The following options are available for configuration when creating a new <b>Connection</b>.</p>
<ul>
<li><b>connectionOptions.Username</b> User name value used to authenticate the connection</li>
<li><b>connectionOptions.Password</b> The password value used to authenticate the connection</li>
<li><b>connectionOptions.SslEnabled</b> A connection level convenience option that enables or disables the transport level SSL functionality. See the connection transport options for more details on SSL configuration, if nothing is configures the connection will attempt to configure the SSL transport using the standard system level configuration properties.</li>
<li><b>connectionOptions.CloseTimeout</b> Timeout value that controls how long the client connection waits on resource closure before returning. By default the client waits 60 seconds for a normal close completion event.</li>
<li><b>connectionOptions.SendTimeout</b> Timeout value that controls how long the client connection waits on completion of a synchronous message send before returning an error. By default the client will wait indefinitely for a send to complete.</li>
<li><b>connectionOptions.OpenTimeout</b> Timeout value that controls how long the client connection waits on the AMQP Open process to complete before returning with an error. By default the client waits 15 seconds for a connection to be established before failing.</li>
<li><b>connectionOptions.RequestTimeout</b> Timeout value that controls how long the client connection waits on completion of various synchronous interactions, such as initiating or retiring a transaction, before returning an error. Does not affect synchronous message sends. By default the client will wait indefinitely for a request to complete.</li>
<li><b>connectionOptions.DrainTimeout</b> Timeout value that controls how long the client connection waits on completion of a drain request for a Receiver link before failing that request with an error. By default the client waits 60 seconds for a normal link drained completion event.</li>
<li><b>connectionOptions.VirtualHost</b> The vhost to connect to. Used to populate the Sasl and Open hostname fields. Default is the main hostname from the hostname provided when opening the Connection.</li>
<li><b>connectionOptions.TraceFrames</b> Configure if the newly created connection should enabled AMQP frame tracing to the system output.</li>
</ul>
<h2><a class="anchor" id="autotoc_md13"></a>
Connection Transport Options</h2>
<p>The ConnectionOptions object exposes a set of configuration options for the underlying I/O transport layer known as the TransportOptions which allows for fine grained configuration of network level options.</p>
<div class="fragment"><div class="line">ConnectionOptions connectionOptions = new();</div>
<div class="line">connectionOptions.TransportOptions.TcpNoDelay = false;</div>
<div class="line">connectionOptions.Username = &quot;user&quot;;</div>
<div class="line">connectionOptions.Password = &quot;pass&quot;;</div>
<div class="line">IConnection connection = client.Connect(serverHost, serverPort, connectionOptions);</div>
</div><!-- fragment --><p>The following transport layer options are available for configuration when creating a new <b>Connection</b>.</p>
<ul>
<li><b>TransportOptions.SendBufferSize</b> default is 64k</li>
<li><b>TransportOptions.ReceiveBufferSize</b> default is 64k</li>
<li><b>TransportOptions.SoLinger</b> default is -1</li>
<li><b>TransportOptions.TcpNoDelay</b> default is true</li>
</ul>
<h2><a class="anchor" id="autotoc_md14"></a>
Connection SSL Options</h2>
<p>If an secure connection is desired the ConnectionOptions exposes another options type for configuring the client for that, the SslOptions.</p>
<div class="fragment"><div class="line">ConnectionOptions connectionOptions = new();</div>
<div class="line">connectionOptions.Username = &quot;user&quot;;</div>
<div class="line">connectionOptions.Password = &quot;pass&quot;;</div>
<div class="line">connectionOptions.SslOptions.SslEnabled = true;</div>
<div class="line">connectionOptions.SslOptions.VerifyHost = true;</div>
<div class="line">IConnection connection = client.Connect(serverHost, serverPort, connectionOptions);</div>
</div><!-- fragment --><p>The following SSL layer options are available for configuration when creating a new <b>Connection</b>.</p>
<ul>
<li><b>SslOptions.SslEnabled</b> Enables or disables the use of the SSL transport layer, default is false.</li>
<li><b>SslOptions.EnableCertificateRevocationChecks</b> Should Certificate revocation checks be enabled (defaults to false).</li>
<li><b>SslOptions.VerifyHost</b> Whether to verify that the hostname being connected to matches with the provided server certificate. Defaults to true.</li>
<li><b>SslOptions.ServerNameOverride</b> Value used to validate the common name (server name) provided in the server certificate, the default is to use the host name used on connect.</li>
</ul>
<h2><a class="anchor" id="autotoc_md15"></a>
Connection Automatic Reconnect Options</h2>
<p>When creating a new connection it is possible to configure that connection to perform automatic connection recovery.</p>
<div class="fragment"><div class="line">ConnectionOptions connectionOptions = new();</div>
<div class="line">connectionOptions.Username = &quot;user&quot;;</div>
<div class="line">connectionOptions.Password = &quot;pass&quot;;</div>
<div class="line">connectionOptions.ReconnectionOptions.ReconnectEnabled = true;</div>
<div class="line">connectionOptions.ReconnectionOptions.ReconnectDelay = 30_000;</div>
<div class="line">connectionOptions.ReconnectionOptions.AddReconnectLocation(hostname, port);</div>
<div class="line">IConnection connection = client.Connect(serverHost, serverPort, connectionOptions);</div>
</div><!-- fragment --><p>The following connection automatic reconnect options are available for configuration when creating a new <b>Connection</b>.</p>
<ul>
<li><b>ReconnectionOptions.ReconnectEnabled</b> enables connection level reconnect for the client, default is false.</li>
<li><b>ReconnectionOptions.ReconnectDelay</b> Controls the delay between successive reconnection attempts, defaults to 10 milliseconds. If the backoff option is not enabled this value remains constant.</li>
<li><b>ReconnectionOptions.MaxReconnectDelay</b> The maximum time that the client will wait before attempting a reconnect. This value is only used when the backoff feature is enabled to ensure that the delay doesn't not grow too large. Defaults to 30 seconds as the max time between connect attempts.</li>
<li><b>ReconnectionOptions.UseReconnectBackOff</b> Controls whether the time between reconnection attempts should grow based on a configured multiplier. This option defaults to true.</li>
<li><b>ReconnectionOptions.ReconnectBackOffMultiplier</b> The multiplier used to grow the reconnection delay value, defaults to 2.0d.</li>
<li><b>ReconnectionOptions.MaxReconnectAttempts</b> The number of reconnection attempts allowed before reporting the connection as failed to the client. The default is no limit or (-1).</li>
<li><b>ReconnectionOptions.MaxInitialConnectionAttempts</b> For a client that has never connected to a remote peer before this option control how many attempts are made to connect before reporting the connection as failed. The default is to use the value of maxReconnectAttempts.</li>
<li><b>ReconnectionOptions.WarnAfterReconnectAttempts</b> Controls how often the client will log a message indicating that failover reconnection is being attempted. The default is to log every 10 connection attempts.</li>
<li><b>ReconnectionOptions.AddReconnectHost</b> Allows additional remote peers to be configured for use when the original connection fails or cannot be established to the host provided in the <b>connect</b> call.</li>
</ul>
<h1><a class="anchor" id="autotoc_md16"></a>
Session Configuration Options</h1>
<p>When creating a new Session the <b>SessionOptions</b> object can be provided which allows some control over various behaviors of the session.</p>
<div class="fragment"><div class="line">SessionOptions sessionOptions = new();</div>
<div class="line">ISession session = connection.OpenSession(sessionOptions);</div>
</div><!-- fragment --><p>The following options are available for configuration when creating a new <b>Session</b>.</p>
<ul>
<li><b>sessionOptions.CloseTimeout</b> Timeout value that controls how long the client session waits on resource closure before returning. By default the client uses the matching connection level close timeout option value.</li>
<li><b>sessionOptions.SendTimeout</b> Timeout value that sets the Session level default send timeout which can control how long a Sender waits on completion of a synchronous message send before returning an error. By default the client uses the matching connection level send timeout option value.</li>
<li><b>sessionOptions.OpenTimeout</b> Timeout value that controls how long the client Session waits on the AMQP Open process to complete before returning with an error. By default the client uses the matching connection level close timeout option value.</li>
<li><b>sessionOptions.RequestTimeout</b> Timeout value that controls how long the client connection waits on completion of various synchronous interactions, such as initiating or retiring a transaction, before returning an error. Does not affect synchronous message sends. By default the client uses the matching connection level request timeout option value.</li>
<li><b>sessionOptions.DrainTimeout</b> Timeout value that controls how long the Receiver create by this Session waits on completion of a drain request before failing that request with an error. By default the client uses the matching connection level drain timeout option value.</li>
</ul>
<h1><a class="anchor" id="autotoc_md17"></a>
Sender Configuration Options</h1>
<p>When creating a new Sender the <b>SenderOptions</b> object can be provided which allows some control over various behaviors of the sender. </p><pre class="fragment"> SenderOptions senderOptions = new();
ISender sender = session.OpenSender("address", senderOptions);
</pre><p> The following options are available for configuration when creating a new <b>Sender</b>.</p>
<ul>
<li><b>SenderOptions.CloseTimeout</b> Timeout value that controls how long the client Sender waits on resource closure before returning. By default the client uses the matching session level close timeout option value.</li>
<li><b>SenderOptions.SendTimeout</b> Timeout value that sets the Sender default send timeout which can control how long a Sender waits on completion of a synchronous message send before returning an error. By default the client uses the matching session level send timeout option value.</li>
<li><b>SenderOptions.OpenTimeout</b> Timeout value that controls how long the client Sender waits on the AMQP Open process to complete before returning with an error. By default the client uses the matching session level close timeout option value.</li>
<li><b>SenderOptions.RequestTimeout</b> Timeout value that controls how long the client connection waits on completion of various synchronous interactions, such as initiating or retiring a transaction, before returning an error. Does not affect synchronous message sends. By default the client uses the matching session level request timeout option value.</li>
</ul>
<h1><a class="anchor" id="autotoc_md18"></a>
Receiver Configuration Options</h1>
<p>When creating a new Receiver the <b>ReceiverOptions</b> object can be provided which allows some control over various behaviors of the receiver. </p><pre class="fragment"> ReceiverOptions receiverOptions = new();
IReceiver receiver = session.OpenReceiver("address", receiverOptions);
</pre><p> The following options are available for configuration when creating a new <b>Receiver</b>.</p>
<ul>
<li><b>receiverOptions.CreditWindow</b> Configures the size of the credit window the Receiver will open with the remote which the Receiver will replenish automatically as incoming deliveries are read. The default value is 10, to disable and control credit manually this value should be set to zero.</li>
<li><b>receiverOptions.CloseTimeout</b> Timeout value that controls how long the <b>Receiver</b> waits on resource closure before returning. By default the client uses the matching session level close timeout option value.</li>
<li><b>receiverOptions.OpenTimeout</b> Timeout value that controls how long the <b>Receiver</b> waits on the AMQP open process to complete before returning with an error. By default the client uses the matching session level open timeout option value.</li>
<li><b>receiverOptions.RequestTimeout</b> Timeout value that controls how long the client Receiver waits on completion of various synchronous interactions, such settlement of a delivery, before returning an error. By default the client uses the matching session level request timeout option value.</li>
<li><b>receiverOptions.DrainTimeout</b> Timeout value that controls how long the Receiver link waits on completion of a drain request before failing that request with an error. By default the client uses the matching session level drain timeout option value.</li>
</ul>
<h1><a class="anchor" id="autotoc_md19"></a>
Stream Sender Configuration Options</h1>
<p>When creating a new Sender the <b>SenderOptions</b> object can be provided which allows some control over various behaviors of the sender.</p>
<div class="fragment"><div class="line">StreamSenderOptions streamSenderOptions = new();</div>
<div class="line">IStreamSender streamSender = connection.OpenStreamSender(&quot;address&quot;, streamSenderOptions);</div>
</div><!-- fragment --><p>The following options are available for configuration when creating a new <b>StreamSender</b>.</p>
<ul>
<li><b>streamSenderOptions.CloseTimeout</b> Timeout value that controls how long the <b>StreamSender</b> waits on resource closure before returning. By default the client uses the matching session level close timeout option value.</li>
<li><b>streamSenderOptions.SendTimeout</b> Timeout value that sets the Sender default send timeout which can control how long a Sender waits on completion of a synchronous message send before returning an error. By default the client uses the matching session level send timeout option value.</li>
<li><b>streamSenderOptions.OpenTimeout</b> Timeout value that controls how long the <b>StreamSender</b> waits on the AMQP Open process to complete before returning with an error. By default the client uses the matching session level close timeout option value.</li>
<li><b>streamSenderOptions.RequestTimeout</b> Timeout value that controls how long the <b>StreamSender</b> waits on completion of various synchronous interactions, such as initiating or retiring a transaction, before returning an error. Does not affect synchronous message sends. By default the client uses the matching session level request timeout option value.</li>
</ul>
<h1><a class="anchor" id="autotoc_md20"></a>
Stream Receiver Configuration Options</h1>
<p>When creating a new Receiver the <b>ReceiverOptions</b> object can be provided which allows some control over various behaviors of the receiver.</p>
<div class="fragment"><div class="line">StreamReceiverOptions streamReceiverOptions = new();</div>
<div class="line">IStreamReceiver streamReceiver = connection.OpenStreamReceiver(&quot;address&quot;, streamReceiverOptions);</div>
</div><!-- fragment --><p>The following options are available for configuration when creating a new <b>StreamReceiver</b>.</p>
<ul>
<li><b>streamReceiverOptions.CreditWindow</b> Configures the size of the credit window the Receiver will open with the remote which the Receiver will replenish automatically as incoming deliveries are read. The default value is 10, to disable and control credit manually this value should be set to zero.</li>
<li><b>streamReceiverOptions.CloseTimeout</b> Timeout value that controls how long the <b>StreamReceiver</b> waits on resource closure before returning. By default the client uses the matching session level close timeout option value.</li>
<li><b>streamReceiverOptions.OpenTimeout</b> Timeout value that controls how long the <b>StreamReceiver</b> waits on the AMQP Open process to complete before returning with an error. By default the client uses the matching session level close timeout option value.</li>
<li><b>streamReceiverOptions.RequestTimeout</b> Timeout value that controls how long the <b>StreamReceiver</b> waits on completion of various synchronous interactions, such settlement of a delivery, before returning an error. By default the client uses the matching session level request timeout option value.</li>
<li><b>streamReceiverOptions.DrainTimeout</b> Timeout value that controls how long the <b>StreamReceiver</b> link waits on completion of a drain request before failing that request with an error. By default the client uses the matching session level drain timeout option value. </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<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>