Release 5.5.0 with netstandard2.0 support

Author: Marfusios

.github/workflows/dotnet-core-branches.yml

@@ -21,3 +21,19 @@ jobs:
       run: dotnet build --configuration Release --no-restore
     - name: Test
       run: dotnet test --no-restore --verbosity normal
+
+  net-framework:
+
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup .NET SDK
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 10.0.x
+
+    - name: Build .NET Framework sample
+      run: dotnet build test_integration\Websocket.Client.Sample.NetFramework\Websocket.Client.Sample.NetFramework.csproj --configuration Release --framework net472
+    - name: Build .NET Framework benchmarks
+      run: dotnet build benchmarks\Websocket.Client.Benchmarks\Websocket.Client.Benchmarks.csproj --configuration Release --framework net472

.github/workflows/dotnet-core.yml

@@ -35,3 +35,19 @@ jobs:
       run: dotnet nuget push *.nupkg --api-key ${{secrets.NUGET_API_KEY}} --source "https://api.nuget.org/v3/index.json" --skip-duplicate
     #- name: Publish library (Github)
     #  run: dotnet nuget push *.nupkg --api-key ${{secrets.PUBLISH_TO_GITHUB_TOKEN}} --source "https://nuget.pkg.github.com/marfusios/index.json" --skip-duplicate
+
+  net-framework:
+
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup .NET SDK
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 10.0.x
+
+    - name: Build .NET Framework sample
+      run: dotnet build test_integration\Websocket.Client.Sample.NetFramework\Websocket.Client.Sample.NetFramework.csproj --configuration Release --framework net472
+    - name: Build .NET Framework benchmarks
+      run: dotnet build benchmarks\Websocket.Client.Benchmarks\Websocket.Client.Benchmarks.csproj --configuration Release --framework net472

Directory.Build.props

@@ -3,7 +3,7 @@
 	<!-- Project defaults -->
 
 	<PropertyGroup>
-		<Version>5.4.0</Version>
+		<Version>5.5.0</Version>
 	</PropertyGroup>
 
 </Project>

README.md

