JSON-RPC.Net

A JSON-RPC server has a short job description: read a request, call a method, write a response. The work around that call can be considerably larger. JSON-RPC.Net 2.0 keeps the core at the document boundary: UTF-8 bytes go in, UTF-8 bytes come out, and your application chooses how they travel. The same service can sit behind Kestrel, a pipe, a socket, or a browser page.

For example, send {"jsonrpc":"2.0","method":"add","params":[1,2],"id":1} and the add method returns {"jsonrpc":"2.0","result":3.0,"id":1}. Below, you can run that exchange as a complete server. What does keeping this path in bytes buy us?

The same five small methods were measured through the last 1.x release and through 2.0 in one job on one 32-core host. The ranges show the low and high of that job's runs. Through the same string API and loop, 2.0's median throughput was 6.0× that of 1.2.3. Through 2.0's new byte entry point, the median comparison was 24.3×. Those are different call paths; the table names each one.

The byte path parses the request and writes the reply without making a result string or scheduling a Task for every call. On one thread, the five-request mix averaged a reported 315 ns per request; numeric shapes allocated 0 bytes in the library. Over pipelined Kestrel TCP, the host reached 18.5 M RPC/s. The async and HTTP results in Benchmarks show what each boundary adds.

Here is a server you can put in one file. Save it as server.cs; the #: directives make it a .NET 10 file-based app. Two lambdas become RPC methods, and Kestrel gives them an HTTP endpoint.

#:sdk Microsoft.NET.Sdk.Web
#:package AustinHarris.JsonRpc.AspNetCore@2.0.1

using AustinHarris.JsonRpc;
using AustinHarris.JsonRpc.AspNetCore;

ServiceBinder.BindMethod("add", (double l, double r) => l + r);
ServiceBinder.BindMethod("greet", (string who) => "hello " + who);

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddJsonRpc();

var app = builder.Build();
app.MapJsonRpc("/rpc");
app.Run();

Run dotnet run server.cs -- --urls http://127.0.0.1:5077, then call it from another terminal:

curl -s -X POST http://127.0.0.1:5077/rpc -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}'

{"jsonrpc":"2.0","result":3.0,"id":1}

That is the whole round trip. A request without an id is a notification and gets no response; a batch is an array of requests and gets an array of responses, omitting notifications. On .NET 8, put the same C# code in an ASP.NET Core Program.cs, remove the two #: lines, and install AustinHarris.JsonRpc.AspNetCore.

If your transport already gives you a JSON document, you can call the processor yourself. The byte overload is the native path; the string overload is convenient when the document is already a string.

using System.Buffers;
using System.Text;
using AustinHarris.JsonRpc;

ServiceBinder.BindMethod("add", (int l, int r) => l + r);
var output = new ArrayBufferWriter<byte>();
JsonRpcProcessor.Process(Handler.DefaultSessionId(),
    """{"method":"add","params":[2,3],"id":3}"""u8, output);
Console.WriteLine(Encoding.UTF8.GetString(output.WrittenSpan));

The processor does not open a listener or choose framing. A host that reads several documents from one stream can use JsonFramer; the embedded host sample shows a complete pipe host. The reference covers buffer ownership, cancellation and deadlines.

JSON-RPC.Net is a server for JSON-RPC 2.0. It binds methods, reads documents and writes replies. It does not provide client proxies or server-to-client calls. For a bidirectional RPC framework, StreamJsonRpc serves a different set of needs; the comparison explains what each benchmark measures.

The core has no JSON-library dependency. Its built-in serializer is the default; Json.NET and System.Text.Json are optional packages. The four packages share a version and are MIT licensed:

For an existing project, install the core with dotnet add package AustinHarris.JsonRpc, then add the serializer or ASP.NET Core package you need.

A delegate is enough for a small API, as the first example shows. When methods belong together, mark members of a class with [JsonRpcMethod]:

public class CalculatorService : JsonRpcService
{
    [JsonRpcMethod]
    private double add(double l, double r) => l + r;

    [JsonRpcMethod("multiply")]
    public int Multiply(int l, int r) => l * r;
}

