7.1 KiB

Raw Blame History

title	author	description	monikerRange	ms.author	ms.date	uid
Call gRPC services with the .NET client	jamesnk	Learn how to call gRPC services with the .NET gRPC client.	>= aspnetcore-3.0	jamesnk	08/21/2019	grpc/client

Call gRPC services with the .NET client

A .NET gRPC client library is available in the Grpc.Net.Client NuGet package. This document explains how to:

Configure a gRPC client to call gRPC services.
Make gRPC calls to unary, server streaming, client streaming, and bi-directional streaming methods.

Configure gRPC client

gRPC clients are concrete client types that are generated from *.proto files. The concrete gRPC client has methods that translate to the gRPC service in the *.proto file.

A gRPC client is created from a channel. Start by using GrpcChannel.ForAddress to create a channel, and then use the channel to create a gRPC client:

var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new Greet.GreeterClient(channel);

A channel represents a long-lived connection to a gRPC service. When a channel is created it is configured with options related to calling a service. For example, the HttpClient used to make calls, the maximum send and receive message size, and logging can be specified on GrpcChannelOptions and used with GrpcChannel.ForAddress. For a complete list of options, see client configuration options.

Creating a channel can be an expensive operation and reusing a channel for gRPC calls offers performance benefits. Multiple concrete gRPC clients can be created from a channel, including different types of clients. Concrete gRPC client types are lightweight objects and can be created when needed.

var channel = GrpcChannel.ForAddress("https://localhost:5001");

var greeterClient = new Greet.GreeterClient(channel);
var counterClient = new Count.CounterClient(channel);

// Use clients to call gRPC services

GrpcChannel.ForAddress isn't the only option for creating a gRPC client. If you are calling gRPC services from an ASP.NET Core app, consider gRPC client factory integration. gRPC integration with HttpClientFactory offers a centralized alternative to creating gRPC clients.

[!NOTE] Additional configuration is required to call insecure gRPC services with the .NET client.

Make gRPC calls

A gRPC call is initiated by calling a method on the client. The gRPC client will handle message serialization and addressing the gRPC call to the correct service.

gRPC has different types of methods. How you use the client to make a gRPC call depends on the type of method you are calling. The gRPC method types are:

Unary
Server streaming
Client streaming
Bi-directional streaming

Unary call

A unary call starts with the client sending a request message. A response message is returned when the service finishes.

var client = new Greet.GreeterClient(channel);
var response = await client.SayHelloAsync(new HelloRequest { Name = "World" });

Console.WriteLine("Greeting: " + response.Message);
// Greeting: Hello World

Each unary service method in the *.proto file will result in two .NET methods on the concrete gRPC client type for calling the method: an asynchronous method and a blocking method. For example, on GreeterClient there are two ways of calling SayHello:

GreeterClient.SayHelloAsync - calls Greeter.SayHello service asynchronously. Can be awaited.
GreeterClient.SayHello - calls Greeter.SayHello service and blocks until complete. Don't use in asynchronous code.

Server streaming call

A server streaming call starts with the client sending a request message. ResponseStream.MoveNext() reads messages streamed from the service. The server streaming call is complete when ResponseStream.MoveNext() returns false.

var client = new Greet.GreeterClient(channel);
using (var call = client.SayHellos(new HelloRequest { Name = "World" }))
{
    while (await call.ResponseStream.MoveNext())
    {
        Console.WriteLine("Greeting: " + call.ResponseStream.Current.Message);
        // "Greeting: Hello World" is written multiple times
    }
}

If you are using C# 8 or later then the await foreach syntax can be used to read messages. The IAsyncStreamReader<T>.ReadAllAsync() extension method reads all messages from the response stream:

var client = new Greet.GreeterClient(channel);
using (var call = client.SayHellos(new HelloRequest { Name = "World" }))
{
    await foreach (var response in call.ResponseStream.ReadAllAsync())
    {
        Console.WriteLine("Greeting: " + response.Message);
        // "Greeting: Hello World" is written multiple times
    }
}

Client streaming call

A client streaming call starts without the client sending a message. The client can choose to send sends messages with RequestStream.WriteAsync. When the client has finished sending messages RequestStream.CompleteAsync should be called to notify the service. The call is finished when the service returns a response message.

var client = new Counter.CounterClient(channel);
using (var call = client.AccumulateCount())
{
    for (var i = 0; i < 3; i++)
    {
        await call.RequestStream.WriteAsync(new CounterRequest { Count = 1 });
    }
    await call.RequestStream.CompleteAsync();

    var response = await call;
    Console.WriteLine($"Count: {response.Count}");
    // Count: 3
}

Bi-directional streaming call

A bi-directional streaming call starts without the client sending a message. The client can choose to send messages with RequestStream.WriteAsync. Messages streamed from the service are accessible with ResponseStream.MoveNext() or ResponseStream.ReadAllAsync(). The bi-directional streaming call is complete when the ResponseStream has no more messages.

using (var call = client.Echo())
{
    Console.WriteLine("Starting background task to receive messages");
    var readTask = Task.Run(async () =>
    {
        await foreach (var response in call.ResponseStream.ReadAllAsync())
        {
            Console.WriteLine(response.Message);
            // Echo messages sent to the service
        }
    });

    Console.WriteLine("Starting to send messages");
    Console.WriteLine("Type a message to echo then press enter.");
    while (true)
    {
        var result = Console.ReadLine();
        if (string.IsNullOrEmpty(result))
        {
            break;
        }

        await call.RequestStream.WriteAsync(new EchoMessage { Message = result });
    }

    Console.WriteLine("Disconnecting");
    await call.RequestStream.CompleteAsync();
    await readTask;
}

During a bi-directional streaming call, the client and service can send messages to each other at any time. The best client logic for interacting with a bi-directional call varies depending upon the service logic.

7.1 KiB Raw Blame History