@@ -15,7 +15,8 @@ This is a wrapper over native C# class `ClientWebSocket` with built-in reconnect
 ### Features
 
 * installation via NuGet ([Websocket.Client](https://www.nuget.org/packages/Websocket.Client))
-* targeting .NET Standard 2.1, .NET 6, .NET 7, .NET 8, .NET 9, and .NET 10
+* targeting .NET Standard 2.0, .NET Standard 2.1, .NET 6, .NET 7, .NET 8, .NET 9, and .NET 10
+* full .NET Framework support through the .NET Standard 2.0 asset; the included framework sample targets .NET Framework 4.7.2 on Windows
 * reactive extensions ([Rx.NET](https://github.com/Reactive-Extensions/Rx.NET))
 * integrated logging abstraction (`Microsoft.Extensions.Logging`)
 * using Channels for high performance sending queue
@@ -43,6 +44,7 @@ Representative BenchmarkDotNet results show meaningful improvements on typical s
 * disabled trace logging: `28.72 ns / 64 B` to approximately `0 ns / 0 B`
 * queued text request envelope: `31.54 ns / 24 B` to `29.65 ns / 0 B`
 * stream-backed binary `ResponseMessage.ToString()` at 32 KB: `1.149 us / 32872 B` to `44.60 ns / 104 B`
+* .NET Framework 4.8.1 client receive path, via the `netstandard2.0` asset: 1000 x 1024 B text messages in `1.062 ms / 2312.21 KB`
 
 For very large text messages, the resulting `string` allocation dominates the receive cost, so the library focuses on avoiding unnecessary intermediate allocations and avoiding retention of oversized receive buffers after traffic spikes.
 

Websocket.Client.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 17
-VisualStudioVersion = 17.0.31903.59
+# Visual Studio Version 18
+VisualStudioVersion = 18.7.11811.120 insiders
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{360B18BD-653A-4824-9261-C88167EEBAD2}"
 EndProject
@@ -33,6 +33,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "benchmarks", "benchmarks",
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Websocket.Client.Benchmarks", "benchmarks\Websocket.Client.Benchmarks\Websocket.Client.Benchmarks.csproj", "{4A962092-136C-489E-A1A7-B40D8506E048}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Websocket.Client.Sample.NetFramework", "test_integration\Websocket.Client.Sample.NetFramework\Websocket.Client.Sample.NetFramework.csproj", "{8742C4B4-85C3-F5D6-4391-68397361775F}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -115,6 +117,18 @@ Global
 		{4A962092-136C-489E-A1A7-B40D8506E048}.Release|x64.Build.0 = Release|Any CPU
 		{4A962092-136C-489E-A1A7-B40D8506E048}.Release|x86.ActiveCfg = Release|Any CPU
 		{4A962092-136C-489E-A1A7-B40D8506E048}.Release|x86.Build.0 = Release|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Debug|x64.Build.0 = Debug|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Debug|x86.Build.0 = Debug|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Release|x64.ActiveCfg = Release|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Release|x64.Build.0 = Release|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Release|x86.ActiveCfg = Release|Any CPU
+		{8742C4B4-85C3-F5D6-4391-68397361775F}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -126,6 +140,7 @@ Global
 		{085B9246-446B-4F61-A6EF-0D8949CA546D} = {42E4078C-4FBE-4B03-B889-1573332945A9}
 		{AFAC261C-E5B5-4558-A869-6AEF5F439060} = {42E4078C-4FBE-4B03-B889-1573332945A9}
 		{4A962092-136C-489E-A1A7-B40D8506E048} = {66320409-64EC-F7C5-3DEF-65E7510DAAD1}
+		{8742C4B4-85C3-F5D6-4391-68397361775F} = {42E4078C-4FBE-4B03-B889-1573332945A9}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {EE3E0B94-CF20-4C22-B50B-E720E8DFD675}

benchmarks/README.md

@@ -2,29 +2,37 @@
 
 This folder contains BenchmarkDotNet benchmarks for allocation-sensitive Websocket.Client hot paths.
 
-The latest representative run below was captured on Windows 11, AMD Ryzen 9 3900X, .NET SDK 10.0.201, running the benchmarks on .NET 10.0.5 with BenchmarkDotNet `ShortRun`.
+The representative .NET 10 results below were captured on Windows 11, AMD Ryzen 9 3900X, .NET SDK 10.0.201, running the benchmarks on .NET 10.0.5 with BenchmarkDotNet `ShortRun`.
 
-Run all benchmarks:
+The .NET Framework results were captured on the same machine with .NET SDK 10.0.300, BenchmarkDotNet 0.15.8, and .NET Framework 4.8.1 through the benchmark project's `net472` target.
+
+Run all .NET 10 benchmarks:
+
+```powershell
+dotnet run --configuration Release --framework net10.0 --project benchmarks\Websocket.Client.Benchmarks -- --filter "*"
+```
+
+Run the most relevant .NET 10 receive/send benchmarks:
 
 ```powershell
-dotnet run --configuration Release --project benchmarks\Websocket.Client.Benchmarks -- --filter "*"
+dotnet run --configuration Release --framework net10.0 --project benchmarks\Websocket.Client.Benchmarks -- --filter "*ReceiveBufferBenchmarks*"
+dotnet run --configuration Release --framework net10.0 --project benchmarks\Websocket.Client.Benchmarks -- --filter "*TextSendEncodingBenchmarks*"
+dotnet run --configuration Release --framework net10.0 --project benchmarks\Websocket.Client.Benchmarks -- --filter "*TraceLoggingBenchmarks*"
+dotnet run --configuration Release --framework net10.0 --project benchmarks\Websocket.Client.Benchmarks -- --filter "*RequestMessageBenchmarks*"
+dotnet run --configuration Release --framework net10.0 --project benchmarks\Websocket.Client.Benchmarks -- --filter "*SendSequenceFramingBenchmarks*"
 ```
 
-Run the most relevant receive/send benchmarks:
+Run the .NET Framework client receive benchmark on Windows:
 
 ```powershell
-dotnet run --configuration Release --project benchmarks\Websocket.Client.Benchmarks -- --filter "*ReceiveBufferBenchmarks*"
-dotnet run --configuration Release --project benchmarks\Websocket.Client.Benchmarks -- --filter "*TextSendEncodingBenchmarks*"
-dotnet run --configuration Release --project benchmarks\Websocket.Client.Benchmarks -- --filter "*TraceLoggingBenchmarks*"
-dotnet run --configuration Release --project benchmarks\Websocket.Client.Benchmarks -- --filter "*RequestMessageBenchmarks*"
-dotnet run --configuration Release --project benchmarks\Websocket.Client.Benchmarks -- --filter "*SendSequenceFramingBenchmarks*"
+dotnet run --configuration Release --framework net472 --project benchmarks\Websocket.Client.Benchmarks -- --filter "*ClientReceiveBenchmarks*"
 ```
 
 Results are written to `BenchmarkDotNet.Artifacts\results`.
 
 ## What The Benchmarks Cover
 
-- `ReceiveBufferBenchmarks` compares the old per-message `RecyclableMemoryStream` receive path, PR #158's `ArrayBufferWriter<byte>` path, and the current pooled receive buffer.
+- `ReceiveBufferBenchmarks` compares the old per-message `RecyclableMemoryStream` receive path, PR #158's `ArrayBufferWriter<byte>` path, and the current pooled receive buffer. This benchmark is .NET 10-only because the comparison uses `ArrayBufferWriter<byte>`.
 - `TextSendEncodingBenchmarks` compares outgoing text encoding through `Encoding.GetBytes(string)` against encoding into an `ArrayPool<byte>` buffer.
 - `ResponseMessageBenchmarks` measures the `ResponseMessage.ToString()` stream-copy fix.
 - `ObservablePropertyBenchmarks` measures cached observable properties versus creating an `AsObservable()` wrapper on every access.
@@ -109,9 +117,22 @@ Use the Ratio and Allocated columns for the quick answer. Values below 1.00 in R
 
 `ClientReceiveBenchmarks` measures the current public `WebsocketClient` receive flow using an in-memory scripted `WebSocket`. It is not a before/after benchmark; it is a package-level smoke benchmark for the real client path.
 
+#### .NET 10.0
+
 | Messages | Message size | Mean | Allocated |
 | ---: | ---: | ---: | ---: |
 | 100 | 64 B | 10.19 us | 25.42 KB |
 | 100 | 1024 B | 25.09 us | 212.93 KB |
 | 1000 | 64 B | 81.07 us | 201.21 KB |
 | 1000 | 1024 B | 215.61 us | 2076.21 KB |
+
+#### .NET Framework 4.8.1
+
+The `net472` benchmark target consumes the library's `netstandard2.0` asset, so this measures the compatibility path used by full .NET Framework applications.
+
+| Messages | Message size | Mean | Allocated |
+| ---: | ---: | ---: | ---: |
+| 100 | 64 B | 63.85 us | 51.31 KB |
+| 100 | 1024 B | 137.56 us | 242.04 KB |
+| 1000 | 64 B | 447.49 us | 421.71 KB |
+| 1000 | 1024 B | 1.062 ms | 2312.21 KB |

benchmarks/Websocket.Client.Benchmarks/ClientReceiveBenchmarks.cs

@@ -55,9 +55,27 @@ public async Task<int> Current_ClientReceiveTextMessages()
 
         await client.Start().ConfigureAwait(false);
         using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(10));
+#if NET472
+        return await WaitAsync(completion.Task, timeout.Token).ConfigureAwait(false);
+#else
         return await completion.Task.WaitAsync(timeout.Token).ConfigureAwait(false);
+#endif
     }
 
+#if NET472
+    private static async Task<T> WaitAsync<T>(Task<T> task, CancellationToken cancellationToken)
+    {
+        var cancellationTask = Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken);
+        var completedTask = await Task.WhenAny(task, cancellationTask).ConfigureAwait(false);
+
+        if (completedTask == task)
+            return await task.ConfigureAwait(false);
+
+        cancellationToken.ThrowIfCancellationRequested();
+        throw new TimeoutException("The benchmark operation timed out.");
+    }
+#endif
+
     private sealed class ScriptedTextWebSocket : WebSocket
     {
         private readonly byte[][] _messages;
@@ -109,10 +127,15 @@ public override void Dispose()
 
         public override async Task<WebSocketReceiveResult> ReceiveAsync(ArraySegment<byte> buffer, CancellationToken cancellationToken)
         {
+#if NET472
+            return await ReceiveSegmentAsync(buffer, cancellationToken).ConfigureAwait(false);
+#else
             var result = await ReceiveAsync(buffer.AsMemory(), cancellationToken).ConfigureAwait(false);
             return new WebSocketReceiveResult(result.Count, result.MessageType, result.EndOfMessage);
+#endif
         }
 
+#if !NET472
         public override ValueTask<ValueWebSocketReceiveResult> ReceiveAsync(Memory<byte> buffer, CancellationToken cancellationToken)
         {
             if (_messageIndex >= _messages.Length)
@@ -141,16 +164,51 @@ public override ValueTask<ValueWebSocketReceiveResult> ReceiveAsync(Memory<byte>
 
             return ValueTask.FromResult(new ValueWebSocketReceiveResult(count, WebSocketMessageType.Text, endOfMessage));
         }
+#endif
 
         public override Task SendAsync(ArraySegment<byte> buffer, WebSocketMessageType messageType, bool endOfMessage, CancellationToken cancellationToken)
         {
             return Task.CompletedTask;
         }
 
+#if NET472
+        private async Task<WebSocketReceiveResult> ReceiveSegmentAsync(ArraySegment<byte> buffer, CancellationToken cancellationToken)
+        {
+            if (_messageIndex >= _messages.Length)
+            {
+                if (_closeReturned)
+                {
+                    await Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken).ConfigureAwait(false);
+                    return new WebSocketReceiveResult(0, WebSocketMessageType.Close, true);
+                }
+
+                _closeReturned = true;
+                _state = WebSocketState.CloseReceived;
+                _closeStatus = WebSocketCloseStatus.NormalClosure;
+                _closeStatusDescription = "Benchmark complete";
+                return new WebSocketReceiveResult(0, WebSocketMessageType.Close, true);
+            }
+
+            var message = _messages[_messageIndex];
+            var count = Math.Min(buffer.Count, message.Length - _messageOffset);
+            Buffer.BlockCopy(message, _messageOffset, buffer.Array!, buffer.Offset, count);
+            _messageOffset += count;
+
+            var endOfMessage = _messageOffset == message.Length;
+            if (endOfMessage)
+            {
+                _messageIndex++;
+                _messageOffset = 0;
+            }
+
+            return new WebSocketReceiveResult(count, WebSocketMessageType.Text, endOfMessage);
+        }
+#else
         private static async ValueTask<ValueWebSocketReceiveResult> WaitForCancellation(CancellationToken cancellationToken)
         {
             await Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken).ConfigureAwait(false);
             return new ValueWebSocketReceiveResult(0, WebSocketMessageType.Close, true);
         }
+#endif
     }
 }

