RemoteService.Net.Client 1.0.1-preview.0.1

RemoteService.Net

Call your server services from Blazor WebAssembly as if they were local — no controllers, no HttpClient boilerplate, no duplicated DTO plumbing.

Define a C# service interface once. RemoteService.Net's Roslyn source generator does the rest:

• On the server (prerendering, InteractiveServer, or InteractiveAuto running server-side) the interface resolves to your real implementation and is called in-process.
• In the browser (InteractiveWebAssembly, or InteractiveAuto after WASM takes over) the interface resolves to a generated HTTP proxy that calls generated Minimal API endpoints on the server.

Your components don't know the difference — they just inject the interface.

public interface IProductService : IRemoteService
{
    Task<Product[]> SearchAsync(string query, CancellationToken cancellationToken = default);
}

@inject IProductService Products

@code {
    private Product[]? _results;

    private async Task Search(string query)
        => _results = await Products.SearchAsync(query);
}

That's it. No API controller, no route constants, no JsonSerializer calls, no manual DI wiring per service. Everything is generated at compile time — fully typed, refactor-safe, and AOT/trimming friendly.

Why?

Blazor Web Apps with WebAssembly interactivity have a well-known friction point: components run in two places. During prerendering they execute on the server where they could call services directly; after hydration they execute in the browser where every data access must go over HTTP. The standard answer is to hand-write an API controller and a typed HttpClient wrapper and keep both in sync with the service interface — for every service.

RemoteService.Net removes that entire layer:

Installation

RemoteService.Net ships as three NuGet packages — one per layer of a typical Blazor Web App solution. Install each package in the project it belongs to.

Package	Install in	Contains
	Shared contracts class library	IRemoteService marker, attributes, exception types
	Blazor WebAssembly project (*.Client)	Client runtime + source generator (emits HTTP proxies)
	ASP.NET Core host project	Server runtime + source generator (emits endpoints)

The contracts library is referenced by both the client and the server project, so a single interface definition is shared across the whole solution.

Option A — .NET CLI

Run each command from the directory of the project it applies to:

# Shared contracts project (class library)
dotnet add package RemoteService.Net.Abstractions

# Blazor WebAssembly client project
dotnet add package RemoteService.Net.Client

# ASP.NET Core server project
dotnet add package RemoteService.Net.Server

Option B — PackageReference in the .csproj

If you prefer editing project files directly (or use Visual Studio's NuGet UI), add the reference to the matching project:

<ItemGroup>
  <PackageReference Include="RemoteService.Net.Abstractions" Version="1.0.0" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="RemoteService.Net.Client" Version="1.0.0" />
  <ProjectReference Include="..\MyApp.Contracts\MyApp.Contracts.csproj" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="RemoteService.Net.Server" Version="1.0.0" />
  <ProjectReference Include="..\MyApp.Contracts\MyApp.Contracts.csproj" />
</ItemGroup>

Using Central Package Management? Put the <PackageVersion Include="RemoteService.Net.Client" Version="1.0.0" /> entries in Directory.Packages.props and drop the Version attribute from the PackageReference elements above.

Visual Studio

Right-click the project → Manage NuGet Packages… → Browse → search for RemoteService.Net → install the package listed for that project in the table above.

Notes

• Requires .NET 10.
• The source generator ships inside the Client and Server packages and detects its role automatically from which package a project references — no configuration needed. Override with the RemoteServiceNetRole MSBuild property if you ever need to (Client, Server, or Client,Server).
• RemoteService.Net.Abstractions is pulled in transitively by both the Client and Server packages, so you only need to reference it explicitly in the shared contracts project.

Quickstart — Blazor Web App

Works with the standard Blazor Web App template using WebAssembly or Auto interactivity:

dotnet new blazor -int WebAssembly --all-interactive   # or -int Auto

1. Define the contract (shared project)

using RemoteService.Net;

public sealed record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary);

public interface IWeatherService : IRemoteService
{
    Task<WeatherForecast[]> GetForecastAsync(int days, CancellationToken cancellationToken = default);
}

The only requirement: inherit the IRemoteService marker interface and return Task/Task<T>/ValueTask/ValueTask<T>.

2. Implement it (server project)

public sealed class ServerWeatherService : IWeatherService
{
    public async Task<WeatherForecast[]> GetForecastAsync(int days, CancellationToken ct = default)
    {
        // Talk to your database, other services, etc.
    }
}

// Program.cs (server)
builder.Services.AddScoped<IWeatherService, ServerWeatherService>();

var app = builder.Build();
// ...
app.MapRemoteServices(); // generated: maps POST /_rpc/{Interface}/{Method}

3. Register the proxies (client project)

// Program.cs (client)
builder.Services.AddScoped(_ => new HttpClient
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress),
});
builder.Services.AddRemoteServiceClients(); // generated: registers a proxy per interface

4. Use it from any component

@page "/weather"
@inject IWeatherService WeatherService

@code {
    [PersistentState] // .NET 10: reuse prerendered data instead of fetching twice
    public WeatherForecast[]? Forecasts { get; set; }

    protected override async Task OnInitializedAsync()
        => Forecasts ??= await WeatherService.GetForecastAsync(days: 5);
}

During prerendering this calls ServerWeatherService directly. In the browser it becomes POST /_rpc/IWeatherService/GetForecastAsync. Combined with [PersistentState], the service is called exactly once per navigation.

Render mode compatibility

A complete runnable demo (weather + todos with validation) lives in samples/.

Errors that behave like exceptions

Throw a typed exception on the server; catch the same typed exception in the browser. On the wire it's a standard RFC 7807 ProblemDetails.

// Server implementation
public Task<TodoItem> AddAsync(string title, CancellationToken ct = default)
{
    if (string.IsNullOrWhiteSpace(title))
        throw new RemoteValidationException("Validation failed.",
            new Dictionary<string, string[]> { ["title"] = ["Title must not be empty."] });
    // ...
}

// Component — identical whether the call was in-process or HTTP
try
{
    await TodoService.AddAsync(title);
}
catch (RemoteValidationException ex)
{
    _errors = ex.Errors;
}

Authorization

Interfaces can't carry [Authorize], so RemoteService.Net provides mirrored attributes that the generator translates to endpoint authorization:

[RemoteAuthorize(Roles = "admin")]
public interface IAdminService : IRemoteService
{
    Task<AuditEntry[]> GetAuditLogAsync(CancellationToken ct = default);

    [RemoteAllowAnonymous]
    Task<bool> PingAsync(CancellationToken ct = default);
}

Policy, Roles, and AuthenticationSchemes are supported, on the interface or per method.

The protocol, briefly

• Every method maps to POST /_rpc/{InterfaceName}/{MethodName} — override with [RemoteRoute] / [RemoteMethod].
• Request body is a JSON object with one property per parameter. Generated types never appear on the wire, so AOT users only need a JsonSerializerContext for their own DTOs.
• Task<T> → 200 (including JSON null); Task → 204. CancellationToken flows to HttpContext.RequestAborted.
• A required custom header (X-RemoteService-Call) blocks classic CSRF against cookie-authenticated endpoints.
• A protocol version header detects stale cached WASM clients after a deployment and surfaces a clear RemoteProtocolException instead of confusing serialization errors.
• Overloads and generic interfaces/methods are rejected at compile time with descriptive diagnostics (RSN001–RSN008).

Building from source

dotnet build
dotnet test
dotnet pack -c Release -o artifacts/packages

License

MIT