Grpc.Net.Client 2.51.0-pre1

Prefix Reserved
This is a prerelease version of Grpc.Net.Client.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Grpc.Net.Client --version 2.51.0-pre1                
NuGet\Install-Package Grpc.Net.Client -Version 2.51.0-pre1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Grpc.Net.Client" Version="2.51.0-pre1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Grpc.Net.Client --version 2.51.0-pre1                
#r "nuget: Grpc.Net.Client, 2.51.0-pre1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Grpc.Net.Client as a Cake Addin
#addin nuget:?package=Grpc.Net.Client&version=2.51.0-pre1&prerelease

// Install Grpc.Net.Client as a Cake Tool
#tool nuget:?package=Grpc.Net.Client&version=2.51.0-pre1&prerelease                

Grpc.Net.Client

Grpc.Net.Client is a gRPC client library for .NET.

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. For example, a service called Greeter generates a GreeterClient type with methods to call the service.

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's 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.

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

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 the client is used to make a gRPC call depends on the type of method called. 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
}

When using C# 8 or later, 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 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.

var client = new Echo.EchoClient(channel);
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;

For best performance, and to avoid unnecessary errors in the client and service, try to complete bi-directional streaming calls gracefully. A bi-directional call completes gracefully when the server has finished reading the request stream and the client has finished reading the response stream. The preceding sample call is one example of a bi-directional call that ends gracefully. In the call, the client:

  1. Starts a new bi-directional streaming call by calling EchoClient.Echo.
  2. Creates a background task to read messages from the service using ResponseStream.ReadAllAsync().
  3. Sends messages to the server with RequestStream.WriteAsync.
  4. Notifies the server it has finished sending messages with RequestStream.CompleteAsync().
  5. Waits until the background task has read all incoming messages.

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (730)

Showing the top 5 NuGet packages that depend on Grpc.Net.Client:

Package Downloads
Grpc.Net.ClientFactory

HttpClientFactory integration the for gRPC .NET client

Google.Api.Gax.Grpc

Additional support classes for Google gRPC API client libraries

OpenTelemetry.Exporter.OpenTelemetryProtocol

OpenTelemetry protocol exporter for OpenTelemetry .NET

Microsoft.Azure.Functions.Worker.Grpc

This library provides gRPC support for Azure Functions .NET Worker communication with the Azure Functions Host.

CouchbaseNetClient

The Official Couchbase .NET SDK.

GitHub repositories (89)

Showing the top 5 popular GitHub repositories that depend on Grpc.Net.Client:

