DEV Community: Jeff Tsai

A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?

Jeff Tsai — Tue, 13 Oct 2026 12:09:53 +0000

JSON-RPC 2.0 is a small specification: the client sends {"jsonrpc":"2.0","method":"...","params":{...},"id":1}, and the server answers with a result or an error. REST makes you decide on routes, HTTP verbs and status codes; JSON-RPC only cares about which method to call and with what parameters. For an API where you own both the front end and the back end, that is pleasant to work with.

Polhem.JsonRpc is a set of .NET packages for JSON-RPC 2.0: a transport-independent server, an ASP.NET Core endpoint and a client, built on System.Text.Json alone. It started as the API layer of the Polhem framework. I have now extracted it into standalone packages that do not depend on the framework, so other projects can reference them directly. The source is on GitHub under the MIT license, and the packages are on NuGet.

1️⃣ What it covers

Full JSON-RPC 2.0: ordinary calls, notifications (calls that expect no response), and batches (several calls in one message). An id can be a string, an integer or null.
A transport-independent server: the dispatcher (the part that finds and runs the method) knows nothing about HTTP. The ASP.NET Core endpoint is a separate package.
A client: an HTTP transport, batches, notifications, and interceptors that can rewrite the parameters and result of each call.
Optional payload encryption: the parameters and result go into an envelope that can be compressed and encrypted, and replayed calls can be rejected.

It is split into several NuGet packages, so an application references only what it needs:

Package	Use
Polhem.JsonRpc	Message types, error codes and the transport abstraction shared by the server and the client
Polhem.JsonRpc.Server	The dispatcher: method resolution, parameter binding and filters
Polhem.JsonRpc.AspNetCore	The ASP.NET Core endpoint, `MapJsonRpc`
Polhem.JsonRpc.Client	The client, `JsonRpcConnector`
Polhem.JsonRpc.Payload	Optional: the payload envelope, compression, encryption and replay protection
Polhem.JsonRpc.Payload.Client	Optional: a client that seals the parameters and opens the result of every call
Polhem.JsonRpc.Payload.Server	Optional: opens the envelope and checks for replays on the server

The server references Polhem.JsonRpc.AspNetCore, and the client references only Polhem.JsonRpc.Client. The split keeps a client, whether a desktop app or a mobile app, from pulling in ASP.NET Core and the reflection-based dispatcher.

Native AOT compiles an app to native code at publish time, so nothing can rely on reflection at run time; iOS and WebAssembly both need it. The shared package, the client and the payload packages are marked AOT-compatible, and CI publishes a test program with Native AOT and runs it. The server package finds methods by reflection, so it does not support AOT. The target framework is net10.0.

2️⃣ Getting started

ASP.NET Core server (Minimal API)

The server uses ASP.NET Core Minimal APIs (endpoints mapped directly in Program.cs with MapXxx, without MVC controllers). MapJsonRpc creates a POST endpoint at the given path, and every JSON-RPC call comes in through it. AddControllers is not needed.

Program.cs needs three things: register the object factory, register the JSON-RPC services, and map the endpoint.

using Polhem.JsonRpc.AspNetCore;
using Polhem.JsonRpc.Server;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IJsonRpcObjectFactory, AppObjectFactory>();
builder.Services.AddJsonRpcServer();

var app = builder.Build();
app.MapJsonRpc("/api");
await app.RunAsync();

AddJsonRpcServer takes two sets of options. The first configures the server itself, such as filters, the method policy, the batch limit and serializer options. The second configures the HTTP endpoint, such as the request body size limit and which HTTP status code an error returns. Leave them out and the defaults apply.

builder.Services.AddJsonRpcServer(
    options =>
    {
        options.MaxBatchSize = 50;
        options.Filters.Add(new ApiKeyFilter(apiKey)); // see section 5
    },
    http => http.MaxRequestBodySize = 1024 * 1024);

MapJsonRpc returns the same thing as any other Minimal API endpoint, so authorization, CORS and rate limiting chain on the usual way, for example app.MapJsonRpc("/api").RequireAuthorization();.

The object factory and the class that handles the calls:

public sealed class AppObjectFactory : IJsonRpcObjectFactory
{
    public object? CreateObject(string progId, JsonRpcRequestContext context) => progId switch
    {
        "Calculator" => new Calculator(),
        _ => null,
    };
}

public sealed class Calculator
{
    public AddResponse Add(AddRequest request) => new() { Sum = request.A + request.B };
}