Constructing CalculatorService registers it in the default session; keep that instance alive. The attribute makes even a private method callable by a client, so review every annotated member as part of your public API. Parameters can be positional or named, and optional defaults work for either. One service instance may handle concurrent requests, so shared state needs to be thread-safe. If you prefer to make the wire contract explicit, ServiceBinder.BindInterface<T> can expose methods through an interface tree. The binding reference has the registration rules, names, lifetimes and interface options.

Choose a host for the boundary you already have:

The core leaves transport policy to the host. A raw Kestrel connection does not run HTTP middleware, so it needs authentication and limits at the listener or in front of it. Hosting details cover framing, service lifetimes and cancellation.

Methods may return Task, Task<T>, ValueTask or ValueTask<T>. Use ProcessAsync to await them. In the ASP.NET Core host, set builder.Services.AddJsonRpc(o => o.EnableAsyncMethods = true); the default host uses the synchronous path. The older Task<string> Process(...) compatibility overload schedules synchronous work and does not await an async method.

[JsonRpcMethod("lookup")]
public async Task<Item> Lookup(int id, [JsonRpcCancellation] CancellationToken cancellationToken)
    => await repository.FindAsync(id, cancellationToken).ConfigureAwait(false);

Cancellation is cooperative. The processor waits for a running method to finish, even after its token fires, and cannot undo effects the method has already made. A host sets the deadline; the processor has none of its own. By default, ambient RPC context is available until the first real await. Capture what you need before it, or opt a method into RpcContextFlow.Flow if its accessors must work afterward. Flow has an allocation cost measured in the async benchmark. The async reference covers ownership of buffers and the exact cancellation rules.

Throw JsonRpcException(code, message, data) for an error your client should see. Binding failures use -32602, a missing method uses -32601, and an unhandled method failure becomes -32603.

By default, an unhandled exception sends -32603 Internal Error with data: null: its type and message stay on the server. Config.IncludeExceptionDetails = true includes exception details for trusted development clients. Application-authored JsonRpcException data is sent as supplied. The error reference lists the structured error data and the per-session hooks for reshaping responses.

A session is a named method table with its own serializer and handlers. The default session is enough for an application that owns its process. A plugin or multi-tenant host can bind its own session, route calls to it, and destroy it when the tenant or connection goes away. A session ID chooses methods; it does not authorize a caller. Requests for an unknown session answer “method not found” without creating one. See the session reference for registration and lifetime rules.

The host may pass a context object with each call. Under ASP.NET Core it is an HttpContext or ConnectionContext; a method reads it with Handler.RpcContext(). Capture it before the first await unless context flow is enabled.

A method can read the request's id through Handler.RpcRequestId() or JsonRpcContext.CurrentRequestId() when it needs to correlate work. The request-id reference covers string, integer, null and notification IDs, including the borrowed raw-byte accessor.

The built-in serializer is ready to use. Choose Json.NET or System.Text.Json when your application needs their converters or options; test client-visible requests before switching because accepted values and supported CLR types differ. A serializer can be selected per call, per session or for the process. The jsonrpc version policy and limits are also configurable. By default the core accepts documents up to 4 MiB and batches up to 1024 entries. Configuration details lists the scopes and constructors, and the serializer guide describes the wire behavior.

Every serializer defaults to a maximum JSON depth of 64. The Kestrel host also limits bytes while receiving, before the core sees them. Limits and error behavior explains which bound applies first.

The library redacts unexpected exceptions, rejects oversized documents and batches, and does not create a session for an unknown session ID. Every [JsonRpcMethod] is exposed regardless of C# visibility. One service instance can serve concurrent calls.

The host owns authentication, authorization, TLS, rate limiting, logging and deadlines. On HTTP, use ASP.NET Core middleware and endpoint metadata; raw connections need equivalent controls at the listener. A session ID is routing, not a permission check. The security reference gives the defaults and boundaries in detail.

The core and both serializer packages target netstandard2.0, netstandard2.1, net8.0 and net10.0. The ASP.NET Core package targets net8.0 and net10.0. CI tests .NET 8 and .NET 10 on Windows and Linux; the other runtimes can load the netstandard assets but are outside that test matrix.

