InterfaceRpc.Client 3.0.0

InterfaceRpc

Turn a C# interface into an HTTP API and a typed client, generated at compile time.

Write an interface once and share it. The server gets ASP.NET Core minimal API endpoints for every method, and the client gets an implementation that calls them over HTTP. Both are generated when you build.

✨ Features

• ⚡ No runtime reflection. Source generators write the endpoints and the client during the build.
• 🧩 Built on the platform. Minimal APIs, IHttpClientFactory, dependency injection and System.Text.Json. Nothing custom to learn.
• 🔐 Standard authorization. [Authorize], [AllowAnonymous], policies and route group conventions all work.
• 🛡️ Errors at compile time. Contracts that can't work over HTTP fail the build with a clear message.
• 🌐 Plain HTTP and JSON. Any language or tool can call your service.
• ✂️ Trim and AOT friendly. Both libraries are annotated for trimming and native AOT.

🚀 Quick start

1. Install

dotnet add package InterfaceRpc.Service --version 3.0.0
dotnet add package InterfaceRpc.Client --version 3.0.0

2. Define a contract

Put the interface in a class library that both apps reference. It can target netstandard2.0.

public interface IGreeter
{
    Task<string> GreetAsync(string name);
}

3. 🖥️ Host it

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IGreeter, Greeter>();

var app = builder.Build();
app.MapRpcService<IGreeter>();   // POST /GreetAsync
app.Run();

4. 💻 Call it

builder.Services.AddRpcClient<IGreeter>(c => c.BaseAddress = new Uri("https://api.example"));

// Then inject IGreeter anywhere:
var message = await greeter.GreetAsync("Rush");

That's it. Calling GreetAsync on the client sends POST /GreetAsync to the server.

🔍 How it works

            IGreeter (shared contract library)
             │                              │
  AddRpcClient<IGreeter>()     MapRpcService<IGreeter>()
             │                              │
             v                              v
   ┌────────────────────┐  POST  ┌────────────────────┐
   │ generated client   │ ─────> │ generated endpoint │
   │ HttpClient + JSON  │ <───── │ minimal API + DI   │
   └────────────────────┘  JSON  └────────────────────┘
         client app                    server app

The generators run in the project that calls AddRpcClient<T>(), RpcClient.Create<T>() or MapRpcService<T>(), so the interface can live in any referenced assembly. Generated code registers itself when your app starts, so the library finds it without reflection.

💡 Tip: To read the generated code, expand Dependencies › Analyzers in Visual Studio, or add <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> to your project file.

📡 Wire format

Nothing is hidden: each method is an ordinary JSON endpoint.

POST /GreetAsync HTTP/1.1
Content-Type: application/json

{ "name": "Rush" }

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

"Hello, Rush!"

⚙️ Configuration

Server

The implementation is resolved from the request's services on every call, so any lifetime works.

📝 Note: Any ASP.NET Core attribute on the interface or its methods ([Authorize], [AllowAnonymous], [EnableRateLimiting], [Tags]…) becomes endpoint metadata. [Authorize] can only be applied to methods. To cover a whole interface, use .RequireAuthorization() or a subclass of AuthorizeAttribute whose AttributeUsage allows interfaces.

Client

builder.Services.AddRpcClient<IGreeter>(c => c.BaseAddress = new Uri("https://api.example/rpc"))
    .AddHttpMessageHandler<BearerTokenHandler>()
    .AddStandardResilienceHandler()
    .ConfigureRpcClient(o => o.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter()));

📝 Note: Synchronous interface methods block on the asynchronous pipeline, so every message handler still runs. Prefer Task-returning methods where you can.

Native AOT

Add a JsonSerializerContext for your contract types on both sides, with ConfigureHttpJsonOptions on the server and ConfigureRpcClient on the client.

✅ Supported contracts

Works:

• Return types void, T, Task, Task<T>, ValueTask and ValueTask<T>
• Parameters of any type System.Text.Json can serialize, including in, params and default values
• CancellationToken parameters
• Methods inherited from base interfaces

Doesn't work (and fails the build):

• Overloaded methods (methods are routed by name)
• Generic methods, ref and out parameters, ref structs such as Span<T>
• Properties, events and IAsyncEnumerable<T>

Compiler diagnostics

Problems are reported at the AddRpcClient, RpcClient.Create or MapRpcService call.

⬆️ Upgrading from 2.x

⚠️ Important: Version 3 changes the wire format (arguments are now a named JSON object), so upgrade clients and services together.

🛠️ Building from source

dotnet build
dotnet test
dotnet pack -c Release   # writes both packages to ./nupkg/<version>

The Examples folder has a demo service and a console client. Start InterfaceRpcDemoService, then run InterfaceRpcDemoClient.

The version comes from <Version> in Directory.Build.props. Building updates the install commands in this README to match.

💬 Feedback

Found a bug or have an idea? Open an issue.

📄 License

Apache 2.0