benchmarks/Websocket.Client.Benchmarks/ReceiveBufferBenchmarks.cs

@@ -5,6 +5,7 @@
 
 namespace Websocket.Client.Benchmarks;
 
+#if !NET472
 [MemoryDiagnoser]
 [ShortRunJob]
 [RankColumn]
@@ -97,3 +98,4 @@ private void WriteChunks(IBufferWriter<byte> writer)
         }
     }
 }
+#endif

benchmarks/Websocket.Client.Benchmarks/Websocket.Client.Benchmarks.csproj

@@ -2,8 +2,10 @@
 
 	<PropertyGroup>
 		<OutputType>Exe</OutputType>
-		<TargetFramework>net10.0</TargetFramework>
+		<TargetFrameworks>net10.0</TargetFrameworks>
+		<TargetFrameworks Condition="'$(OS)' == 'Windows_NT'">$(TargetFrameworks);net472</TargetFrameworks>
 		<Nullable>enable</Nullable>
+		<LangVersion>latest</LangVersion>
 		<ImplicitUsings>enable</ImplicitUsings>
 		<IsPackable>false</IsPackable>
 	</PropertyGroup>
@@ -13,6 +15,11 @@
 		<PackageReference Include="Microsoft.IO.RecyclableMemoryStream" Version="3.0.1" />
 	</ItemGroup>
 
