A README written for the package pages

The core package shipped the repository README, which nuget.org renders
without its HTML, relative links or images. Json-Rpc/README.md is written for
that page: what the library is, the prerelease install line, the quick start
from the repository README, the 1.2.3-versus-2.0 table with the headline chart
from raw.githubusercontent.com, the companion packages, a short Upgrading from
1.x summary, and absolute links to the documentation site. It points a 1.x user
at the What is new and Upgrading pages right after the install line, which is
what Visual Studio shows when it opens the README on install. The companion
READMEs open the same way, and the four package descriptions are shorter.

Author: Astn

AustinHarris.JsonRpc.AspNetCore/AustinHarris.JsonRpc.AspNetCore.csproj

@@ -4,7 +4,7 @@
         <Company>Austin Harris</Company>
         <Authors>Austin Harris</Authors>
         <Product>Json-Rpc.Net ASP.NET Core host</Product>
-        <Description>ASP.NET Core / Kestrel hosting for JSON-RPC.Net: MapJsonRpc endpoint (PipeReader in, BodyWriter out, no strings), a raw Kestrel ConnectionHandler for JSON-RPC over TCP, and DI registration of services.</Description>
+        <Description>ASP.NET Core hosting for AustinHarris.JsonRpc. Adds HTTP endpoints and raw Kestrel connections over TCP, Unix sockets and named pipes, with dependency injection.</Description>
         <VersionPrefix>2.0.0</VersionPrefix>
         <VersionSuffix>preview.1</VersionSuffix>
         <PackageReleaseNotes>2.0.0-preview.1, released with the core package. What is new: https://astn.github.io/JSON-RPC.NET/changelog.html. Upgrading from 1.x: https://astn.github.io/JSON-RPC.NET/upgrading.html</PackageReleaseNotes>

AustinHarris.JsonRpc.AspNetCore/README.md

@@ -1,14 +1,17 @@
-# AustinHarris.JsonRpc.AspNetCore
+# `AustinHarris.JsonRpc.AspNetCore`
 