The reflection binder is not supported under trimming or Native AOT. A trimmed application can lose bound methods. The WebAssembly sample runs in its documented interpreter and AOT configurations, which do not validate PublishTrimmed or PublishAot for the library. Versioning and support has the release policy.

How much of a request's cost belongs to the server, and how much belongs to everything around it? These results follow the same small calls from a direct byte invocation to awaited methods, Kestrel, and competing frameworks. The summary is a map; each section below says which work its number includes.

The main tables and charts come from one Hugging Face Jobs cpu-performance run: AMD EPYC 7R13, 32 cores (a cgroup quota of all 32 host CPUs), Ubuntu 24.04.5 LTS, .NET 10.0.12, Release, Server GC, built-in serializer. The publish job ran on 2026-09-28 (job 6ab9b3936b030d633f69b0fb, commit 6c3c272). It ran the scaling gate once, the legacy string mode three times, every other mode and benchmarks/Baseline twice, and the connection sweep five times, in sequence. Ranges are the low and high over those runs; a single figure is one that every run rounded to. Each Sync ns figure is the median of the runs' reported costs. The summary's inline Async range also spans different registrations. The explorer shows the medians and individual runs.

TestServer_Console binds five small methods (add, addInt, NullableFloatToNullableFloat, Test2 and StringMe), sends the same five requests through each path, and checks that every reply is a result rather than an error. The WebAssembly figures come from a separate desktop browser run on 2026-09-23. To repeat the publish job or inspect its exact commands, see the benchmark guide; micro-benchmarks show one-request cost and allocations.

Start with the library alone. --sync calls the byte-level JsonRpcProcessor.Process on dedicated threads, measuring parsing, dispatch, binding and response writing without a transport or a per-call scheduler hop. What changes when more cores join the loop?

One thread handled 3.17 M to 3.18 M RPC/s at a reported 315 ns per request. At 32 threads the aggregate reached 44.2 M to 45.7 M RPC/s, while the reported per-thread cost rose to 712 ns as every available core was occupied. Numeric shapes allocated 0 bytes in the library; StringMe returned its own string.

The next question is what ProcessAsync costs when a method can await. --async starts Task.Run workers once, then each worker awaits calls over the same request set as --sync. Most registrations complete inline; yieldsOnce really awaits Task.Yield() on every request. The last column includes the service method's own allocations at one worker, so it measures the whole call shape.

The 32-worker inline rows mix the five requests equally; yieldsOnce is one request shape. The per-method allocation table below makes the source of those bytes easier to see. Each value is bytes per request at one worker, including method allocations.

With RpcContextFlow.None, the dispatcher adds no allocation when a method completes inline. The Task<T> None row includes the service's Task.FromResult allocations (Task<int> for 8 uses the runtime cache); StringMe allocates its 32-byte result string. Flow allocates invocation and execution-context state even for an inline completion. An actual suspension also needs completion state in the method, result writer, handler and processor: yieldsOnce under None measured 548 B per request at one worker, including the method.

A lock explains why the async path needed a scaling test. Before 2.0.0, one lock on a shared scratch pool capped ProcessAsync near 4 M RPC/s at every worker count; a single-thread benchmark could not reveal it. A per-thread scratch slot removed that bottleneck. The scaling gate measured 1.3 with the lock and 12.1 to 13.1 at 32 workers with the cache (medians on 2026-09-28). It tests inline methods across worker counts and serializers before release; the benchmark guide has the gate and diagnostic commands.

The 1.x compatibility overload pays for work the byte path avoids. The t mode sends batches through Task<string> Process(string) from every core. Each request pays for transcoding, a thread-pool hop, a Task, a result string and a continuation. The table varies batch size after a one-second warm-up, timing each size for at least half a second. More queued work helps until the queue itself becomes the cost.

That peak is below the byte paths because this mode measures the thread pool and string API as well as dispatch. The ASP.NET Core host uses bytes and awaits transport reads and flushes; its results bring the network boundary into view.