Repository Stars
2dust/v2rayN
A GUI client for Windows, support Xray core and v2fly core and others
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
dotnet/runtime
.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.
dotnet/AspNetCore.Docs
Documentation for ASP.NET Core
dodyg/practical-aspnetcore
Practical samples of ASP.NET Core 9 RC2, 8.0, 7.0, 6.0, 5.0, 3.1, 2.2, and 2.1,projects you can use. Readme contains explanations on all projects.
Version Downloads Last updated
2.67.0-pre1 909 10/22/2024
2.66.0 888,558 9/20/2024
2.66.0-pre1 3,585 9/6/2024
2.65.0 2,359,699 7/27/2024
2.65.0-pre1 876 7/20/2024
2.64.0 277,029 7/19/2024
2.64.0-pre1 1,548 7/15/2024
2.63.0 3,156,094 5/24/2024
2.63.0-pre1 22,428 5/8/2024
2.62.0 4,640,105 3/29/2024
2.62.0-pre1 8,400 3/8/2024
2.61.0 3,054,758 2/22/2024
2.61.0-pre1 13,887 2/8/2024
2.60.0 17,543,319 1/3/2024
2.60.0-pre1 17,838 12/14/2023
2.59.0 4,508,418 11/8/2023
2.59.0-pre1 9,213 10/27/2023
2.58.0 1,469,265 10/19/2023
2.58.0-pre1 32,915 10/9/2023
2.57.0 3,456,123 9/6/2023
2.57.0-pre1 5,505 8/31/2023
2.56.0 933,225 8/25/2023
2.56.0-pre2 7,432 8/16/2023
2.56.0-pre1 22,606 8/3/2023
2.55.0 17,080,465 7/4/2023
2.55.0-pre1 11,017 6/23/2023
2.54.0 1,705,789 6/15/2023
2.54.0-pre1 13,685 5/25/2023
2.53.0 9,509,428 5/5/2023
2.53.0-pre1 25,690 4/12/2023
2.52.0 37,335,631 3/15/2023
2.52.0-pre1 13,698 3/3/2023
2.51.0 15,217,061 1/2/2023
2.51.0-pre1 22,040 12/7/2022
2.50.0 5,661,815 11/17/2022
2.50.0-pre1 36,767 11/3/2022
2.49.0 18,705,776 9/26/2022
2.49.0-pre1 10,763 9/1/2022
2.48.0 2,382,711 8/24/2022
2.48.0-pre1 4,280 8/17/2022
2.47.0 8,756,576 7/3/2022
2.47.0-pre1 5,444 6/23/2022
2.46.0 13,563,768 5/13/2022
2.46.0-pre1 9,565 4/28/2022
2.45.0 2,432,764 4/19/2022
2.45.0-pre1 15,099 4/7/2022
2.44.0 2,230,398 3/17/2022
2.44.0-pre1 22,361 3/9/2022
2.43.0 31,624,339 2/25/2022
2.43.0-pre1 24,296 1/28/2022
2.42.0 4,033,289 1/19/2022
2.42.0-pre1 15,950 12/30/2021
2.41.0 2,247,577 12/7/2021
2.41.0-pre1 40,695 11/12/2021
2.40.0 10,020,302 10/5/2021
2.40.0-pre1 8,624 9/9/2021
2.39.0 2,548,358 8/18/2021
2.39.0-pre1 97,332 8/6/2021
2.38.0 3,015,154 6/11/2021
2.38.0-pre1 3,614 6/4/2021
2.37.0 8,415,882 4/20/2021
2.37.0-pre1 3,442 4/14/2021
2.36.0 1,748,746 3/17/2021
2.36.0-pre1 3,607 3/9/2021
2.35.0 1,617,984 2/4/2021
2.35.0-pre1 4,280 1/26/2021
2.34.0 4,041,137 12/11/2020
2.34.0-pre1 5,806 12/1/2020
2.33.1 2,184,849 10/28/2020
2.33.1-pre1 2,956 10/22/2020
2.32.0 12,796,658 10/5/2020
2.32.0-pre1 16,662 9/8/2020
2.31.0 1,322,807 8/14/2020
2.31.0-pre2 3,182 8/3/2020
2.30.0 641,227 7/16/2020
2.30.0-pre1 17,193 6/17/2020
2.29.0 1,230,212 5/27/2020
2.29.0-pre1 7,675 5/15/2020
2.28.0 914,070 4/9/2020
2.28.0-pre2 20,943 3/11/2020
2.28.0-pre1 10,126 3/3/2020
2.27.0 1,970,269 2/7/2020
2.27.0-pre1 27,926 1/24/2020
2.26.0 1,618,344 12/19/2019
2.26.0-pre1 3,014 12/10/2019
2.25.0 1,075,945 11/7/2019
2.25.0-pre1 2,906 11/1/2019
2.24.0 519,501 10/21/2019
2.24.0-pre1 4,155 10/9/2019
2.23.2 586,761 9/20/2019
0.2.23-pre2 14,196 9/6/2019
0.2.23-pre1 14,517 8/21/2019
0.1.22-pre3 9,554 7/30/2019
0.1.22-pre2 16,905 7/2/2019
0.1.22-pre1 5,790 6/17/2019
0.1.21-pre1 3,125 6/4/2019