HttpJsonRpc 3.0.0
dotnet add package HttpJsonRpc --version 3.0.0
NuGet\Install-Package HttpJsonRpc -Version 3.0.0
<PackageReference Include="HttpJsonRpc" Version="3.0.0" />
<PackageVersion Include="HttpJsonRpc" Version="3.0.0" />
<PackageReference Include="HttpJsonRpc" />
paket add HttpJsonRpc --version 3.0.0
#r "nuget: HttpJsonRpc, 3.0.0"
#:package HttpJsonRpc@3.0.0
#addin nuget:?package=HttpJsonRpc&version=3.0.0
#tool nuget:?package=HttpJsonRpc&version=3.0.0
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
- Create a class that will hold your
JsonRpcmethods with theJsonRpcClassAttribute.
[JsonRpcClass("math")]
public static class MathApi
{
[JsonRpcMethod]
public static Task<int> SumAsync(int n1, int n2)
{
var result = n1 + n2;
return Task.FromResult(result);
}
}
- Call the
JsonRpc.Startmethod to start listening forJSON-RPCrequests overHTTP.
class Program
{
static void Main(string[] args)
{
JsonRpc.Start();
Console.ReadLine();
}
}
- The ideal way to call
JSON-RPCmethods is using anHTTP POSTwith theJSON-RPC Requestin theHTTP BodybutHttpJsonRpcalso supportsURL Parametersfor simple method calls. Test the method by pasting theURLin 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"
}
- You can add your favorite logging provider by setting the
JsonRpc.LoggerFactoryproperty. This sample uses Serilog.
Log.Logger = new LoggerConfiguration()
.WriteTo.Console()
.CreateLogger();
JsonRpc.LoggerFactory = new LoggerFactory().AddSerilog();
JsonRpc.Start();
- 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.
OnCompletedRequestremains a success-only callback. For batch calls it runs after successful result construction, before the aggregate HTTP response is written.OnRequestFinishedruns 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.Exceptionidentifies a processing failure.JsonRpcContext.Currentis scoped to the request. Do not retain itsHttpContextafter completion.- Instances created with
Activatorare 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
CancellationTokenRPC parameter receivesHttpContext.RequestAbortedautomatically 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 withcontact..- Omission,
null, or"*"selects all visible methods. - An empty string or an unmatched name returns an empty
methodsarray.
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>andValueTask<T>use the nullability ofTfor 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
objectschema 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>andList<string?>. Follow emitted references or use the transformer'sComponentName;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.
ClrTypeis the first encountered type (possibly a wrapper such asTask<T>); useConvertedTypefor conventions on the shared underlying type. - Property and collection-element usages belong to their containing type, not to a
particular endpoint. Their
Methodis null. Parameter and result usages carry the registered method. A DTO parameter carries itsPropertyInfoinMember; a direct parameter carriesParameterInfoinParameter. 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.Schemawith another non-null schema. References are wrapped inallOfso 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
Resultidentify the initially generated descriptors; if you replace entries inMethodDescription, 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 | Versions 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. |
-
.NETStandard 2.0
- CommonServiceLocator (>= 2.0.7)
- Microsoft.AspNetCore.Cors (>= 2.3.0)
- Microsoft.AspNetCore.Server.Kestrel (>= 2.3.13)
- Microsoft.Bcl.AsyncInterfaces (>= 9.0.7)
- Microsoft.Extensions.Logging.Abstractions (>= 9.0.7)
- System.ComponentModel.Annotations (>= 5.0.0)
- System.Text.Json (>= 9.0.7)
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 |