HttpJsonRpc 3.0.0

dotnet add package HttpJsonRpc --version 3.0.0
                    
NuGet\Install-Package HttpJsonRpc -Version 3.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="HttpJsonRpc" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="HttpJsonRpc" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="HttpJsonRpc" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add HttpJsonRpc --version 3.0.0
                    
#r "nuget: HttpJsonRpc, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package HttpJsonRpc@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=HttpJsonRpc&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=HttpJsonRpc&version=3.0.0
                    
Install as a Cake Tool

HttpJsonRpc

HttpJsonRpc is a cross-platform, .NET Standard library that implements the JSON-RPC 2.0 Specification, as well as streaming (up and down), on top of HTTP.

It makes it simple to create high performance, robust, light-weight API's that can be hosted in any project type. It uses ASP.NET Core Kestrel internally without requiring an ASP.NET application project.

HttpJsonRpc also has extensibility points for logging and dependency injection, so you can use your favorite frameworks.

Getting Started

  1. Create a class that will hold your JsonRpc methods with the JsonRpcClassAttribute.
[JsonRpcClass("math")]
public static class MathApi
{
    [JsonRpcMethod]
    public static Task<int> SumAsync(int n1, int n2)
    {
        var result = n1 + n2;

        return Task.FromResult(result);
    }
}
  1. Call the JsonRpc.Start method to start listening for JSON-RPC requests over HTTP.
class Program
{
    static void Main(string[] args)
    {
        JsonRpc.Start();

        Console.ReadLine();
    }
}
  1. The ideal way to call JSON-RPC methods is using an HTTP POST with the JSON-RPC Request in the HTTP Body but HttpJsonRpc also supports URL Parameters for simple method calls. Test the method by pasting the URL in a browser.
http://localhost:5000/?method=math.sum&n1=2&n2=2

You should get the result in JSON.

{
    "jsonrpc": "2.0",
    "result": 4
}

When calling your method in code or Postman use an HTTP POST with the JSON-RPC Request in the HTTP Body.

{
	"jsonrpc": "2.0",
	"method": "math.sum",
	"params": {
		"n1": 2,
		"n2": 2
	},
	"id": "1"
}
  1. You can add your favorite logging provider by setting the JsonRpc.LoggerFactory property. This sample uses Serilog.
Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .CreateLogger();

JsonRpc.LoggerFactory = new LoggerFactory().AddSerilog();
JsonRpc.Start();
  1. You can find more code samples here.

Hosting and middleware

Configure the library before calling JsonRpc.Start(). Registration and option changes are startup operations; do not mutate callbacks, converters, or the method registry while requests are running.

JsonRpc.Options.ConfigureApplication = app =>
{
    // Register ASP.NET Core middleware before CORS and the RPC handler.
};
JsonRpc.Start();
// When shutting down:
await JsonRpc.StopAsync();

The library uses ASP.NET Core Kestrel internally and targets .NET Standard 2.0. It can be hosted by .NET Framework 4.8 and modern .NET applications. StopAsync stops and disposes the host. Repeated stop calls are safe; starting an already-running host throws. Registrations persist across restarts. ListeningAddresses reports bound addresses, including dynamically allocated ports.

When using forwarded headers, add Microsoft.AspNetCore.HttpOverrides in the consuming application and register UseForwardedHeaders through this callback. Configure trusted proxies/networks there; HttpJsonRpc does not trust forwarded headers itself. Authentication and authorization remain the host application's responsibility. CORS is not authentication.

Request handling and lifecycle

To finish a request without invoking an RPC method, set JsonRpcContext.Current.Handled = true in OnReceivedHttpRequest, or context.Handled = true in OnReceivedRequest, and prepare the HTTP response. Started responses, explicit content lengths (including zero), and HTTP errors also stop dispatch. Alternatively throw JsonRpcUnauthorizedException to return an RPC unauthorized error.

  • OnCompletedRequest remains a success-only callback. For batch calls it runs after successful result construction, before the aggregate HTTP response is written.
  • OnRequestFinished runs on success, failure, rejection, or cancellation. For a dispatched batch it runs once per processed item; if parsing or HTTP rejection prevents dispatch, it runs once for the HTTP request. Use it for cleanup and diagnostics. context.Exception identifies a processing failure.
  • JsonRpcContext.Current is scoped to the request. Do not retain its HttpContext after completion.
  • Instances created with Activator are disposed after finished callbacks. Instances returned by CommonServiceLocator remain container-owned.
  • Returned streams are library-owned and disposed after writing. Bytes are copied from the current position. The response body itself remains server-owned.
  • A CancellationToken RPC parameter receives HttpContext.RequestAborted automatically and is not exposed as a wire parameter. Methods should observe cancellation; the library cannot forcibly stop application code.

