grpc-interceptors

name	grpc-interceptors
description	gRPC interceptors for ASP.NET Core — server and client interceptors for logging, authentication, validation, error handling, and metrics. Use when implementing cross-cutting concerns.

gRPC Interceptors

Interceptors allow apps to interact with incoming or outgoing gRPC calls. They are transparent to application logic and ideal for cross-cutting concerns like logging, authentication, validation, and metrics.

Server Interceptors

Base Class Methods to Override

Method	Intercepts
UnaryServerHandler	Unary RPCs
ClientStreamingServerHandler	Client-streaming RPCs
ServerStreamingServerHandler	Server-streaming RPCs
DuplexStreamingServerHandler	Bidirectional-streaming RPCs

Logging Interceptor Example

public class ServerLoggingInterceptor(ILogger<ServerLoggingInterceptor> logger) : Interceptor
{
    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request,
        ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        logger.LogInformation("Starting call: {Method}", context.Method);
        try
        {
            var response = await continuation(request, context);
            logger.LogInformation("Completed call: {Method}", context.Method);
            return response;
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Error in call: {Method}", context.Method);
            throw;
        }
    }
}

Validation Interceptor Example

public class ValidationInterceptor : Interceptor
{
    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request,
        ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        if (request is IValidatable validatable)
        {
            var errors = validatable.Validate();
            if (errors.Any())
            {
                throw new RpcException(new Status(
                    StatusCode.InvalidArgument,
                    string.Join("; ", errors)));
            }
        }
        return await continuation(request, context);
    }
}

Registration

// Global — applies to all services
builder.Services.AddGrpc(options =>
{
    options.Interceptors.Add<ServerLoggingInterceptor>();
    options.Interceptors.Add<ValidationInterceptor>();
});

// Per-service — applies only to a specific service
builder.Services.AddGrpc()
    .AddServiceOptions<MyService>(options =>
    {
        options.Interceptors.Add<ServerLoggingInterceptor>();
    });

Execution Order

• Global interceptors run before per-service interceptors
• Within each group, interceptors run in registration order

DI Lifetime

• By default, server interceptors have per-request lifetime
• Register as singleton for shared state:

builder.Services.AddSingleton<ServerLoggingInterceptor>();

---

Client Interceptors

Base Class Methods to Override

Method	Intercepts
AsyncUnaryCall	Async unary RPCs
BlockingUnaryCall	Blocking unary RPCs
AsyncClientStreamingCall	Client-streaming RPCs
AsyncServerStreamingCall	Server-streaming RPCs
AsyncDuplexStreamingCall	Bidirectional RPCs

Client Logging Interceptor Example

public class ClientLoggingInterceptor(ILoggerFactory loggerFactory) : Interceptor
{
    private readonly ILogger _logger = loggerFactory.CreateLogger<ClientLoggingInterceptor>();

    public override AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(
        TRequest request,
        ClientInterceptorContext<TRequest, TResponse> context,
        AsyncUnaryCallContinuation<TRequest, TResponse> continuation)
    {
        _logger.LogInformation("Starting call: {Type}/{Method}",
            context.Method.Type, context.Method.Name);
        return continuation(request, context);
    }
}

Client Error Handling Interceptor

public class ClientErrorInterceptor : Interceptor
{
    public override AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(
        TRequest request,
        ClientInterceptorContext<TRequest, TResponse> context,
        AsyncUnaryCallContinuation<TRequest, TResponse> continuation)
    {
        var call = continuation(request, context);
        return new AsyncUnaryCall<TResponse>(
            HandleResponse(call.ResponseAsync),
            call.ResponseHeadersAsync,
            call.GetStatus,
            call.GetTrailers,
            call.Dispose);
    }

    private static async Task<TResponse> HandleResponse<TResponse>(Task<TResponse> inner)
    {
        try
        {
            return await inner;
        }
        catch (RpcException ex) when (ex.StatusCode == StatusCode.Unavailable)
        {
            throw new InvalidOperationException("Service unavailable", ex);
        }
    }
}

Registration

// Manual channel configuration
using var channel = GrpcChannel.ForAddress("https://localhost:5001");
var invoker = channel
    .Intercept(new ClientLoggingInterceptor(loggerFactory))
    .Intercept(new ClientErrorInterceptor());
var client = new MyService.MyServiceClient(invoker);

// gRPC client factory (preferred for ASP.NET Core)
builder.Services.AddGrpcClient<MyService.MyServiceClient>(options =>
{
    options.Address = new Uri("https://localhost:5001");
})
.AddInterceptor<ClientLoggingInterceptor>();

Important Notes

• Intercept() chain executes in reverse order (last added runs first)
• Client factory AddInterceptor<T>() executes in registration order
• BlockingUnaryCall and AsyncUnaryCall are NOT interchangeable — override both if needed

---

Interceptors vs Middleware

Aspect	Interceptors	ASP.NET Core Middleware
Abstraction level	gRPC (typed messages)	HTTP (raw bytes)
Access to messages	Deserialized request/response	Raw HTTP streams
Execution order	After middleware	Before interceptors
Scope	gRPC calls only	All HTTP requests
Error handling	Can catch typed gRPC exceptions	Operates on HTTP status codes

Guideline: Use interceptors for gRPC-specific concerns. Use middleware for HTTP-level concerns (CORS, compression, rate limiting).