What changes when the call goes through a real host? --kestrel starts Kestrel on loopback with the HTTP endpoint and raw connection handler, then drives it from one client per core (32 on this host). The client and server share a loopback machine and compete for its cores, so these are local results rather than remote end-to-end predictions. The in-process row provides scale. The default host calls Process; the async rows enable ProcessAsync, first with methods that complete inline and then with methods that await Task.Yield().

One HTTP POST per call spends most of its time on the round trip: 156 k to 162 k RPC/s, versus 14.4 M to 14.8 M when each POST contains a batch of 100. Raw TCP with 256 pipelined requests reached 18.5 M. The host processes documents in order on each connection; enabling async methods preserves that order. When every method actually suspends, each pipelined request pays for its own continuation, and the TCP row falls to 2.86 M to 2.87 M. The publish job tracks that suspended row for regressions; the benchmark guide describes the gate.

The comparison needs a little care. StreamJsonRpc is Microsoft's full bidirectional JSON-RPC framework, used by Visual Studio and language-server tooling. --compare gives it and JSON-RPC.Net the same five requests on Kestrel TCP, one connection per core (32 here) and 256 requests in flight per connection. StreamJsonRpc requires "jsonrpc":"2.0", so these requests include it and the JSON-RPC.Net row sits below its other TCP measurements. The rows retain each library's named formatter and framing; they compare complete server paths.

The same run hosts gRPC for .NET on Kestrel with the corresponding five calls from calculator.proto. Its Grpc.Net.Client uses one channel per core and 256 calls in flight per channel. Each row ran twice for 3 s; the table shows both results as a range.

StreamJsonRpc 2.25.29 used its defaults apart from the formatter and framing named in each row. Its fastest row reached 1.06 M to 1.15 M RPC/s; JSON-RPC.Net answered the same five calls at about 15× that rate on the same connections. StreamJsonRpc also provides client proxies, cancellation, progress, marshaled objects and events. JSON-RPC.Net used its built-in serializer while the fastest StreamJsonRpc rows used System.Text.Json. This is a whole-server comparison; JSON-RPC.Net with its System.Text.Json serializer was measured separately and is not in the table.

gRPC for .NET 2.84.0 used default settings except Kestrel's MaxStreamsPerConnection, raised to 256 so the pipeline depth was not capped at 100. Protobuf has no decimal, so Test2 used the units/nanos DecimalValue message recommended in the gRPC docs; nullable values used proto3 optional.

These gRPC rows include Grpc.Net.Client running on the same cores as the server. They measure what a .NET caller and service achieve end to end, while the JSON-RPC TCP rows use a lightweight raw client. In the sweep, one gRPC channel handled 136 k to 143 k unary calls per second and eight handled 338 k to 357 k; additional channels competed with the server for the same cores. The streaming row batched writes (BufferHint on every message except the last in a refill) and the server flushed when its input ran dry, matching the TCP handler's once-per-read-group flush.

In-process paths: a direct call, a Pipe pair and a typed proxy (different boundaries, not comparable with the rows above)

Path	RPC/s
JSON-RPC.Net in-process, 1 thread (direct call, bytes in, bytes out)	2.97 M to 3.01 M
StreamJsonRpc in-process, 1 client over a Pipe pair, newline framing, System.Text.Json formatter, 256 pipelined	133 k to 154 k
StreamJsonRpc typed proxy, sequential await per call, in-process pipes	53.7 k to 56.2 k (18 to 19 µs per round trip)

StreamJsonRpc's server side has no "document in, document out" call, so its in-process row is a pair of System.IO.Pipelines pipes, the closest it has to a direct call; the proxy row is one call at a time, so it measures a round trip, not throughput. The direct-call row comes from --compare and sits a little below the Sync table's 1-thread figure.

What happens between one connection and 32? --sweep repeats the networked library and transport paths at each power-of-two connection count (channels for gRPC). The chart uses five 2 s runs per point, a median marker and a low-to-high whisker. Sweep files also record system, process and dedicated TCP-client CPU shares, because a busy client can limit what reaches the server.