Client

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:5080/api") };
var rpc = new JsonRpcConnector(new HttpTransport(http));

var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", new AddRequest { A = 1, B = 2 });

That is enough to call Calculator.Add. Note that the server has no AddMethod or similar registration, and Calculator carries no attribute.

3️⃣ With no registration, which methods can be called?

Skipping registration is convenient, but it raises a worry: if one day I add a public method to the class for internal use, can it be called from the network too? When the server receives Calculator.Add, it runs the following checks in order.

Name format. The method name must be ProgId.Action. A ProgId (program identifier) may contain letters, digits, underscores and hyphens; an action letters, digits and underscores; each at most 64 characters. A malformed name is rejected before any lookup.

The application decides the object. The ProgId is passed to your implementation of IJsonRpcObjectFactory.CreateObject, which decides which object to create; returning null means the ProgId is unknown. The packages keep no registry of names, so which ProgIds exist is entirely up to the factory. After the call, the object is passed to ReleaseObjectAsync to be released.

Method signature. An action maps only to a public, non-generic instance method with exactly one parameter. Static methods, property accessors and methods declared by object do not count. If two or more methods with the same name qualify, the server does not pick one; it treats the method as not found.

Naming convention. The parameter type must be named {Action}Request, and the return type (or the result type of Task<T> or ValueTask<T>) must be named {Action}Response. Add takes an AddRequest and returns an AddResponse. This is the default method policy; any public method that does not follow it is treated as nonexistent and answered with -32601 Method not found. An internal helper method that does not follow this naming cannot be called from outside.

The rule can be replaced through JsonRpcServerOptions.MethodPolicy. The Polhem framework replaces it with one that reads its own access-control attribute.

Policy before filters. The method policy runs before every filter, so filters such as authorization checks or decryption only ever see calls that are allowed to run.

Only after these checks are the params bound. params must be a JSON object, deserialized into the request class with camelCase names by default; missing params or an array (positional parameters) are answered with -32602 Invalid params. To return a custom error, a method throws JsonRpcErrorException; any other exception is answered with -32603 Internal error, and the exception message is not sent to the client.

4️⃣ The client

An error returned by the server becomes a JsonRpcErrorException, which carries the error code and message:

try
{
    await rpc.InvokeAsync<DivideResponse>("Calculator.Divide", new DivideRequest { Dividend = 1, Divisor = 0 });
}
catch (JsonRpcErrorException ex)
{
    Console.WriteLine($"Error {ex.Code}: {ex.Message}");
}

Notifications and batches:

// The server runs it but does not respond.
await rpc.NotifyAsync("Calculator.Log", new LogRequest { Message = "Hello" });

// Two calls sent in the same message.
var batch = rpc.CreateBatch();
var first = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 2, B = 3 });
var second = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 4, B = 5 });
await batch.SendAsync();
Console.WriteLine($"{(await first)!.Sum}, {(await second)!.Sum}");

The request and response classes usually live in a project shared by both sides, which is how the samples in the repo are arranged.

5️⃣ Extension points: filters and interceptors

A server filter wraps every call. It can reject the call, rewrite the parameters before the method runs, and rewrite the result afterwards. For example, checking an API key:

public sealed class ApiKeyFilter(string expectedKey) : IJsonRpcFilter
{
    public ValueTask InvokeAsync(JsonRpcRequestContext context, JsonRpcFilterDelegate next)
    {
        context.Transport.Headers.TryGetValue("X-Api-Key", out var key);
        if (!CryptographicOperations.FixedTimeEquals(
                Encoding.UTF8.GetBytes(key ?? ""), Encoding.UTF8.GetBytes(expectedKey)))
        {
            throw new JsonRpcErrorException(-32001, "Unauthorized");
        }
        return next(context);
    }
}

builder.Services.AddJsonRpcServer(options => options.Filters.Add(new ApiKeyFilter(apiKey)));

To add an HTTP header on the client, use HttpClient's own DelegatingHandler; the packages add no layer of their own. To rewrite the parameters and result of every call, add an IJsonRpcClientInterceptor.

The Polhem framework plugs its sessions and authorization checks into these extension points (the object factory, the method policy and filters). None of that logic is in the packages themselves.

6️⃣ Encrypted payloads

HTTPS protects the connection. If the parameters and results also need end-to-end protection, or a call must not run a second time when it is resent, add the optional payload packages.

