* Update dotnet tutorial seven to use GitHub references

Author: lukebakken

tutorials/tutorial-seven-dotnet.md

@@ -50,9 +50,8 @@ Publisher confirms are a RabbitMQ extension to the AMQP 0.9.1 protocol,
 so they are not enabled by default. Publisher confirms are
 enabled at the channel level with the `ConfirmSelect` method:
 
-```csharp
-var channel = await connection.CreateModelAsync();
-channel.ConfirmSelect();
+```csharp reference
+https://github.com/rabbitmq/rabbitmq-tutorials/blob/rabbitmq-dotnet-client-7.0.0/dotnet/PublisherConfirms/PublisherConfirms.cs#L29
 ```
 
 This method must be called on every channel that you expect to use publisher
@@ -68,28 +67,29 @@ while (ThereAreMessagesToPublish())
 {
     byte[] body = ...;
     IBasicProperties properties = ...;
-    channel.BasicPublish(exchange, queue, properties, body);
+    await channel.BasicPublishAsync(exchange, queue, properties, body);
     // uses a 5 second timeout
-    channel.WaitForConfirmsOrDie(TimeSpan.FromSeconds(5));
+    await channel.WaitForConfirmsOrDieAsync(TimeSpan.FromSeconds(5));
 }
 ```
 
 In the previous example we publish a message as usual and wait for its
-confirmation with the `Channel#WaitForConfirmsOrDie(TimeSpan)` method.
+confirmation with the `IChannel#WaitForConfirmsOrDieAsync(TimeSpan)` method.
 The method returns as soon as the message has been confirmed. If the
 message is not confirmed within the timeout or if it is nack-ed (meaning
 the broker could not take care of it for some reason), the method will
 throw an exception. The handling of the exception usually consists
 in logging an error message and/or retrying to send the message.
 
-Different client libraries have different ways to synchronously deal with publisher confirms,
-so make sure to read carefully the documentation of the client you are using.
+Different client libraries have different ways to synchronously deal with
+publisher confirms, so make sure to read carefully the documentation of the
+client you are using.
 
-This technique is very straightforward but also has a major drawback:
-it **significantly slows down publishing**, as the confirmation of a message blocks the publishing
-of all subsequent messages. This approach is not going to deliver throughput of
-more than a few hundreds of published messages per second. Nevertheless, this can be
-good enough for some applications.
+This technique is very straightforward but also has a major drawback: it can
+**significantly slows down publishing**, as the confirmation of a message
+blocks the publishing of all subsequent messages. This approach is not going to
+deliver throughput of more than a few hundreds of published messages per
+second. Nevertheless, this can be good enough for some applications.
 
 > #### Are Publisher Confirms Asynchronous?
 >
@@ -107,25 +107,8 @@ To improve upon our previous example, we can publish a batch
 of messages and wait for this whole batch to be confirmed.
 The following example uses a batch of 100:
 
-```csharp
-var batchSize = 100;
-var outstandingMessageCount = 0;
-while (ThereAreMessagesToPublish())
-{
-    byte[] body = ...;
-    IBasicProperties properties = ...;
-    channel.BasicPublish(exchange, queue, properties, body);
-    outstandingMessageCount++;
-    if (outstandingMessageCount == batchSize)
-    {
-        channel.WaitForConfirmsOrDie(TimeSpan.FromSeconds(5));
-        outstandingMessageCount = 0;
-    }
-}
-if (outstandingMessageCount > 0)
-{
-    channel.WaitForConfirmsOrDie(TimeSpan.FromSeconds(5));
-}
+```csharp reference
+https://github.com/rabbitmq/rabbitmq-tutorials/blob/rabbitmq-dotnet-client-7.0.0/dotnet/PublisherConfirms/PublisherConfirms.cs#L67-L91
 ```
 
 Waiting for a batch of messages to be confirmed improves throughput drastically over
@@ -143,7 +126,7 @@ to register a callback on the client to be notified of these confirms:
 
 ```csharp
 var channel = await connection.CreateModelAsync();
