Add tests and document new WriteValue method

src/Compilers/Core/CodeAnalysisTest/ObjectSerializationTests.cs

@@ -500,6 +500,19 @@ public void TestPrimitiveArrayValues()
             TestRoundTrip(w => TestWritingPrimitiveArrays(w), r => TestReadingPrimitiveArrays(r));
         }
 
+        [Theory]
+        [CombinatorialData]
+        public void TestByteSpan([CombinatorialValues(0, 1, 2, 3, 1000, 1000000)] int size)
+        {
+            var data = new byte[size];
+            for (int i = 0; i < data.Length; i++)
+            {
+                data[i] = (byte)i;
+            }
+
+            TestRoundTrip(w => TestWritingByteSpan(data, w), r => TestReadingByteSpan(data, r));
+        }
+
         [Fact]
         public void TestPrimitiveArrayMembers()
         {
@@ -596,6 +609,16 @@ private static void TestReadingPrimitiveArrays(ObjectReader reader)
             Assert.True(Enumerable.SequenceEqual(inputString, (string[])reader.ReadValue()));
         }
 
+        private static void TestWritingByteSpan(byte[] data, ObjectWriter writer)
+        {
+            writer.WriteValue(data.AsSpan());
+        }
+
+        private static void TestReadingByteSpan(byte[] expected, ObjectReader reader)
+        {
+            Assert.True(Enumerable.SequenceEqual(expected, (byte[])reader.ReadValue()));
+        }
+
         [Fact]
         public void TestBooleanArrays()
         {

src/Compilers/Core/Portable/Serialization/ObjectWriter.cs

@@ -266,6 +266,11 @@ public void WriteValue(object value)
             }
         }
 
+        /// <summary>
+        /// Write an array of bytes. The array data is provided as a
+        /// <see cref="ReadOnlySpan{T}">ReadOnlySpan</see>&lt;<see cref="byte"/>&gt;, and deserialized to a byte array.
+        /// </summary>
+        /// <param name="span">The array data.</param>
         public void WriteValue(ReadOnlySpan<byte> span)
         {
             int length = span.Length;
@@ -297,6 +302,9 @@ public void WriteValue(ReadOnlySpan<byte> span)
 #if NETCOREAPP
             _writer.Write(span);
 #else
+            // BinaryWriter in .NET Framework does not support ReadOnlySpan<byte>, so we use a temporary buffer to write
+            // arrays of data. The buffer is chosen to be no larger than 8K, which avoids allocations in the large
+            // object heap.
             var buffer = new byte[Math.Min(length, 8192)];
             for (int offset = 0; offset < length; offset += buffer.Length)
             {

src/Test/Utilities/Portable/Roslyn.Test.Utilities.csproj

@@ -80,6 +80,7 @@
     <PackageReference Include="Moq" Version="$(MoqVersion)" />
     <PackageReference Include="xunit.assert" Version="$(xunitassertVersion)" />
     <PackageReference Include="xunit.extensibility.core" Version="$(xunitextensibilitycoreVersion)" />
+    <PackageReference Include="Xunit.Combinatorial" Version="$(XunitCombinatorialVersion)" />
     <PackageReference Include="ICSharpCode.Decompiler" Version="$(ICSharpCodeDecompilerVersion)" />
     <PackageReference Include="Newtonsoft.Json" Version="$(NewtonsoftJsonVersion)" />
     <PackageReference Include="Microsoft.CodeAnalysis.AnalyzerUtilities" Version="$(MicrosoftCodeAnalysisAnalyzerUtilitiesVersion)" />