Protocol behavior

JsonRpc.Options.StrictProtocol defaults to false for existing clients that use GET requests, omitted protocol versions, case-insensitive method lookup, and id-less calls expecting replies.

Set it to true to validate JSON-RPC 2.0 request fields, use case-sensitive method lookup, validate extra arguments, and suppress replies to notifications (requests without id). A notification-only HTTP request returns status 204. Both modes use corrected response envelopes and error codes: parse error -32700, invalid request -32600, missing method -32601, invalid parameters -32602, internal error -32603. Application authorization uses the existing code 1.

Batches execute sequentially and preserve individual request IDs. MaxBatchSize defaults to 100. Query-string merging is not supported for batches. Streaming results cannot be represented in a JSON batch and produce a per-item error; use individual calls for downloads. Methods in a batch are independent, not a transaction. Cancellation prevents further items from starting.

GET/query requests, raw binary uploads and stream downloads are HTTP extensions, not portable JSON-RPC behavior. Standard multipart requests may contain exactly one JSON field called request; framework form limits apply. Raw binary upload methods can read the request body directly using a query-based method selector and a non-JSON/non-form content type.

RPC methods support synchronous values/void, Task, Task<T>, ValueTask, and ValueTask<T>. Generic methods, ref/out/pointer signatures, and async-void methods are rejected during registration. Explicit method names are preserved; only an inferred trailing Async suffix is removed. For [JsonRpcParams] objects, use System.Text.Json property naming attributes to control the serialized names.

Error disclosure

Both IncludeStackTraceInErrors and IncludeExceptionMessagesInErrors default to false. Error callbacks and logging still receive the original exception. Opt in explicitly for trusted development environments, or provide a JsonRpcErrorFactory that exposes only approved application messages. Changing this setting can affect applications that display server exception messages to users; see migration notes.

OpenRPC discovery

Enable JsonRpc.Options.OpenRpc.IsEnabled to expose rpc.discover. Method filters limit discovery output; they do not enforce authorization when a method is invoked. Generated documents declare OpenRPC 1.4.1 and are validated against the official meta-schema in tests.

Schema component names now include CLR namespaces. Explicit JSON property names, GUIDs, numeric/string enums, nullable values, recursive objects/collections, and typed dictionaries are covered by tests. Versioned methods include the x-version extension; consumers must send that version in HttpJsonRpc's request version field.

Custom JSON converters can change shapes in arbitrary ways. Supply a matching IOpenRpcTypeConverter for those types; the library cannot infer arbitrary converter behavior or request-dependent serialization. Existing wrapper converters, such as an Undefinable-style converter that unwraps its inner type, remain supported. This release does not attempt complete inference of every custom System.Text.Json contract. Test the actual serialized contracts used by your application.

Filtering discovery by method name

rpc.discover accepts an optional name parameter. Matching uses the full method name and is case-sensitive:

  • "contact.find" selects that exact name.
  • "contact.*" selects names beginning with contact..
  • Omission, null, or "*" selects all visible methods.
  • An empty string or an unmatched name returns an empty methods array.

Only a final * has wildcard meaning; other characters are matched literally. This optional parameter is an HttpJsonRpc extension to the standard discovery call. Calls without parameters continue to work.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rpc.discover",
  "params": { "name": "contact.find" }
}

Configured MethodFilters still control visibility. Name filtering runs before schema generation, so the document includes matching methods and their schema dependencies. Method and document transformers receive the selected methods; transformers can still add their own content and components.

Filtering does not select an API version or change info.version. Methods retain x-version, including when several registered versions share the selected name. Such duplicate names remain a limitation for standard OpenRPC consumers, which require unique method names within a document.

Explicit descriptions

Use OpenRpc* attributes to author documentation. These attributes and discovery transformers do not validate requests or results, register methods, or change serialization. JsonRpc* attributes configure routing and binding; System.Text.Json attributes and options configure serialization. Applications enforce their own validation rules.