-channel.ConfirmSelect();
+await channel.ConfirmSelectAsync();
 channel.BasicAcks += (sender, ea) =>
 {
   // code when message is confirmed
@@ -155,91 +138,39 @@ channel.BasicNacks += (sender, ea) =>
 ```
 
 There are 2 callbacks: one for confirmed messages and one for nack-ed messages
-(messages that can be considered lost by the broker). Both callbacks have a corresponding `EventArgs` parameter (`ea`) containing a:
+(messages that can be considered lost by the broker). Both callbacks have a
+corresponding `EventArgs` parameter (`ea`) containing a:
 
  * delivery tag: the sequence number identifying the confirmed
  or nack-ed message. We will see shortly how to correlate it with the published message.
  * multiple: this is a boolean value. If false, only one message is confirmed/nack-ed, if
  true, all messages with a lower or equal sequence number are confirmed/nack-ed.
 
-The sequence number can be obtained with `Channel#NextPublishSeqNo`
+The sequence number can be obtained with `IChannel#NextPublishSeqNo`
 before publishing:
 
 ```csharp
 var sequenceNumber = channel.NextPublishSeqNo;
-channel.BasicPublish(exchange, queue, properties, body);
+await channel.BasicPublishAsync(exchange, queue, properties, body);
 ```
 
-A simple way to correlate messages with sequence number consists
-in using a dictionary. Let's assume we want to publish strings because they are easy
-to turn into an array of bytes for publishing. Here is a code
-sample that uses a dictionary to correlate the publishing sequence number
-with the string body of the message:
+A performant way to correlate messages with sequence number consists in using a
+linked list. Let's assume we want to publish strings because they are easy to
+turn into an array of bytes for publishing.
 
-```csharp
-var outstandingConfirms = new ConcurrentDictionary<ulong, string>();
-// ... code for confirm callbacks will come later
-var body = "...";
-outstandingConfirms.TryAdd(channel.NextPublishSeqNo, body);
-channel.BasicPublish(exchange, queue, properties, Encoding.UTF8.GetBytes(body));
-```
-
-The publishing code now tracks outbound messages with a dictionary. We need
-to clean this dictionary when confirms arrive and do something like logging a warning
+The publishing code now tracks outbound messages with a linked list. We need to
+clean this list when confirms arrive and do something like logging a warning
 when messages are nack-ed:
 
-```csharp
-var outstandingConfirms = new ConcurrentDictionary<ulong, string>();
-
-void CleanOutstandingConfirms(ulong sequenceNumber, bool multiple)
-{
-    if (multiple)
-    {
-        var confirmed = outstandingConfirms.Where(k => k.Key <= sequenceNumber);
-        foreach (var entry in confirmed)
-        {
-            outstandingConfirms.TryRemove(entry.Key, out _);
-        }
-    }
-    else
-    {
-        outstandingConfirms.TryRemove(sequenceNumber, out _);
-    }
-}
-
-channel.BasicAcks += (sender, ea) => CleanOutstandingConfirms(ea.DeliveryTag, ea.Multiple);
-channel.BasicNacks += (sender, ea) =>
-{
-    outstandingConfirms.TryGetValue(ea.DeliveryTag, out string body);
-    Console.WriteLine($"Message with body {body} has been nack-ed. Sequence number: {ea.DeliveryTag}, multiple: {ea.Multiple}");
-    CleanOutstandingConfirms(ea.DeliveryTag, ea.Multiple);
-};
-
-// ... publishing code
+```csharp reference
+https://github.com/rabbitmq/rabbitmq-tutorials/blob/rabbitmq-dotnet-client-7.0.0/dotnet/PublisherConfirms/PublisherConfirms.cs#L118-L156
 ```
 
-The previous sample contains a callback that cleans the dictionary when
-confirms arrive. Note this callback handles both single and multiple
-confirms. This callback is used when confirms arrive (`Channel#BasicAcks`). The callback for nack-ed messages
-retrieves the message body and issues a warning. It then re-uses the
-previous callback to clean the dictionary of outstanding confirms (whether
-messages are confirmed or nack-ed, their corresponding entries in the dictionary
-must be removed.)
-
-> #### How to Track Outstanding Confirms?
->
-> Our samples use a `ConcurrentDictionary` to track outstanding confirms.
-> This data structure is convenient for several reasons. It allows to
-> easily correlate a sequence number with a message (whatever the message data
-> is) and to easily clean the entries up to a given sequence id (to handle
-> multiple confirms/nacks). At last, it supports concurrent access, because
-> confirm callbacks are called in a thread owned by the client library, which
-> should be kept different from the publishing thread.
->
-> There are other ways to track outstanding confirms than with
-> a sophisticated dictionary implementation, like using a simple concurrent hash table
-> and a variable to track the lower bound of the publishing sequence, but
-> they are usually more involved and do not belong to a tutorial.
+The previous sample contains a callback that cleans the linked list when
+confirms arrive. Note this callback handles both single and multiple confirms.
+This callback is used when confirms arrive (`IChannel#BasicAcks`). The callback
+for nack-ed messages issues a warning. It then re-uses the previous callback to
+clean the linked list of outstanding confirms.
 
 To sum up, handling publisher confirms asynchronously usually requires the
 following steps:
@@ -278,53 +209,44 @@ to the constraints in the application and in the overall system. Typical techniq
 
 ## Putting It All Together
 
-The [`PublisherConfirms.cs`](https://github.com/rabbitmq/rabbitmq-tutorials/blob/main/dotnet/PublisherConfirms/PublisherConfirms.cs)
+The [`PublisherConfirms.cs`](https://github.com/rabbitmq/rabbitmq-tutorials/blob/rabbitmq-dotnet-client-7.0.0/dotnet/PublisherConfirms/PublisherConfirms.cs)
 class contains code for the techniques we covered. We can compile it, execute it as-is and
 see how they each perform:
 
-```bash
-dotnet run
+```PowerShell
+> dotnet run .\PublisherConfirms.csproj
+9/9/2024 11:07:11 AM [INFO] publishing 50,000 messages individually and handling confirms all at once
+9/9/2024 11:07:12 AM [INFO] published 50,000 messages individually in 796 ms
+9/9/2024 11:07:12 AM [INFO] publishing 50,000 messages and handling confirms in batches
+9/9/2024 11:07:13 AM [INFO] published 50,000 messages in batch in 1,034 ms
+9/9/2024 11:07:13 AM [INFO] publishing 50,000 messages and handling confirms asynchronously
+9/9/2024 11:07:14 AM [INFO] published 50,000 messages and handled confirm asynchronously 763 ms
 ```
 
-The output will look like the following:
-
-```bash
-Published 50,000 messages individually in 5,549 ms
-Published 50,000 messages in batch in 2,331 ms
-Published 50,000 messages and handled confirms asynchronously in 4,054 ms
-```
-
-The output on your computer should look similar if the client and the server sit
-on the same machine. Publishing messages individually performs poorly as expected,
-but the results for asynchronously handling are a bit disappointing compared to batch publishing.
+The output on your computer should look similar if the client and the server
+sit on the same machine.
 
 Publisher confirms are very network-dependent, so we're better off
 trying with a remote node, which is more realistic as clients
 and servers are usually not on the same machine in production.
 `PublisherConfirms.cs` can easily be changed to use a non-local node:
 
 ```csharp
-private static IConnection CreateConnection()
+private static Task<IConnection> CreateConnection()
 {
-    var factory = new ConnectionFactory { HostName = "remote-host", UserName = "remote-host", Password = "remote-password" };
-    return await factory.CreateConnectionAsync();
-}
-```
-
-Recompile the class, execute it again, and wait for the results:
+    var factory = new ConnectionFactory
+    {
+        HostName = "remote-host",
+        UserName = "remote-host",
+        Password = "remote-password"
+    };
 
-```bash
-Published 50,000 messages individually in 231,541 ms
-Published 50,000 messages in batch in 7,232 ms
-Published 50,000 messages and handled confirms asynchronously in 6,332 ms
+    return factory.CreateConnectionAsync();
+}
 ```
 
-We see publishing individually now performs terribly. But
-with the network between the client and the server, batch publishing and asynchronous handling
-now perform similarly, with a small advantage for asynchronous handling of the publisher confirms.
-
-Remember that batch publishing is simple to implement, but does not make it easy to know
-which message(s) could not make it to the broker in case of negative publisher acknowledgment.
-Handling publisher confirms asynchronously is more involved to implement but provide
-better granularity and better control over actions to perform when published messages
-are nack-ed.
+Remember that batch publishing is simple to implement, but does not make it
+easy to know which message(s) could not make it to the broker in case of
+negative publisher acknowledgment. Handling publisher confirms asynchronously
+is more involved to implement but provide better granularity and better control
+over actions to perform when published messages are nack-ed.