Merge pull request #795 from rabbitmq/rabbitmq-dotnet-client-793

Change log and basic doc updates for 6.x

Author: michaelklishin

CHANGELOG.md

@@ -1,8 +1,77 @@
 ## Changes Between 5.2.0 and 6.0.0
 
-Please see the milestone for all changes:
+This major release of this client introduces substantial improvements
+in terms of memory footprint and throughput. They come at the cost
+of minor but important **breaking API changes** covered below.
+
+The client now requires .NET Framework 4.6.1 or .NET Standard 2.0.
+Earlier versions are no longer supported by the `6.x` series.
+
+Key improvements in this release have been the result of hard work by
+our stellar community members (in no particular order): @stebet, @bording,
+@Anarh2404, @danielmarbach, and others.
+
+A full list of changes can be found in the GitHub milestone: [`6.0.0`](https://github.com/rabbitmq/rabbitmq-dotnet-client/milestone/41?closed=1).
+
+### The Switch to System.Memory (and Significantly Lower Memory Footprint that Comes with It)
+
+The client now uses the [`System.Memory` library]() for message and command payloads. This significantly
+reduces object allocation and GC pressure for heavy workloads but also
+**potentially requires application changes**: consumer delivery payloads are now of instance [`System.ReadOnlyMemory<byte>`](https://docs.microsoft.com/en-us/dotnet/api/system.readonlymemory-1?view=netcore-3.1)
+instead of `byte[]`.
+
+While there's an implicit conversion for these types,
+instances of `System.ReadOnlyMemory<byte>` **must be copied or consumed/deserialised before delivery handler completes**.
+Holding on to delivered payloads and referencing them at a later point **is no longer safe**.
+
+The same applies to publishers and the `IModel.BasicPublish` method: prefer using `System.ReadOnlyMemory<byte>`
+over `byte[]` and dont' assume that this memory can be retained and used outside of the scope of the publishing
+function.
+
+GitHub issue: [#732](https://github.com/rabbitmq/rabbitmq-dotnet-client/pull/732)
+
+### Timeouts Use `System.TimeSpan`
+
+All timeout arguments now use `System.TimeSpan` values.
+
+GitHub issue: [#688](https://github.com/rabbitmq/rabbitmq-dotnet-client/pull/688)
+
+### Reduced Public API Surface
+
+No major changes here but this is potentially breaking. Only public classes that were never meant
+to be publicly used have been turned internal to the client.
+
+GitHub issue: [#714](https://github.com/rabbitmq/rabbitmq-dotnet-client/issues/714)
+
+### Requires .NET Framework 4.6.1 or .NET Standard 2.0
+
+The client now requires .NET Framework 4.6.1 or .NET Standard 2.0. Earlier versions are no longer
+supported.
+
+GitHub issue: [#686](https://github.com/rabbitmq/rabbitmq-dotnet-client/issues/686)
+
+### `Microsoft.Diagnostics.Tracing.EventSource` Dependency Dropped
+
+`Microsoft.Diagnostics.Tracing.EventSource` dependency has been removed. It was an annoying
+dependency to have for some environments.
+
+### Source Linking
+
+The library now supports source linking.
+
+GitHub issue: [#697](https://github.com/rabbitmq/rabbitmq-dotnet-client/issues/697)
+
+### NuGet Source Packages
+
+Source packages are now also distributed via NuGet.
+
+### CRL Checks for Server x.509 (TLS) Certificates
+
+Added a TLS option to enforce CRL checks for server certificates.
+
+GitHub issue: [#500](https://github.com/rabbitmq/rabbitmq-dotnet-client/pull/500)
+
 
-[GitHub `6.0.0` Milestone](https://github.com/rabbitmq/rabbitmq-dotnet-client/milestone/41?closed=1)
 
 ## Changes Between 5.1.2 and 5.2.0
 
@@ -14,13 +83,14 @@ Selected highlights:
 
 ### Add support for `netstandard2.0`
 
-GitHub Issue: https://github.com/rabbitmq/rabbitmq-dotnet-client/issues/428
-GitHub PR: https://github.com/rabbitmq/rabbitmq-dotnet-client/pull/435
+GitHub issues: [#428](https://github.com/rabbitmq/rabbitmq-dotnet-client/issues/428), [#435](https://github.com/rabbitmq/rabbitmq-dotnet-client/pull/435)
 
 ### Re-introduce lock for all socket writes
 
 GitHub PR: [rabbitmq-dotnet-client#702](https://github.com/rabbitmq/rabbitmq-dotnet-client/pull/702)
 
+
+
 ## Changes Between 5.1.1 and 5.1.2
 
 ### Bump System.Net.Security to 4.3.2

README.md

@@ -1,21 +1,18 @@
-## RabbitMQ .NET Client [![Build status](https://ci.appveyor.com/api/projects/status/33srpo7owl1h3y4e?svg=true)](https://ci.appveyor.com/project/rabbitmq/rabbitmq-dotnet-client)
+## RabbitMQ .NET Client
+
+* AppVeyor: [![AppVeyor Build status](https://ci.appveyor.com/api/projects/status/33srpo7owl1h3y4e?svg=true)](https://ci.appveyor.com/project/rabbitmq/rabbitmq-dotnet-client)
+* TravisCI: [![Travis CI Build Status](https://travis-ci.org/rabbitmq/rabbitmq-dotnet-client.svg?branch=master)](https://travis-ci.org/rabbitmq/rabbitmq-dotnet-client)
 
 This repository contains source code of the [RabbitMQ .NET client](https://www.rabbitmq.com/dotnet.html).
 The client is maintained by the [RabbitMQ team at VMware](https://github.com/rabbitmq/).
 
-## Dependency (Binaries and Nuget Artifact)
+
+## Dependency (NuGet Artifact)
 
 ### Modern Versions
 
 The client is [distributed via NuGet](https://www.nuget.org/packages/RabbitMQ.Client/).
 
-### Legacy Versions
-
-`3.6.x` and earlier releases were distributed [together with RabbitMQ server 3.6.x](https://github.com/rabbitmq/rabbitmq-server/releases/)
-as archives.
-
-[Release archive up to 3.4.3](https://bintray.com/rabbitmq/archive/rabbitmq-dotnet-client) is available from Bintray.
-
 
 ## Tutorials and Documentation
 
@@ -26,7 +23,10 @@ as archives.
 
 ## Supported Platforms and .NET Releases
 
-Future `6.x` versions of the library require .NET 4.6.1 or a .NET Core version implementing .NET Standard 2.0.
+### 6.x
+
+`6.x` versions of the library require .NET 4.6.1 or a .NET Core version implementing .NET Standard 2.0.
+They also introduce potentially breaking public API changes covered in the [changelog](CHANGELOG.md).
 
 ### 5.x and 4.x
 
@@ -37,18 +37,20 @@ For .NET Core users, 2.0 is the minimum supported version for `5.x` series.
 
 `3.6.x` releases support Linux and MacOS on [Mono](https://www.mono-project.com/).
 
+
 ## Change Log
 
-See [/CHANGELOG.md](https://github.com/rabbitmq/rabbitmq-dotnet-client/blob/master/CHANGELOG.md).
+See [CHANGELOG.md](CHANGELOG.md).
+
 
 ## Building from Source
 
-Please see [How to Run Tests](./RUNNING_TESTS.md) and [Building .NET Core](./BUILD_DOTNET_CORE.md)
-for build process overview.
+Please see [How to Run Tests](RUNNING_TESTS.md) for the build and test process overview.
+
 
 ## Contributing
 
-See [Contributing](./CONTRIBUTING.md) and [How to Run Tests](./RUNNING_TESTS.md).
+See [Contributing](CONTRIBUTING.md) and [How to Run Tests](RUNNING_TESTS.md).
 
 
 ## License

RUNNING_TESTS.md

@@ -1,13 +1,14 @@
 ## Overview
 
-.NET client's test suite assumes there's a RabbitMQ node listening on localhost:5672
+.NET client's test suite assumes there's a RabbitMQ node listening on `localhost:5672`
 (the default settings). SSL tests require a broker listening on the default
 SSL port. Connection recovery tests assume `rabbitmqctl` at `../rabbitmq-server/scripts/rabbitmqctl`
 can control the running node: this is the case when all repositories are cloned using
 the [umbrella repository](https://github.com/rabbitmq/rabbitmq-public-umbrella).
 
-It is possible to use [Visual Studio 2015 Community Edition](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx),
-.NET Core, and `dotnet.exe` in `PATH`, to build the client and run the test suite.
+It is possible to use Visual Studio Community Edition .NET Core, and
+`dotnet.exe` in `PATH`, to build the client and run the test suite.
+
 
 ## Building
 
@@ -27,39 +28,47 @@ This will complete the code AMQP 0-9-1 protocol code generation and build all pr
 
 ## Running Tests
 
-Tests can be run from Visual Studio using [NUnit Test Adapter](https://visualstudiogallery.msdn.microsoft.com/6ab922d0-21c0-4f06-ab5f-4ecd1fe7175d).
-Note that it may take some time for the adapter to discover tests in the assemblies.
+Tests can be run from Visual Studio using the NUnit Test Adapter.  Note that it
+may take some time for the adapter to discover tests in the assemblies.
 
-The test suite assumes there's a RabbitMQ node running locally with all defaults, and the tests will need to be able to run commands against the [rabbitmqctl](https://www.rabbitmq.com/rabbitmqctl.8.html) tool for that node. Two options to accomplish this are:
+The test suite assumes there's a RabbitMQ node running locally with all
+defaults, and the tests will need to be able to run commands against the
+[`rabbitmqctl`](https://www.rabbitmq.com/rabbitmqctl.8.html) tool for that node.
+Two options to accomplish this are:
 
 1. Team RabbitMQ uses [rabbitmq-public-umbrella](https://github.com/rabbitmq/rabbitmq-public-umbrella), which sets up a local RabbitMQ server [built from source](https://www.rabbitmq.com/build-server.html):
-```
+    ```
     git clone https://github.com/rabbitmq/rabbitmq-public-umbrella umbrella
     cd umbrella
     make co
     cd deps/rabbit
     make
     make run-broker
-```
+    ```
 
 2. You can load a RabbitMQ node in a [docker](https://www.docker.com/) container. You will need to create an environment variable `RABBITMQ_RABBITMQCTL_PATH` and set it to `DOCKER:<container_name>` (for example `DOCKER:rabbitmq01`). This tells the unit tests to run the `rabbitmqctl` commands through docker, in the format `docker exec rabbitmq01 rabbitmqctl <args>`:
-```
+    ```
     docker run -d --hostname rabbitmq01 --name rabbitmq01 -p 15672:15672 -p 5672:5672 rabbitmq:3-management
-```
+    ```
 
-Then, to run the tests on Windows use:
+    Then, to run the tests on Windows use:
 
+    ```
     run-test.bat
+    ```
 
-On MacOS, Linux, BSD use:
+    On MacOS, Linux, BSD use:
 
+    ```
     run-test.sh
+    ```
 
 Running individual tests and fixtures on Windows is trivial using the Visual Studio test runner.
 To run a specific tests fixture on MacOS or Linux, use the NUnit filter expressions to select the tests
 to be run:
 
-    dotnet test projects/Unit --filter "Name~TestAmqpUriParseFail"
-
+```
+dotnet test projects/Unit --filter "Name~TestAmqpUriParseFail"
 
-    dotnet test projects/Unit --filter "FullyQualifiedName~RabbitMQ.Client.Unit.TestHeartbeats"
+dotnet test projects/Unit --filter "FullyQualifiedName~RabbitMQ.Client.Unit.TestHeartbeats"
+```

projects/RabbitMQ.Client/client/api/AsyncDefaultBasicConsumer.cs

@@ -100,12 +100,14 @@ public virtual Task HandleBasicConsumeOk(string consumerTag)
         }
 
         /// <summary>
-        /// Called each time a message arrives for this consumer.
+        /// Called each time a message is delivered for this consumer.
         /// </summary>
         /// <remarks>
-        /// Does nothing with the passed in information.
-        /// Note that in particular, some delivered messages may require acknowledgement via <see cref="IModel.BasicAck"/>.
-        /// The implementation of this method in this class does NOT acknowledge such messages.
+        /// This is a no-op implementation. It will not acknowledge deliveries via <see cref="IModel.BasicAck"/>
+        /// if consuming in automatic acknowledgement mode.
+        /// Subclasses must copy or fully use delivery body before returning.
+        /// Accessing the body at a later point is unsafe as its memory can
+        /// be already released.
         /// </remarks>
         public virtual Task HandleBasicDeliver(string consumerTag,
             ulong deliveryTag,
@@ -120,10 +122,10 @@ public virtual Task HandleBasicDeliver(string consumerTag,
         }
 
         /// <summary>
-        ///  Called when the model shuts down.
-        ///  </summary>
-        ///  <param name="model"> Common AMQP model.</param>
-        /// <param name="reason"> Information about the reason why a particular model, session, or connection was destroyed.</param>
+        /// Called when the model (channel) this consumer was registered on terminates.
+        /// </summary>
+        /// <param name="model">A channel this consumer was registered on.</param>
+        /// <param name="reason">Shutdown context.</param>
         public virtual Task HandleModelShutdown(object model, ShutdownEventArgs reason)
         {
             ShutdownReason = reason;

projects/RabbitMQ.Client/client/api/DefaultBasicConsumer.cs

@@ -147,12 +147,14 @@ public virtual void HandleBasicConsumeOk(string consumerTag)
         }
 
         /// <summary>
-        /// Called each time a message arrives for this consumer.
+        /// Called each time a message is delivered for this consumer.
         /// </summary>
         /// <remarks>
-        /// Does nothing with the passed in information.
-        /// Note that in particular, some delivered messages may require acknowledgement via <see cref="IModel.BasicAck"/>.
-        /// The implementation of this method in this class does NOT acknowledge such messages.
+        /// This is a no-op implementation. It will not acknowledge deliveries via <see cref="IModel.BasicAck"/>
+        /// if consuming in automatic acknowledgement mode.
+        /// Subclasses must copy or fully use delivery body before returning.
+        /// Accessing the body at a later point is unsafe as its memory can
+        /// be already released.
         /// </remarks>
         public virtual void HandleBasicDeliver(string consumerTag,
             ulong deliveryTag,
@@ -166,10 +168,10 @@ public virtual void HandleBasicDeliver(string consumerTag,
         }
 
         /// <summary>
-        ///  Called when the model shuts down.
-        ///  </summary>
-        ///  <param name="model"> Common AMQP model.</param>
-        /// <param name="reason"> Information about the reason why a particular model, session, or connection was destroyed.</param>
+        /// Called when the model (channel) this consumer was registered on terminates.
+        /// </summary>
+        /// <param name="model">A channel this consumer was registered on.</param>
+        /// <param name="reason">Shutdown context.</param>
         public virtual void HandleModelShutdown(object model, ShutdownEventArgs reason)
         {
             ShutdownReason = reason;

projects/RabbitMQ.Client/client/events/AsyncEventingBasicConsumer.cs

@@ -11,26 +11,33 @@ public AsyncEventingBasicConsumer(IModel model) : base(model)
         {
         }
 
-        ///<summary>Event fired on HandleBasicDeliver.</summary>
+        ///<summary>
+        /// Event fired when a delivery arrives for the consumer.
+        /// </summary>
+        /// <remarks>
+        /// Handlers must copy or fully use delivery body before returning.
+        /// Accessing the body at a later point is unsafe as its memory can
+        /// be already released.
+        /// </remarks>
         public event AsyncEventHandler<BasicDeliverEventArgs> Received;
 
-        ///<summary>Event fired on HandleBasicConsumeOk.</summary>
+        ///<summary>Fires when the server confirms successful consumer cancelation.</summary>
         public event AsyncEventHandler<ConsumerEventArgs> Registered;
 
-        ///<summary>Event fired on HandleModelShutdown.</summary>
+        ///<summary>Fires on model (channel) shutdown, both client and server initiated.</summary>
         public event AsyncEventHandler<ShutdownEventArgs> Shutdown;
 
-        ///<summary>Event fired on HandleBasicCancelOk.</summary>
+        ///<summary>Fires when the server confirms successful consumer cancelation.</summary>
         public event AsyncEventHandler<ConsumerEventArgs> Unregistered;
 
-        ///<summary>Fires the Unregistered event.</summary>
+        ///<summary>Fires when the server confirms successful consumer cancelation.</summary>
         public override async Task HandleBasicCancelOk(string consumerTag)
         {
             await base.HandleBasicCancelOk(consumerTag).ConfigureAwait(false);
             await (Unregistered?.Invoke(this, new ConsumerEventArgs(new[] { consumerTag })) ?? Task.CompletedTask).ConfigureAwait(false);
         }
 
-        ///<summary>Fires the Registered event.</summary>
+        ///<summary>Fires when the server confirms successful consumer registration.</summary>
         public override async Task HandleBasicConsumeOk(string consumerTag)
         {
             await base.HandleBasicConsumeOk(consumerTag).ConfigureAwait(false);