Names come from the executable contract: JsonRpcClass and JsonRpcMethod supply RPC names, JsonRpcParameter.Name supplies direct parameter names, and JsonPropertyName or the serializer naming policy supplies object property and flattened [JsonRpcParams] parameter names. Documentation attributes cannot rename these. OpenRpcSchema.Name only controls reusable schema component names; the result content descriptor is named result.

The runtime registry remains available for dispatch and inspection, but its JsonRpcMethod and JsonRpcParameter models no longer contain descriptions. Use rpc.discover for API documentation.

Target Attribute Discovery field
RPC operation OpenRpcMethod.Description Method description
Direct method parameter OpenRpcParameter.Description Parameter content descriptor description
Flattened [JsonRpcParams] property OpenRpcProperty.Description Parameter content descriptor description
Nested object property or serialized field OpenRpcProperty.Description Local property schema description
Shared type OpenRpcSchema.Description Type schema description
Method success result Method-level OpenRpcResult.Description Result content descriptor description
[OpenRpcSchema(Description = "Values used to create a contact.")]
public class ContactCreateValues
{
    [OpenRpcProperty(Description = "The contact's given name.")]
    public string FirstName { get; set; }
}

[JsonRpcClass("contact")]
public class ContactApi
{
    [JsonRpcMethod, OpenRpcMethod(Description = "Creates a contact.")]
    [OpenRpcResult(Description = "The newly created contact.")]
    public Task<Contact> CreateAsync(
        [OpenRpcParameter(Description = "Values for the new contact.")]
        ContactCreateValues values)
    {
        // Create and return the application's Contact model.
        throw new NotImplementedException();
    }
}

OpenRpcSchema supports classes, structs, interfaces, and enums. Its description is read from the converted underlying type, so Task<Contact> uses the Contact schema's description. Type attributes inherit along class inheritance; attributes on interfaces are not automatically imported into implementing classes. Nested properties and serialized fields use OpenRpcProperty and follow the serializer's selected members, including renamed, inherited, and shadowed properties. Ignored members are not documented.

Descriptions on nested object references use a local allOf wrapper and leave the shared component description intact. Parameters and results keep their usage text on their content descriptors rather than duplicating it on the referenced schema. OpenRpcResult is applied to the method, not the return-value attribute target. It does not introduce a result for void, Task, or ValueTask methods that have no generated result schema.

Attribute descriptions are populated before the relevant transformers run, so transformers can override or clear them. Unset schema descriptions are omitted; explicit empty strings remain empty. Text is preserved verbatim, including Markdown. The library does not automatically import System.ComponentModel.DescriptionAttribute or XML comments. These attributes affect discovery only, not runtime validation, JSON property names, or method execution.

Requiredness and nullability

Presence and nullability are independent. OpenRpcParameter and OpenRpcProperty accept Required and Nullable booleans on method parameters and object properties, respectively. OpenRpcResult accepts Nullable on methods. Omit either property to infer it; explicitly setting false is an override, not the same as leaving it unset.

#nullable enable

public class ContactDetails
{
    [OpenRpcProperty(Required = true)]
    public string Name { get; set; } = "";

    [OpenRpcProperty(Required = true)]
    public string? Nickname { get; set; }

    public int? Age { get; set; }
}

The generated schema describes name as required and non-null, nickname as required and nullable, and age as optional and nullable. These annotations do not enforce those rules at runtime. Explicit Nullable = true or Nullable = false overrides inference for that value. On a collection, it changes the collection's nullability, not the nullability of its elements.

  • Requiredness defaults to the existing contract: non-optional method parameters are required, and object properties use serializer-required metadata, C# required, [JsonRequired], or the existing [Required] presence check. Nullability does not imply requiredness. Value-validation rules such as non-empty strings are not inferred from DataAnnotations.
  • Nullable<T> permits null. Other value types do not. Modern C# nullable reference metadata is read using reflection, including enclosing nullable contexts, generic substitutions, inherited members, array elements, and dictionary values. Task<T> and ValueTask<T> use the nullability of T for their result.
  • When reference metadata is absent (for example, unannotated legacy code), discovery preserves the previous schema behavior: typed schemas do not add null; an unconstrained object schema still accepts any JSON value. Use an explicit override to describe a different contract. The reader consumes compiler nullable annotations, not flow-analysis attributes such as [AllowNull] or [MaybeNull].
  • Different nested annotations can produce separate components for the same CLR type, such as List<string> and List<string?>. Follow emitted references or use the transformer's ComponentName; GetName(Type) supplies the base name and cannot identify a particular annotated usage.
  • Custom wire-type converters retain their outer usage nullability, but must describe their own nested wire shapes. Nullable metadata cannot infer a custom serializer's output representation.

