This is an automated email from the ASF dual-hosted git repository.
tabish pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/qpid-proton-dotnet.git
The following commit(s) were added to refs/heads/main by this push:
new 9904020 PROTON-2766 Add basic client usage guide to proton-client
9904020 is described below
commit 9904020961cf6659966a5ef1be63ed1a981a777b
Author: Timothy Bish <tabish...@gmail.com>
AuthorDate: Mon Sep 18 13:24:32 2023 -0400
PROTON-2766 Add basic client usage guide to proton-client
Adds a simple client overview to the proton client project.
---
src/Proton.Client/README.md | 105 +++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 103 insertions(+), 2 deletions(-)
diff --git a/src/Proton.Client/README.md b/src/Proton.Client/README.md
index 9c8c994..8762f65 100644
--- a/src/Proton.Client/README.md
+++ b/src/Proton.Client/README.md
@@ -2,7 +2,108 @@
==================================
Qpid Proton DotNet is a high-performance, lightweight AMQP Client that
provides an
-imperative API whic can be used in the widest range of messaging applications.
+imperative API which can be used in the widest range of messaging applications.
-Please see http://qpid.apache.org/proton for more information.
+## Adding the client to you .NET application
+============================================
+
+Using the 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.
+
+ dotnet add package Apache.Qpid.Proton.Client --version 1.0.0-M9
+
+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:
+
+ <ItemGroup>
+ <PackageReference Include="Apache.Qpid.Proton.Client" Version="1.0.0-M9" />
+ </ItemGroup>
+
+Users can manually add this reference as well and use the 'dotnet restore'
command to
+fetch the artifacts from the Nuget gallery.
+
+## Creating a connection
+========================
+
+The entry point for creating new connections with the proton-dotnet client is
the IClient
+type which provides a simple static factory method to create new instances.
+
+ IClient container = IClient.Create();
+
+The IClient 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.
+
+Once you have created a IClient instance you can use that to create new
connections which
+will be of type IConnection. The IClient instance provides API for creating a
connection
+to a given host and port as well as providing connection options object that
carry a large
+set of connection specific configuration elements to customize the behavior of
your connection.
+The basic create API looks as follows:
+
+ IConnection connection = container.Connect(remoteAddress, remotePort, new
ConnectionOptions());
+
+From you connection instance you can then proceed to create sessions, senders
and receivers that
+you can use in your application.
+
+### Sending a message
+
+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:
+
+ ISender sender = connection.OpenSender("address");
+
+A message instance must be created before you can send it and the IMessage
interface provides
+simple static factory methods for common message types you might want to send,
for this example
+we will create a message that carries text in an AmqpValue body section:
+ IMessage<string> message = IMessage<string>.Create("Hello World");
+
+Once you have the message that you want to send the previously created sender
can be used as
+follows:
+
+ ITracker tracker = sender.Send(message);
+
+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 ITracker instance to
provides API for
+checking if the remote has accepted the message or applied other AMQP outcomes
to the sent
+message.
+
+### Receiving a message
+
+To receive a message sent to the remote peer a Receiver 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:
+
+ IReceiver receiver = connection.OpenReceiver("address");
+
+After creating the receiver the application needs to provide credit to the
remote which allows
+for control of how many messages a remote can send to the receiver. We will
add a single credit
+here indicating to the remote that one message can be sent to this receiver:
+
+ receiver.AddCredit(1);
+
+After having granted credit to the above created receiver the application can
then call one of
+the available receive APIs to await the arrival of a message from a remote
sender.
+
+ IDelivery delivery = receiver.Receive();
+
+Once a delivery arrives an IDelivery 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:
+
+ IMessage<object> received = delivery.Message();
+
+Once the message is examined and processed the application can accept delivery
by calling
+the accept method from the delivery object as follows:
+
+ delivery.Accept();
+
+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.
+
+Please see http://qpid.apache.org/proton for more information.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
