CarpaNet.AspNetCore #
ASP.NET Core XRPC server endpoint support for CarpaNet. Generate abstract ATProtocol XRPC controllers from lexicon definitions and implement your own ATProtocol server endpoints.
Installation #
dotnet add package CarpaNet.AspNetCore
You also need the core CarpaNet package (with source generator) to generate the controllers and data model types.
Quick Start #
1. Enable XRPC endpoint generation #
Set CarpaNet_EmitXrpcEndpoints to true in your ASP.NET Core project:
<PropertyGroup>
<CarpaNet_EmitXrpcEndpoints>true</CarpaNet_EmitXrpcEndpoints>
<CarpaNet_LexiconAutoResolve>true</CarpaNet_LexiconAutoResolve>
</PropertyGroup>
<ItemGroup>
<LexiconResolve Include="com.atproto.server.describeServer" />
<LexiconResolve Include="com.atproto.identity.resolveHandle" />
</ItemGroup>
This tells the CarpaNet source generator to produce abstract controller classes alongside the usual data model types.
2. Implement the generated controllers #
The generator creates abstract controllers grouped by NSID namespace. Subclass them and implement the abstract methods:
using CarpaNet.AspNetCore;
using Microsoft.AspNetCore.Http.HttpResults;
public class MyServerController : Xrpc.ComAtproto.Server.ServerController
{
public override Task<Results<Ok<ComAtproto.Server.DescribeServerOutput>, ATErrorResult>> DescribeServerAsync(
CancellationToken cancellationToken = default)
{
var output = new ComAtproto.Server.DescribeServerOutput
{
AvailableUserDomains = new List<string> { ".example.com" },
Did = new CarpaNet.ATDid("did:web:example.com"),
};
return Task.FromResult<Results<Ok<ComAtproto.Server.DescribeServerOutput>, ATErrorResult>>(
TypedResults.Ok(output));
}
}
3. Wire up ASP.NET #
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();
Your endpoints are now available at /xrpc/{nsid} (e.g., /xrpc/com.atproto.server.describeServer).
How It Works #
The CarpaNet source generator reads ATProtocol lexicon JSON files and produces:
- Data model classes — Records, objects, input/output types (generated by the existing pipeline)
- Abstract controllers — One per NSID namespace group (e.g.,
ServerControllerforcom.atproto.server.*)
Lexicon queries map to [HttpGet] with [FromQuery] parameters. Lexicon procedures map to [HttpPost] with [FromBody] input.
Generated Controller Pattern #
Lexicon: com.atproto.identity.resolveHandle (query)
↓
Xrpc.ComAtproto.Identity.IdentityController (abstract)
→ ResolveHandleAsync([FromQuery] string handle, CancellationToken ct)
→ Returns Task<Results<Ok<ResolveHandleOutput>, ATErrorResult>>
Lexicon: com.atproto.repo.createRecord (procedure)
↓
Xrpc.ComAtproto.Repo.RepoController (abstract)
→ CreateRecordAsync([FromBody] CreateRecordInput input, CancellationToken ct)
→ Returns Task<Results<Ok<CreateRecordOutput>, ATErrorResult>>
Error Handling #
Use ATErrorResult factory methods to return ATProtocol-compliant error responses:
// Returns { "error": "NotFound", "message": "Record not found" } with HTTP 404
return ATErrorResult.NotFound("Record not found");
// Returns { "error": "AuthMissing", "message": "Authentication Required" } with HTTP 401
return ATErrorResult.Unauthorized();
// Returns { "error": "BadRequest", "message": "Invalid handle format" } with HTTP 400
return ATErrorResult.BadRequest("Invalid handle format");
Available factory methods:
| Method | Status Code | Error Type |
|---|---|---|
BadRequest() |
400 | BadRequest |
Unauthorized() |
401 | AuthMissing |
Forbidden() |
403 | Forbidden |
NotFound() |
404 | NotFound |
PayloadTooLarge() |
413 | PayloadTooLarge |
TooManyRequests() |
429 | TooManyRequests |
InternalServerError() |
500 | InternalServerError |
NotImplemented() |
501 | NotImplemented |
BadGateway() |
502 | BadGateway |
ServiceUnavailable() |
503 | ServiceUnavailable |
GatewayTimeout() |
504 | GatewayTimeout |
MSBuild Properties #
| Property | Description | Default |
|---|---|---|
CarpaNet_EmitXrpcEndpoints |
Enable XRPC controller generation | false |