Using google.rpc.Status with gRPC .NET

In the broad gRPC community, there is an as yet unspecified convention that one way to include details about failed requests is to serialize a google.rpc.Status message and put it in the response trailer field grpc-status-details-bin. (Example implementations: C++, Python, Ruby).

This repository shows one way to implement this convention using the gRPC .NET implementation.

Google publishes a NuGet package with a C# implementation of the google.rpc.Status message, Google.Api.CommonProtos. That package is used in this example.

The most interesting directories are:

• client: client-side code that shows how to extract the detailed status
  from a failed request
• service: service-side code that fails requests with
  StatusCode.FailedPrecondition and additional details when the Name
  field in the request is missing. The interesting code is in the
  GreeterService.cs implementation. The rest is standard gRPC .NET
  bootstrapping.

Running the example

To run this example, you will need to

1. Clone the repository.
2. Build and run the service.
3. Build and run the client.

First, clone the repository and run the service:

mkdir example
cd example
# Notice the dot at the end of this command to clone into the current directory
git clone https://github.com/chwarr/grpc-dotnet-google-rpc-status.git .
cd service
dotnet run

Then, run the client from a different shell:

cd example/client
dotnet run

Determining what status details an API may return

You are likely safe assuming that grpc-status-details-bin is a Protocol Buffer serialized google.rpc.Status message.

You will have to consult the documentation of the gRPC service methods you are invoking to determine what messages to expect in the google.rpc.Status.details field.

Troubleshooting

If you try to use this approach in your own service and your don't see the grpc-status-details-bin trailer on the client side, make sure both the client and the server are using gRPC .NET 2.32 or later. Earlier versions had a bug that filtered out this trailer inadvertently.

If the service cannot bind to port 5000 and 5001, it may fail to respond to requests. The ports used can be adjusted by editing service/appsettings.json and client/Program.cs.

Support

There is no support provided for this example code.

The existence of this example does not imply that Microsoft recommends or does not recommend that this pattern be employed.

Legal

This example is copyright 2020 Microsoft Corporation. It is released under the MIT license.

Trademarks: This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.