They put params and result into an envelope with three formats: plain JSON, encoded (serialized, then gzip-compressed), and encrypted (AES-256-CBC with HMAC-SHA256, encrypt-then-MAC). A frame carrying a timestamp and a sequence number can also be put in front of the content, so the server can reject expired or repeated requests; that is the replay protection.

// Server: the application's policy decides the keys and which methods must be encrypted or replay-protected.
builder.Services.AddJsonRpcServer(options => options.UsePayload(payloadOptions, new MyPayloadPolicy()));

// Client: called the same way as an ordinary call; each call seals its parameters and opens its result.
var rpc = new PayloadConnector(connector, new PayloadProcessor(payloadOptions),
    new PayloadConnectorOptions { KeyProvider = () => sessionKey });
var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", request);

A few more security details:

The HMAC is compared in constant time and verified before anything is decrypted.
The HMAC covers the method name and the direction, so an intercepted call cannot be redirected to another method, and a response cannot be sent back as a request.
A method can require a minimum format; a request in a lower format is rejected before any key is asked for.

How keys are negotiated (exchanged after sign-in, provisioned in advance, and so on) is outside the packages and left to the application.

7️⃣ How it differs from common libraries

There are quite a few JSON-RPC libraries for .NET; here are two common ones for comparison. The version in each column header is the latest stable release on NuGet as of October 2026, and the details come from that release's documentation and NuGet dependency list. Later releases may differ.

	StreamJsonRpc 2.25.29	Tochka.JsonRpc 7.4.1	Polhem.JsonRpc 1.2.0
JSON library	Newtonsoft.Json by default, switchable to System.Text.Json; the package still depends on Newtonsoft.Json and MessagePack	System.Text.Json	System.Text.Json, with no other dependencies
Transport model	Full duplex over a Stream, WebSocket or Pipe	HTTP on ASP.NET Core MVC	HTTP request and response on ASP.NET Core Minimal APIs
Client	Yes, with proxies generated from interfaces	Yes	Yes
How methods are registered	`AddLocalRpcTarget` adds a target object whose public methods become callable	Controllers that inherit `JsonRpcControllerBase`; each action is a method	No registration; found by `ProgId.Action` and the naming convention
Native AOT	Partially supported, within the limits its documentation lists	Tied to MVC, not supported	The shared package, the client and the payload packages support it; the server does not
Good fit	Two-way communication, such as Visual Studio extensions or LSP	You already use MVC and want to keep writing controllers	An API where you own both ends, possibly with desktop or mobile clients

StreamJsonRpc is the most complete, with cancellation, progress reporting and server-to-client calls, but it is designed for streams and full duplex; turning it into an HTTP request/response API means building the endpoint yourself.

Tochka.JsonRpc is the closest in scope to Polhem.JsonRpc. It builds on MVC controllers, so MVC filters and model binding work as they are, at the cost of sharing MVC's lack of AOT support.

Polhem.JsonRpc goes in a different direction: it trades a fixed call shape for "no registration" and "an API that can evolve", as the next section explains.

8️⃣ Design trade-offs

The fixed call shape is there so the API can evolve. The ProgId.Action name, one request class and one response class are a deliberate restriction. When a member is added to a request or response class, a member an older front end does not send binds to its default on the server, and a result member an older front end does not know is simply skipped when read. Old and new front ends call the same method, with no v1 and v2 endpoints to maintain. Positional parameters cannot do this: add, remove or reorder one parameter and every caller has to change.

Defaults follow the specification. The internal error code is -32603, a response carries only jsonrpc, result or error, and id, and id is always written, as null when it cannot be determined. The Polhem framework's original response format differed from the specification in places; when the packages were extracted, it was the framework that changed to follow the specification, not the packages that bent to the old format.

The reasoning behind each decision is recorded as ADRs (Architecture Decision Records) in the repo's maintainers/adr/, and the security design is summarized in docs/security.md.

✅ Wrapping up

Install the server and client packages:

dotnet add package Polhem.JsonRpc.AspNetCore
dotnet add package Polhem.JsonRpc.Client

The repo includes samples: an ASP.NET Core Minimal API server, a console client (ordinary calls, error handling, notifications and batches), and a server and client using encrypted payloads.

These packages do convention-based JSON-RPC, not general-purpose JSON-RPC. Protocols whose method names and parameters are defined by someone else, such as the Language Server Protocol, MCP or an Ethereum node's API (names like textDocument/didOpen and eth_call with positional parameters), cannot be implemented with them; StreamJsonRpc or the MCP C# SDK fit those better. Nor do they offer a full-duplex connection where the server calls the client: one call is one HTTP request and its response.

