name: grpc-standards description: "Use when working with gRPC services, protobuf definitions, Protocol Buffers, streaming RPCs, interceptors, or gRPC client configuration in .NET. Provides domain-specific rules layered on top of base architectural standards."

Skill: gRPC Service Standards

Identity

When to Apply

Activate this skill when the task involves:

• Defining or editing .proto files
• Implementing gRPC service classes
• Server or client streaming patterns
• gRPC interceptors (logging, auth, error mapping)
• Deadline and timeout configuration
• gRPC client registration and channel management

Rules

These rules layer on top of base architectural standards. On conflict, these win.

gRPC — Service Standards

Apply these rules in addition to _base.md for projects using gRPC services.

Protobuf Conventions

• One .proto file per service — file name matches service name: order_service.proto.
• Use snake_case for field names, PascalCase for message and service names (protobuf convention).
• Set option csharp_namespace explicitly to control generated C# namespace.
• Version APIs via package name: package myapp.orders.v1; — never reuse package names for breaking changes.
• Every RPC method has a dedicated Request and Response message — never reuse messages across RPCs.
• Use google.protobuf.Timestamp for dates, google.protobuf.Duration for time spans, google.protobuf.StringValue for nullable strings.

Service Implementation

• Inherit from generated Base class: public class OrderService : Orders.OrdersBase.
• Keep service methods thin — delegate to Application layer handlers (same as Minimal API handlers).
• Inject dependencies via constructor DI — gRPC services are registered as scoped by default.
• Always accept ServerCallContext and propagate its CancellationToken to downstream calls.
• Return domain errors via RpcException with appropriate StatusCode — never throw raw exceptions.

Streaming Patterns

• Server streaming: use async + yield return pattern or write to IServerStreamWriter<T> in a loop.
• Client streaming: read from IAsyncStreamReader<T> until MoveNext() returns false.
• Bidirectional: use Task.WhenAll to read and write concurrently, not sequentially.
• Always check context.CancellationToken in streaming loops — abort cleanly on client disconnect.
• Set reasonable MaxReceiveMessageSize and MaxSendMessageSize (default 4MB is often too small for file transfers).

Deadlines & Timeouts

• Every client call must set a deadline: client.GetOrderAsync(req, deadline: DateTime.UtcNow.AddSeconds(5)).
• Propagate incoming deadlines to downstream calls — use context.Deadline for cascading timeouts.
• Handle StatusCode.DeadlineExceeded explicitly in client error handling.
• Set global channel options for default deadline: GrpcChannelOptions.MaxReceiveMessageSize.

Error Handling

• Map domain errors to gRPC status codes:

• Include detail metadata in RpcException for debugging — never expose stack traces.
• Use interceptors for global error mapping — don't repeat try/catch in every RPC method.

Interceptors

• Use server interceptors for cross-cutting concerns: logging, metrics, auth, error mapping.
• One concern per interceptor — same single-responsibility as middleware.
• Register interceptors in AddGrpc(options => options.Interceptors.Add<LoggingInterceptor>()).
• Client interceptors for: retry, deadline propagation, auth token injection.

Client Configuration

• Use GrpcChannel.ForAddress with IHttpClientFactory for connection management.
• Register typed clients via AddGrpcClient<OrderService.OrderServiceClient>() in DI.
• Enable retry via ServiceConfig — gRPC has built-in retry policy support.
• Use CallInvoker for testing — mock at the channel level, not the service level.

Common Anti-Patterns

See Also

• api-design.md — RESTful conventions, HTTP methods, pagination, error responses
• resilience.md — Polly v8 resilience pipelines, retry, circuit breaker, timeout
• auth.md — Authentication, authorization, OAuth/OIDC, secrets management
• result-error-handling.md — Result object pattern, error constants, exception boundaries