The sweep ran in the same job as the tables, with a 2 s warm-up and 2 s timed window per cell. The TCP result is near its comparison-table row: JSON-RPC.Net measured 17.3 M to 17.8 M at 32 connections, versus 16.4 M to 16.8 M in the comparison table. The gRPC sweep results are higher: unary 269 k to 290 k versus 158 k to 166 k; streaming 893 k to 913 k versus 703 k to 733 k. The cause is not pinned down, so the comparison table keeps its original figures.

The scaling pattern is the reason for this chart. JSON-RPC.Net over TCP rises from a 1.58 M median at one connection to 17.5 M at 32; batched HTTP goes from 744 k to 14.6 M. StreamJsonRpc gains 5 to 6× from one to 32 connections, with its two Content-Length paths leveling off after 16. gRPC unary peaks at eight channels, while its stream climbs to 902 k at 32.

The benchmark explorer is the same data as an interactive page: toggle series, hover or tab to a point for the exact low, median, high and every run, switch the axis between log and linear, and download the data. It is one self-contained HTML file, benchmarks/charts/explorer.html, so it also works saved to disk.

The browser changes the boundary again. The WasmHost sample compares the same add(1, 2) through JSON-RPC and plain Blazor interop in Chrome, under the .NET 10 interpreter and AOT. Interpreted, plain DotNet.invokeMethod took about 64 µs including Blazor's JSON marshalling, a UTF-8 JSON-RPC document written directly into WebAssembly memory through [JSExport] took 53 µs, and a batch of 100 reached 27 k RPC/s. AOT changed those three results to 15 µs, 7 µs and 210 k RPC/s; a typed [JSExport] add took 0.3 µs either way. The sample README has the table and chart.

One parser experiment did not help. simdjson was evaluated as a fourth parser and not adopted: through the .NET binding tested here, its parse alone costs more than the whole built-in envelope read, and walking the result is 5 to 6 times slower with 350 bytes or more of garbage per request. The harness and numbers are in benchmarks/SimdJsonEval/RESULTS.md.

The current tables come from the 2026-09-28 cloud job. Earlier measurements used a desktop and different harness configurations, so they tell the development story rather than extend the current comparison.

Most 1.x services run unchanged. Upgrading from 1.x lists the changes that break the build, the changes clients will see on the wire and the behaviour changes inside your server. Read the first list before you build and the second before you deploy next to existing clients. CHANGELOG.md is the record of every change per version.

The four 2.x packages are released together at one version; use matching versions. Public API and documented wire behavior follow Semantic Versioning. There is no fixed release cadence. A preview (2.0.0-preview.N) is tested but may change API before the stable release it precedes; 1.x receives no further releases.

Obsolete members warn with a JSONRPC0xxx diagnostic and a link to the replacement. They remain warnings through 2.x and are removed in the next major version. CHANGELOG.md records changes. Report vulnerabilities privately through SECURITY.md; use GitHub issues for questions and bugs.

CI tests net8.0 and net10.0 on Windows and Linux. Other runtimes can load the netstandard assets but are outside that test matrix. Trimming and Native AOT remain unsupported until the reflection binder is annotated and validated in CI, planned alongside a source generator for 2.8; a trimmed host today can lose bound methods.

Use the .NET 10 SDK pinned in global.json and the .NET 8 runtime for the net8.0 tests:

dotnet build AustinHarris.JsonRpc.sln
dotnet test AustinHarris.JsonRpcTestN

The suite runs protocol cases across the built-in, Json.NET and System.Text.Json serializers, plus parser, dispatch, version-policy and Kestrel tests, on both targets. A Release build of a package project writes its NuGet package under bin/Release/. The WebAssembly sample builds without wasm-tools; add that workload for AOT.

The tables and charts are generated from benchmarks/charts/benchmarks.json. python benchmarks/charts/render.py --check verifies that the published figures and generated assets agree. The benchmark guide describes the publish, fetch and rendering steps.

MIT. See LICENSE. The built-in serializer's tokenizer is a C# port of jsmn, copyright Serge A. Zaitsev, under the MIT license; its notice is in THIRD-PARTY-NOTICES.txt, which also ships in the AustinHarris.JsonRpc package.