Method-parameter presence uses the OpenRPC descriptor's required boolean. Object-property presence uses the JSON Schema required array. Null is expressed with JSON Schema type unions or anyOf; a non-null override can use not to exclude null from a referenced or composed schema without modifying its shared definition. No OpenAPI-style nullable keyword is generated.

Usage transformers run after inferred and explicit nullability. Method transformers run after descriptor requiredness is resolved, and schema transformers can change an object's generated required array. These settings affect discovery only: they do not change parameter binding, defaults, serialization, or runtime validation.

Schema constraints

OpenRpcParameter, OpenRpcProperty, OpenRpcResult, and OpenRpcSchema support these explicit JSON Schema Draft 7 keywords. They describe the public contract; they do not add runtime input validation or change serialization.

Attribute property Type Meaning
Format string Semantic format, such as email, date, or uri
MinLength, MaxLength int Inclusive string-length limits
Pattern string JSON Schema regular expression
Minimum, Maximum double Inclusive numeric bounds
ExclusiveMinimum, ExclusiveMaximum double Exclusive numeric bounds, not boolean switches
MultipleOf double Positive numeric divisor
MinItems, MaxItems int Inclusive array-size limits
UniqueItems bool Whether array elements must be unique
public class ContactInput
{
    [OpenRpcProperty(Required = true, Nullable = false,
        Format = "email", MaxLength = 254)]
    public string Email { get; set; } = "";

    [OpenRpcProperty(Minimum = 0, Maximum = 100, MultipleOf = 0.5)]
    public double Score { get; set; }

    [OpenRpcProperty(MinItems = 1, MaxItems = 10, UniqueItems = true)]
    public string[] Tags { get; set; } = new string[0];
}

Omitting a property emits no additional constraint. Explicit zero and false values are retained. Attribute numeric bounds use double and therefore have its precision limits; no string-based exact-number overload is provided. Negative lengths/counts, non-finite numeric bounds, and non-positive MultipleOf values fail discovery with an explanatory exception. Combined constraints must be chosen consistently by the author; an empty allowed range is not automatically corrected.

Use JSON Schema/ECMAScript-compatible patterns, not .NET-specific regular-expression syntax. Patterns are not implicitly anchored; use ^ and $ when the whole string must match. String lengths count Unicode code points, and MinLength = 1 does not exclude whitespace. Format enforcement depends on the consuming validator.

Constraints are placed on the schema, not on the OpenRPC content descriptor. OpenRpcResult describes the unwrapped result of async methods; OpenRpcSchema describes the converted type's shared schema. Parameters, flattened request properties, and nested object properties receive local constraints. References use an allOf wrapper so Draft 7 applies local keywords without modifying the shared component. Shared type constraints still apply: local constraints can tighten them, but cannot relax constraints inside the referenced definition.

Constraints do not imply requiredness or non-nullability. For example, a nullable string with MaxLength = 20 still permits null. Type-specific keywords do not apply to unrelated JSON types. No additional DataAnnotations validation attributes are imported automatically.

Type constraints run before schema transformers; usage constraints run before usage transformers. Transformers may set or clear the corresponding nullable properties on OpenRpcSchema, and schema copies preserve them. For a shared referenced constraint, change the component through a schema transformer if it needs to be relaxed.

Discovery transformers

Configure the following synchronous callback lists on JsonRpc.Options.OpenRpc before starting the server. Each list runs in registration order; later callbacks see earlier changes. These callbacks customize documentation, not runtime binding or validation.

Callback list Target and context
SchemaTransformers A generated type schema, original ClrType, ConvertedType, and optional ComponentName.
SchemaUsageTransformers A local schema for a property, parameter, result, array item, or dictionary value. Includes Kind, ClrType, ContainingType, JsonName, Member, Parameter, and Method where applicable.
MethodTransformers MethodDescription, registered Method, parameter-to-descriptor mappings, result descriptor, and RequestContext.
DocumentTransformers The complete Document, included Methods, and RequestContext.

For example, a generic contact API can describe a string date, customize a method, and publish its server address:

