Agent Skills: gRPC Services in .NET

gRPC Services in .NET

Proto File

syntax = "proto3";
option csharp_namespace = "MyApp.Grpc";
package catalog;

service CatalogService {
  rpc GetProduct (GetProductRequest) returns (ProductResponse);
  rpc ListProducts (ListProductsRequest) returns (ListProductsResponse);
  rpc CreateProduct (CreateProductRequest) returns (ProductResponse);
  rpc StreamProducts (StreamRequest) returns (stream ProductResponse);
}

message GetProductRequest { int32 id = 1; }
message ListProductsRequest {
  int32 page = 1;
  int32 page_size = 2;
  string search = 3;
}
message ListProductsResponse {
  repeated ProductResponse products = 1;
  int32 total_count = 2;
}
message CreateProductRequest {
  string name = 1;
  string description = 2;
  double price = 3;
}
message ProductResponse {
  int32 id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
}
message StreamRequest { string filter = 1; }

Service Implementation

public sealed class CatalogGrpcService(ICatalogService catalog, ILogger<CatalogGrpcService> logger)
    : CatalogService.CatalogServiceBase
{
    public override async Task<ProductResponse> GetProduct(
        GetProductRequest request, ServerCallContext context)
    {
        var product = await catalog.GetByIdAsync(request.Id, context.CancellationToken)
            ?? throw new RpcException(new Status(StatusCode.NotFound, $"Product {request.Id} not found"));

        return MapToResponse(product);
    }

    public override async Task StreamProducts(
        StreamRequest request, IServerStreamWriter<ProductResponse> responseStream, ServerCallContext context)
    {
        await foreach (var product in catalog.StreamAsync(request.Filter, context.CancellationToken))
        {
            await responseStream.WriteAsync(MapToResponse(product));
        }
    }
}

Server Setup

builder.Services.AddGrpc();
app.MapGrpcService<CatalogGrpcService>();

Client (with Aspire)

builder.Services.AddGrpcClient<CatalogService.CatalogServiceClient>(o =>
{
    o.Address = new("https+http://catalog-api");
})
.AddStandardResilienceHandler();

gRPC vs REST Decision Matrix (from official docs)

| Aspect | gRPC | REST/HTTP | |--------|------|----------| | Serialization | Protocol Buffers (binary) | JSON (text) | | Protocol | HTTP/2 | HTTP/1.1 or HTTP/2 | | Payload size | Small, compressed | Larger, human-readable | | Latency | Low (~10x faster) | Higher | | Browser support | Limited (gRPC-Web) | Full | | Code generation | Automatic (contract-first) | Manual | | Streaming | Native, bidirectional | Limited | | Debugging | Binary (harder) | Easy (HTTP tools) | | Use case | Microservices, real-time | Public APIs, browsers |

All 4 RPC Patterns (from official docs)

Client Streaming

// Stream of requests → single response
public override async Task<HelloReply> LotsOfGreetings(
    IAsyncStreamReader<HelloRequest> requestStream, ServerCallContext context)
{
    var count = 0;
    await foreach (var request in requestStream.ReadAllAsync())
    {
        count++;
    }
    return new HelloReply { Message = $"Processed {count} greetings" };
}

Bidirectional Streaming

// Stream requests ↔ stream responses simultaneously
public override async Task BidiHello(
    IAsyncStreamReader<HelloRequest> requestStream,
    IServerStreamWriter<HelloReply> responseStream,
    ServerCallContext context)
{
    await foreach (var request in requestStream.ReadAllAsync())
    {
        await responseStream.WriteAsync(new HelloReply
        {
            Message = $"Echo: {request.Name}"
        });
    }
}

Project Setup (from official docs)

<!-- .csproj -->
<ItemGroup>
  <Protobuf Include="Protos\greet.proto" />
</ItemGroup>

dotnet add package Grpc.AspNetCore
dotnet add package Grpc.Tools

Best Practices

• Use gRPC for internal service-to-service communication
• Use REST/HTTP for external APIs (browser compatibility)
• Use server streaming for large result sets
• Use Deadline for request timeouts
• Use interceptors for cross-cutting concerns (logging, auth)
• Add .proto files to <Protobuf> item group in .csproj
• Binary format = harder debugging; use gRPC reflection for tooling