If you own both ends of your API, want JSON-RPC that relies on System.Text.Json alone, or have clients that run as desktop or mobile apps, give it a try. Feedback, issues and pull requests are welcome.

One OAuth2 Library for Every Kind of .NET App

Jeff Tsai — Tue, 13 Oct 2026 11:44:12 +0000

Adding "Sign in with Google" to a .NET application looks like a problem that was solved long ago, until you have more than one kind of application. A website uses ASP.NET Core's authentication handlers, a desktop tool needs something that can open a browser and catch the callback, a mobile app does it another way again, and none of these help the old Web Forms site that is still in production.

I wanted a small library that handles all of these in the same way, so I built Polhem.OAuth2. It is open source under the MIT license and available on NuGet.

If you have used Bee.OAuth2, Polhem.OAuth2 is its successor. It keeps the idea of one set of options per provider (the sign-in service, such as Google or LINE), and most of the rest has been rebuilt. Section 6 lists what changed.

1️⃣ What it covers

Desktop and console apps: opens the system browser, receives the callback on a loopback address (127.0.0.1 or localhost on the local machine), and uses PKCE. Runs on Windows, macOS and Linux.
.NET MAUI apps on Android, iOS and Mac Catalyst: signs in through WebAuthenticator with PKCE, and keeps no client secret in the app. An app with its own ASP.NET Core back end can sign in through that back end instead, so the provider's tokens never reach the device.
ASP.NET Core: the authorization code flow with PKCE, with the state of each sign-in kept in its own protected cookie.
Classic ASP.NET: the same flow for Web Forms and MVC applications on System.Web.
Other server frameworks: the core OAuth2Client runs the flow in two steps and does not depend on any HTTP framework.

PKCE (Proof Key for Code Exchange) is an extension to OAuth2. The client generates a random value when it starts the sign-in and presents it again when it exchanges the code for tokens, so an intercepted authorization code is useless without that value. For desktop and mobile apps, which cannot keep a client secret, it is essential.

Supported providers: Google, Facebook, LINE, Microsoft Entra ID, Auth0 and Okta. Every provider returns the result in the same shape: the user ID, name and email, plus the access, refresh and ID tokens.

Package	Target frameworks	Use
Polhem.OAuth2	netstandard2.0, net10.0	The providers; desktop, console and .NET MAUI apps; other server frameworks
Polhem.OAuth2.AspNetCore	net10.0	ASP.NET Core
Polhem.OAuth2.AspNet	net472	ASP.NET Web Forms and MVC on `System.Web`

2️⃣ Desktop or console apps

LoopbackOAuth2Client listens on the redirect URI, opens the sign-in page in the default browser, waits for the provider to redirect back, and exchanges the authorization code:

using Polhem.OAuth2;

var options = new GoogleOAuth2Options
{
    ClientId = "your-client-id",
    ClientSecret = "your-client-secret",
    RedirectUri = "http://127.0.0.1:0/callback"
};

var client = new LoopbackOAuth2Client(options);
AuthorizationResult result = await client.SignInAsync();

if (result.IsSuccess)
    Console.WriteLine($"{result.UserInfo.UserId} {result.UserInfo.UserName} {result.UserInfo.Email}");

Port 0 picks a free port for each sign-in. This only works with providers that accept any loopback port, such as Google. For other providers, use the port you registered.

3️⃣ ASP.NET Core apps

builder.Services.AddOAuth2Client("Google", new GoogleOAuth2Options
{
    ClientId = "your-client-id",
    ClientSecret = "your-client-secret",
    RedirectUri = "https://localhost:7032/auth/callback"
});

Then start and complete the sign-in with two actions:

public class AuthController(OAuth2Manager oauth2Manager) : ControllerBase
{
    [HttpGet("/auth/login")]
    public IActionResult Login()
    {
        return Redirect(oauth2Manager.CreateAuthorizationUrl(HttpContext, "Google"));
    }

    [HttpGet("/auth/callback")]
    public async Task<IActionResult> Callback()
    {
        AuthorizationResult result = await oauth2Manager.CompleteAuthorizationAsync(HttpContext, HttpContext.RequestAborted);
        return result.IsSuccess
            ? Content($"Hello, {result.UserInfo.UserName}")
            : Content($"The sign-in failed: {result.Exception.Message}");
    }
}

