Merge pull request #239 from brantburnett/raw-binary-transcoder-memory

DOC-9636: Document new RawBinaryTranscoder features in .NET SDK 3.2.6

Author: jeffrymorris

modules/howtos/examples/Transcoding.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Buffers;
 using System.IO;
 using System.Threading.Tasks;
 using System.Text.Json;
@@ -80,6 +81,26 @@ public async Task Binary()
             Console.WriteLine(returned);
         }
 
+        public async Task BinaryMemory()
+        {
+
+            // #tag::binary-memory[]
+            var docId = "doc";
+
+            using var buffer = MemoryPool<byte>.Shared.Rent(16);
+            var byteCount = System.Text.Encoding.UTF8.GetBytes("hello world", buffer.Memory.Span);
+            Memory<byte> bytes = buffer.Memory.Slice(0, byteCount);
+
+            await _collection.UpsertAsync(docId, bytes, options => options.Transcoder(new RawBinaryTranscoder()));
+
+            var result = await _collection.GetAsync(docId, options => options.Transcoder(new RawBinaryTranscoder()));
+
+            // Be sure to dispose of the IMemoryOwner<byte> when done, typically via a using statement
+            using var returned = result.ContentAs<IMemoryOwner<byte>>();
+            // #end::binary-memory[]
+            Console.WriteLine(System.Text.Encoding.UTF8.GetString(returned.Memory.Span));
+        }
+
         public async Task CustomEncode()
         {
             // #tag::custom-encode[]

modules/howtos/pages/transcoders-nonjson.adoc

@@ -143,25 +143,40 @@ include::example$Transcoding.cs[tag=string,indent=0]
 
 === RawBinaryTranscoder
 The RawBinaryTranscoder provides the ability for the user to explicitly store and retrieve raw byte data to Couchbase.
-The transcoder does not perform any form of real transcoding, and does not take a serializer, but rather passes the data through and assigns the appropriate binary Common Flag.
+The transcoder does not perform any form of real transcoding, and does not take a serializer, but rather passes the data through and assigns the appropriate `Binary` Common Flag (except in the case of an exception).
 
 [cols="3", options="header"]
 |===
 |Item
-|Result
-|Common Flag
+|Encoding Result
+|Decoding Result
 
 |String
 |InvalidArgumentException
-|-
+|InvalidArgumentException
 
 |byte[]
 |Passthrough
-|Binary
+|Passthrough
+
+|Memory<byte>
+|Passthrough +
+(from 3.2.6)
+|InvalidArgumentException
+
+|ReadOnlyMemory<byte>
+|Passthrough +
+(from 3.2.6)
+|InvalidArgumentException
+
+|IMemoryOwner<byte>
+|InvalidArgumentException
+|Passthrough +
+(from 3.2.6)
 
 |Other `Object`
 |InvalidArgumentException
-|-
+|InvalidArgumentException
 |===
 
 Here’s an example of using the `RawBinaryTranscoder`:
@@ -171,6 +186,14 @@ Here’s an example of using the `RawBinaryTranscoder`:
 include::example$Transcoding.cs[tag=binary,indent=0]
 ----
 
+From version 3.2.6, the `RawBinaryTranscoder` will accept `Memory<byte>` and `ReadOnlyMemory<byte>` inputs and can return `IMemoryOwner<byte>` outputs.
+Using these types may improve performance by not allocating large, temporary `byte[]` arrays on the heap.
+
+[source,csharp]
+----
+include::example$Transcoding.cs[tag=binary-memory,indent=0]
+----
+
 == Custom Transcoders and Serializers
 More advanced transcoding needs can be accomplished if the application implements their own transcoders and serializers.