-Hosts [JSON-RPC.Net](https://github.com/Astn/JSON-RPC.NET) in ASP.NET Core. The core processes requests as
-UTF-8 bytes, so the HTTP endpoint reads the body with `PipeReader` and writes straight into
-`Response.BodyWriter`; nothing is turned into a string on the way through. A `ConnectionHandler` does the
-same for JSON-RPC over a raw Kestrel connection (TCP, Unix socket, named pipe).
+`AustinHarris.JsonRpc.AspNetCore` hosts
+[`AustinHarris.JsonRpc`](https://www.nuget.org/packages/AustinHarris.JsonRpc) 2.0 in ASP.NET Core
+and registers services through dependency injection.
+Choose it for an HTTP endpoint or raw Kestrel connections over TCP, Unix sockets or named pipes.
+
+The HTTP endpoint reads with `PipeReader` and writes to `Response.BodyWriter`
+without converting the document to a string.
 
 ## Install
 
-```
-dotnet add package AustinHarris.JsonRpc.AspNetCore
+```sh
+dotnet add package AustinHarris.JsonRpc.AspNetCore --prerelease
 ```
 
 Targets `net8.0` and `net10.0`; depends on the `AustinHarris.JsonRpc` core package and the ASP.NET Core shared

AustinHarris.JsonRpc.Newtonsoft/AustinHarris.JsonRpc.Newtonsoft.csproj

@@ -4,7 +4,7 @@
         <Company>Austin Harris</Company>
         <Authors>Austin Harris</Authors>
         <Product>Json-Rpc.Net Json.NET serializer</Product>
-        <Description>Json.NET (Newtonsoft.Json) serializer for JSON-RPC.Net. Lenient parsing and full Json.NET conversion semantics; pass JsonSerializerSettings to control it.</Description>
+        <Description>Json.NET serializer for AustinHarris.JsonRpc. Uses JsonSerializerSettings for converters, contract resolvers and lenient JSON input.</Description>
         <VersionPrefix>2.0.0</VersionPrefix>
         <VersionSuffix>preview.1</VersionSuffix>
         <PackageReleaseNotes>2.0.0-preview.1, released with the core package. What is new: https://astn.github.io/JSON-RPC.NET/changelog.html. Upgrading from 1.x: https://astn.github.io/JSON-RPC.NET/upgrading.html</PackageReleaseNotes>

AustinHarris.JsonRpc.Newtonsoft/README.md

@@ -1,14 +1,16 @@
-# AustinHarris.JsonRpc.Newtonsoft
+# `AustinHarris.JsonRpc.Newtonsoft`
 
-Json.NET (Newtonsoft.Json) serializer for [JSON-RPC.Net](https://github.com/Astn/JSON-RPC.NET) 2.0.
+`AustinHarris.JsonRpc.Newtonsoft` adds Json.NET serialization to
+[`AustinHarris.JsonRpc`](https://www.nuget.org/packages/AustinHarris.JsonRpc) 2.0.
+Choose it when your models rely on Json.NET converters, contract resolvers or `[JsonProperty]`,
+or when clients send non-strict JSON.
 
-The core package (`AustinHarris.JsonRpc`) parses the JSON-RPC envelope itself and ships a built-in serializer for
-parameters and results that needs no JSON library. Install this package when you want Json.NET to do the value
-conversions: its converters, contract resolvers, `[JsonProperty]` attributes, date/float handling, and its
-tolerance for non-strict JSON.
+Configure parameter and result conversion with `JsonSerializerSettings`.
 
-```
-dotnet add package AustinHarris.JsonRpc.Newtonsoft
+## Install
+
+```sh
+dotnet add package AustinHarris.JsonRpc.Newtonsoft --prerelease
 ```
 
 Targets `netstandard2.0`, `netstandard2.1`, `net8.0` and `net10.0`; depends on Newtonsoft.Json 13.0.4 and the

AustinHarris.JsonRpc.SystemTextJson/AustinHarris.JsonRpc.SystemTextJson.csproj

@@ -4,7 +4,7 @@
         <Company>Austin Harris</Company>
         <Authors>Austin Harris</Authors>
         <Product>Json-Rpc.Net System.Text.Json serializer</Product>
-        <Description>System.Text.Json serializer for JSON-RPC.Net. Utf8JsonReader/Utf8JsonWriter end to end; pass JsonSerializerOptions to control it.</Description>
+        <Description>System.Text.Json serializer for AustinHarris.JsonRpc. Reads UTF-8 parameters and writes results directly to the response buffer, configured with JsonSerializerOptions.</Description>
         <VersionPrefix>2.0.0</VersionPrefix>
         <VersionSuffix>preview.1</VersionSuffix>
         <PackageReleaseNotes>2.0.0-preview.1, released with the core package. What is new: https://astn.github.io/JSON-RPC.NET/changelog.html. Upgrading from 1.x: https://astn.github.io/JSON-RPC.NET/upgrading.html</PackageReleaseNotes>

AustinHarris.JsonRpc.SystemTextJson/README.md

@@ -1,15 +1,17 @@
-# AustinHarris.JsonRpc.SystemTextJson
+# `AustinHarris.JsonRpc.SystemTextJson`
 
-System.Text.Json serializer for [JSON-RPC.Net](https://github.com/Astn/JSON-RPC.NET) 2.0. The core parses the
-JSON-RPC envelope (method / params / id) itself and asks the serializer only to convert values: request
-parameters arrive as the raw UTF-8 bytes of one JSON value and go straight into `JsonSerializer.Deserialize`
-(no transcoding, no copies); results are written with a per-thread cached `Utf8JsonWriter` directly into the
+`AustinHarris.JsonRpc.SystemTextJson` adds `System.Text.Json` serialization to
+[`AustinHarris.JsonRpc`](https://www.nuget.org/packages/AustinHarris.JsonRpc) 2.0.
+Choose it when your application already uses `JsonSerializerOptions` and `System.Text.Json` converters.
+
+Request parameters arrive as the raw UTF-8 bytes of one JSON value and go straight into `JsonSerializer.Deserialize`,
+with no transcoding and no copies. Results are written with a per-thread cached `Utf8JsonWriter` directly into the
 response buffer.
 
 ## Install
 
-```
-dotnet add package AustinHarris.JsonRpc.SystemTextJson
+```sh
+dotnet add package AustinHarris.JsonRpc.SystemTextJson --prerelease
 ```
 
 Targets `netstandard2.0`, `netstandard2.1`, `net8.0` and `net10.0`; depends on System.Text.Json 10.0.3 and the

Json-Rpc/AustinHarris.JsonRpc.csproj

@@ -4,7 +4,7 @@
         <Company>Austin Harris</Company>
         <Authors>Austin Harris</Authors>
         <Product>Json-Rpc.Net Core</Product>
-        <Description>JSON-RPC.Net is a high performance JSON-RPC 2.0 server for .NET Standard 2.0+ and modern .NET. Bytes in, bytes out, no JSON library dependency: the built-in serializer needs nothing, and Json.NET or System.Text.Json plug in through the companion packages. Host it in ASP.NET Core / Kestrel, a console app, sockets, pipes - anything that can hand you UTF-8 or a string.</Description>
+        <Description>High-throughput JSON-RPC 2.0 server library for .NET Standard 2.0 through .NET 10: UTF-8 bytes in and out, no JSON library dependency, with Json.NET, System.Text.Json and ASP.NET Core hosting as companion packages.</Description>
         <VersionPrefix>2.0.0</VersionPrefix>
         <VersionSuffix>preview.1</VersionSuffix>
         <Copyright>Austin Harris</Copyright>
@@ -28,7 +28,7 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <None Include="..\README.md" Pack="true" PackagePath="\" />
+        <None Include="README.md" Pack="true" PackagePath="\" />
         <None Include="..\icon.png" Pack="true" PackagePath="\" />
         <InternalsVisibleTo Include="AustinHarris.JsonRpcTestN" />
         <InternalsVisibleTo Include="AustinHarris.JsonRpc.Micro" />

Json-Rpc/README.md

@@ -0,0 +1,150 @@
+# `AustinHarris.JsonRpc`
+
+`AustinHarris.JsonRpc` is a JSON-RPC 2.0 server library for .NET.
+Give it a UTF-8 request document and receive the response document: bytes in, bytes out.
+It handles parsing, method dispatch, parameter binding, batches and error responses.
+You supply the transport.
+
+The core has no JSON library dependency.
+Its built-in serializer works on its own; companion packages add Json.NET,
+`System.Text.Json` or ASP.NET Core hosting.
+
+Targets `netstandard2.0`, `netstandard2.1`, `net8.0` and `net10.0`.
+This is a server library, with no client proxies or server-to-client calls.
+
+## Install
+
+2.0 is a prerelease. Include `--prerelease` when installing:
+
+```sh
+dotnet add package AustinHarris.JsonRpc --prerelease
+```
+
+Coming from 1.x? Read [What is new in 2.0](https://astn.github.io/JSON-RPC.NET/changelog.html) and [Upgrading from 1.x](https://astn.github.io/JSON-RPC.NET/upgrading.html) first.
+
+## Getting started
+
+### Declare a service
+
+Create `CalculatorService.cs` with the service below.
+Derive from `JsonRpcService` and mark exposed methods with `[JsonRpcMethod]`.
+Constructing the service registers its methods in the default session.
+
+```csharp
+using AustinHarris.JsonRpc;
+
+public class CalculatorService : JsonRpcService
+{
+    [JsonRpcMethod]                 // exposed as "add"
+    private double add(double l, double r) => l + r;
+
+    [JsonRpcMethod("multiply")]     // exposed under an explicit name
+    public int Multiply(int l, int r) => l * r;
+
+    [JsonRpcMethod]
+    public string StringMe(string x) => x;
+}
+```
+
+Methods can be `private`. Parameters can be positional or named.
+Keep the service instance alive; it serves concurrent requests, so its state must be thread-safe.
+
+### Process requests
+
+Put this code in `Program.cs` in a console project targeting `net8.0` or `net10.0`.
+It calls the service through both string overloads and the byte entry point.
+The string overloads transcode into the byte pipeline.
+
+```csharp
+using System;
+using System.Buffers;
+using System.Text;
+using AustinHarris.JsonRpc;
+
+var service = new CalculatorService();   // binds itself to the default session; keep a reference
+
+// Strings, asynchronous invocation.
+string response = await JsonRpcProcessor.ProcessAsync("{\"jsonrpc\":\"2.0\",\"method\":\"add\",\"params\":[1,2],\"id\":1}");
+// {"jsonrpc":"2.0","result":3.0,"id":1}
+
+// Strings, synchronous, on the calling thread. Named parameters.
+string sync = JsonRpcProcessor.ProcessSync("{\"method\":\"multiply\",\"params\":{\"l\":6,\"r\":7},\"id\":2}");
+// {"jsonrpc":"2.0","result":42,"id":2}
+
+// Bytes: the native path. The string overloads transcode into it.
+byte[] request = Encoding.UTF8.GetBytes("{\"method\":\"add\",\"params\":[2,3],\"id\":3}");
+var output = new ArrayBufferWriter<byte>();
+JsonRpcProcessor.Process(Handler.DefaultSessionId(), request.AsSpan(), output);
+Console.WriteLine(Encoding.UTF8.GetString(output.WrittenSpan));   // nothing is written for a notification
+```
+
+The string responses appear in the comments above. The byte call prints:
+
+```json
+{"jsonrpc":"2.0","result":5.0,"id":3}
+```
+
+A batch returns an array when it contains calls that need responses.
+A notification has no `id` and produces no response.
+Pass a `byte[]` as `AsSpan()` to select the span overload.
+
+Use `JsonRpcProcessor.ProcessAsync` for methods returning `Task` or `ValueTask`.
+The synchronous entry points do not await those methods.
+
+## Performance
+
+These results compare 1.2.3 and 2.0 with the same five requests on the same machine in one session.
+The 2.0 runs used the built-in serializer on an AMD Ryzen 7 7800X3D with .NET 10, Release and Server GC.
+
+![JSON-RPC.Net 1.2.3 and 2.0 throughput through the string and byte entry points](https://raw.githubusercontent.com/Astn/JSON-RPC.NET/master/benchmarks/charts/headline-1x-vs-2.svg)
+
+| Path | RPC/s | Against 1.2.3 |
+| --- | ---: | ---: |
+| 1.2.3, `Task<string> Process(string)`, thread pool, best batch size | 3.08 M | |
+| 2.0, the same string API and the same loop | 13.3 M | 4.3× |
+| 2.0, `Process(bytes)`, 16 dedicated threads | 31.7 M | 10.3× |
+| 2.0, `ProcessAsync(bytes)`, 16 awaited workers | 32.1 M | 10.4× |
+
+These measurements cover the library without a transport.
+The asynchronous byte row uses methods that complete inline.
+For Kestrel TCP with 256 requests in flight per connection and `EnableAsyncMethods = false`,
+the measured range is 14.3 M to 16.5 M RPC/s on loopback, with clients and server on the same machine.
+
+See the [benchmark tables](https://astn.github.io/JSON-RPC.NET/#benchmarks) for conditions
+and the [benchmark explorer](https://astn.github.io/JSON-RPC.NET/benchmarks/charts/explorer.html) for the data.
+
+## Companion packages
+
+Install only the integrations your host needs. Use matching package versions.
+
+- [`AustinHarris.JsonRpc.Newtonsoft`](https://astn.github.io/JSON-RPC.NET/newtonsoft.html): Json.NET converters, contract resolvers, `[JsonProperty]`, `JsonSerializerSettings` and lenient input.
+- [`AustinHarris.JsonRpc.SystemTextJson`](https://astn.github.io/JSON-RPC.NET/systemtextjson.html): `System.Text.Json` conversion with `JsonSerializerOptions`, reading and writing UTF-8 values.
+- [`AustinHarris.JsonRpc.AspNetCore`](https://astn.github.io/JSON-RPC.NET/aspnetcore.html): HTTP endpoints, raw Kestrel connections over TCP, Unix sockets or named pipes, and dependency injection.
+
+## Upgrading from 1.x
+
+Most service methods can stay as they are. Review these changes before switching:
+
+- Json.NET is now a companion package. Use it for `JsonSerializerSettings` and settings-based
+  compatibility helpers; `JsonRequest.Params` follows the selected serializer's object model.
+- Review string overloads, especially calls with a positional null context.
+  Name the `context` argument explicitly; serializer-taking overloads have changed.
+- Check client-visible behaviour: notifications never return responses, responding batches stay arrays,
+  and version values, named parameters and conversion failures are validated.
+- Unhandled exceptions now return internal errors with exception details hidden by default.
+
+[Upgrading from 1.x](https://astn.github.io/JSON-RPC.NET/upgrading.html) covers every API and wire change, and
+[What is new in 2.0](https://astn.github.io/JSON-RPC.NET/changelog.html) is the full changelog.
+
+## Documentation
+
+- [Server guide](https://astn.github.io/JSON-RPC.NET/)
+- [Hosting](https://astn.github.io/JSON-RPC.NET/#hosting)
+- [Configuration](https://astn.github.io/JSON-RPC.NET/#configuration)
+- [Errors and exception handling](https://astn.github.io/JSON-RPC.NET/#errors)
+- [Asynchronous methods and cancellation](https://astn.github.io/JSON-RPC.NET/#asynchronous-methods-and-cancellation)
+- [Security and host responsibilities](https://astn.github.io/JSON-RPC.NET/#security)
+- [What is new](https://astn.github.io/JSON-RPC.NET/changelog.html)
+- [Upgrading from 1.x](https://astn.github.io/JSON-RPC.NET/upgrading.html)
+- [Source repository](https://github.com/Astn/JSON-RPC.NET)
+- [MIT license](https://github.com/Astn/JSON-RPC.NET/blob/master/LICENSE)