The state, PKCE code verifier and redirect URI of each sign-in are kept in their own cookie, encrypted with ASP.NET Core Data Protection. So no session is needed, sign-ins started in several tabs at once do not overwrite each other, and several servers can work together as long as they share the Data Protection keys.

4️⃣ .NET MAUI apps

Anything inside a mobile app can be extracted, so it cannot keep a client secret. AppOAuth2Client therefore always uses PKCE and never sends a client secret. You pass it a function that opens the browser, which is usually WebAuthenticator:

var options = new Auth0OAuth2Options
{
    Domain = "your-tenant.auth0.com",
    ClientId = "your-native-client-id",
    RedirectUri = "com.example.app:/oauth2redirect"
};

var client = new AppOAuth2Client(options, async (url, redirectUri, cancellationToken) =>
    (await WebAuthenticator.Default.AuthenticateAsync(url, redirectUri)).CallbackUri);

AuthorizationResult result = await client.SignInAsync();

If the app signs in to its own back end, the back end can complete the sign-in as a web client and hand the app a one-time code. The app exchanges that code for the user's information, and the provider's tokens stay on the server.

5️⃣ Design decisions

A few decisions shape how the library behaves:

PKCE is on by default, and every provider endpoint must use https.
Options are checked when the client is created. Invalid options throw immediately, which in ASP.NET Core means at application startup rather than at the first sign-in.
Expected failures are returned in the result, and only programming errors throw. A failed HTTP request, a state mismatch or an error from the provider ends up in result.Exception. An unregistered client name is a programming error and throws.
Users are identified by provider plus user ID, not by email. Emails change, and providers differ in whether they verify them.
Few dependencies: the net10.0 build of the core package has no package dependencies, the public API has nullable annotations, and the net10.0 build is checked with the trim and AOT analyzers (which confirm it still works when unused code is trimmed at publish and it is compiled ahead of time to native code).

The reasoning behind each decision is written up as an ADR (Architecture Decision Record) in the repo's docs/adr/.

6️⃣ Coming from Bee.OAuth2

Five packages became three: Bee.OAuth2.WinForms and Bee.OAuth2.Desktop are replaced by LoopbackOAuth2Client in the core package.
Desktop sign-in now uses the system browser instead of an embedded WebView2 window. Users can see the address bar and keep their existing sessions and password manager, and the app cannot see what they type. Google's policy already rejects embedded browsers, and with WebView2 gone, desktop sign-in is no longer tied to Windows.
Web sign-in no longer needs a session or the OAUTH2_STATE_KEY environment variable. Each sign-in has its own cookie, protected by ASP.NET Core Data Protection or MachineKey.
One-line registration in ASP.NET Core: AddOAuth2Client replaces the OAuth2Manager singleton you used to assemble by hand.
Okta and .NET MAUI support are new.
No more dependency on Bee.Base or Newtonsoft.Json. JSON is now parsed with System.Text.Json.

The README has a migration guide that maps each old type and method to its replacement.

✅ Wrapping up

Install the core package:

dotnet add package Polhem.OAuth2

The README covers each kind of application, including how to register the redirect URI with each provider. The repo also includes sample apps: a console app, Windows Forms on .NET and on .NET Framework, ASP.NET Core, and .NET MAUI.

The library only handles signing in and getting the user's information and tokens. It does not validate the ID token's signature, and it does not manage accounts or permissions after sign-in. If your project is already well served by ASP.NET Core's built-in authentication or an OpenID Connect package, you may not need to switch. It fits best when you have desktop, mobile and web applications at the same time and want to write sign-in the same way in all of them. Feedback, issues and pull requests are welcome.

DEV Community: Jeff Tsai

A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?

1️⃣ What it covers

2️⃣ Getting started

ASP.NET Core server (Minimal API)

Client

3️⃣ With no registration, which methods can be called?

4️⃣ The client

5️⃣ Extension points: filters and interceptors

6️⃣ Encrypted payloads

7️⃣ How it differs from common libraries

8️⃣ Design trade-offs

✅ Wrapping up

Further reading

One OAuth2 Library for Every Kind of .NET App

1️⃣ What it covers

2️⃣ Desktop or console apps

3️⃣ ASP.NET Core apps

4️⃣ .NET MAUI apps

5️⃣ Design decisions

6️⃣ Coming from Bee.OAuth2

✅ Wrapping up

Further reading