var openRpc = JsonRpc.Options.OpenRpc;
openRpc.SchemaUsageTransformers.Add(context =>
{
    if (context.Kind == OpenRpcSchemaUsageKind.Property &&
        context.ContainingType == typeof(Contact) &&
        context.Member?.Name == nameof(Contact.BirthDate))
    {
        context.Schema.Format = "date";
    }
});
openRpc.MethodTransformers.Add(context =>
{
    if (context.Method.FullName == "contact.create")
        context.MethodDescription.Summary = "Create a contact";
});
openRpc.DocumentTransformers.Add(context =>
{
    context.Document.Servers = new[]
    {
        new OpenRpcServer { Name = "production", Url = "https://example.com/rpc" }
    };
});

Generation follows these rules:

  • Method inclusion filters run first. Excluded methods are not passed to transformers.
  • Existing type converters still determine the CLR type's representation. A schema transformer runs after that schema's properties/items have been generated, once per shared component per discovery call, or for each generated inline schema. ClrType is the first encountered type (possibly a wrapper such as Task<T>); use ConvertedType for conventions on the shared underlying type.
  • Property and collection-element usages belong to their containing type, not to a particular endpoint. Their Method is null. Parameter and result usages carry the registered method. A DTO parameter carries its PropertyInfo in Member; a direct parameter carries ParameterInfo in Parameter. Results expose the return parameter; JSON names reflect serializer naming. Collection elements have no member or JSON name of their own.
  • Usage transformers receive an independent schema and may replace context.Schema with another non-null schema. References are wrapped in allOf so local keywords remain effective under JSON Schema Draft 7. They do not modify the referenced component. A property inside a shared component still applies wherever that containing type is used; endpoint-specific differences belong on the endpoint's parameter/result schema.
  • Recursive references can point to components still under construction. Schema callbacks should work on their supplied target; whole-document inspection belongs in a document transformer. Preserve references rather than creating cyclic CLR object graphs in the schema model.
  • Method transformers run after that method's descriptors are generated. The parameter map and Result identify the initially generated descriptors; if you replace entries in MethodDescription, update the replacements directly.
  • Document transformers run last. The document, component schemas, and configured info/contact/license copies belong to the current discovery call.
  • Callbacks can execute concurrently across requests. Do not mutate configuration while serving requests, retain request context, or insert shared mutable metadata objects into multiple documents. Exceptions fail discovery through the normal RPC error-handling path rather than returning a partially customized document.

The schema model's supported keywords still apply. Advanced conditional constraints and automatic XML documentation ingestion are not implemented.

Request and result examples

Use method transformers to publish named input/result pairings with the existing OpenRpcExamplePairing and OpenRpcExample models. See OpenRPC examples for contact creation, lookup results, explicit JSON nulls, and the generated discovery JSON.

Development and release validation

dotnet build src/HttpJsonRpc.sln -c Release -p:GeneratePackageOnBuild=false
dotnet test src/HttpJsonRpc.Tests/HttpJsonRpc.Tests.csproj -c Release --no-build
dotnet list src/HttpJsonRpc/HttpJsonRpc.csproj package --vulnerable --include-transitive
dotnet pack src/HttpJsonRpc/HttpJsonRpc.csproj -c Release --no-build -o artifacts -p:GeneratePackageOnBuild=false
./eng/Verify-Package.ps1 (Get-ChildItem artifacts/*.nupkg).FullName

Tests target .NET Framework 4.8 (Windows) and .NET 10. They use loopback listeners with dynamically assigned ports and vendored schemas, without external services. CI runs the same builds/tests and checks package contents. Transitive NuGet vulnerability warnings fail the build. The sample targets .NET 10.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0 136 10/31/2026
2.7.1 154 9/17/2026
2.7.0 119 9/17/2026
2.6.4 122 9/17/2026
2.6.3 118 9/17/2026
2.6.2 312 3/4/2026
2.6.1 171 2/25/2026
2.6.0 186 1/15/2026
2.5.8 196 1/2/2026
2.5.7 183 1/2/2026
2.5.6 269 12/24/2025
2.5.5 274 12/24/2025
2.5.4 263 12/24/2025
2.5.3 265 12/24/2025
2.5.2 272 12/23/2025
2.5.1 254 12/23/2025
2.5.0 275 12/23/2025
2.4.1 387 8/28/2025
2.4.0 243 8/15/2025
2.3.0 304 8/4/2025
Loading failed