+	<ItemGroup Condition="'$(TargetFramework)' == 'net472'">
+		<PackageReference Include="System.Memory" Version="4.6.3" />
+		<PackageReference Include="System.Threading.Channels" Version="10.0.8" />
+	</ItemGroup>
+
 	<ItemGroup>
 		<ProjectReference Include="..\..\src\Websocket.Client\Websocket.Client.csproj" />
 	</ItemGroup>

src/Websocket.Client/PooledBufferWriter.cs

@@ -25,6 +25,8 @@ private PooledBufferWriter(int initialCapacity, ArrayPool<byte> pool)
 
         public ReadOnlySpan<byte> WrittenSpan => _buffer.AsSpan(0, _written);
 
+        public ArraySegment<byte> WrittenSegment => new ArraySegment<byte>(_buffer, 0, _written);
+
         public int Capacity => _buffer.Length;
 
         public void Advance(int count)
@@ -50,6 +52,12 @@ public Span<byte> GetSpan(int sizeHint = 0)
             return _buffer.AsSpan(_written);
         }
 
+        public ArraySegment<byte> GetSegment(int sizeHint = 0)
+        {
+            Ensure(sizeHint);
+            return new ArraySegment<byte>(_buffer, _written, _buffer.Length - _written);
+        }
+
         public void Clear()
         {
             _written = 0;