Use gRPC client with .NET Standard 2.0

By James Newton-King

This article discusses how to use the .NET gRPC client with .NET implementations that support .NET Standard 2.0.

.NET implementations

The following .NET implementations (or later) support Grpc.Net.Client but don't have full support for HTTP/2:

  • .NET Core 2.1
  • .NET Framework 4.6.1
  • Mono 5.4
  • Xamarin.iOS 10.14
  • Xamarin.Android 8.0
  • Universal Windows Platform 10.0.16299
  • Unity 2018.1

The .NET gRPC client can call services from these .NET implementations with some additional configuration.

HttpHandler configuration

An HTTP provider must be configured using GrpcChannelOptions.HttpHandler. If a handler isn't configured, an error is thrown:

System.PlatformNotSupportedException: gRPC requires extra configuration to successfully make RPC calls on .NET implementations that don't have support for gRPC over HTTP/2. An HTTP provider must be specified using GrpcChannelOptions.HttpHandler. The configured HTTP provider must either support HTTP/2 or be configured to use gRPC-Web.

.NET implementations that don't support HTTP/2, such as UWP, Xamarin, and Unity, can use gRPC-Web as an alternative.

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions
    {
        HttpHandler = new GrpcWebHandler(new HttpClientHandler())
    });

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

Clients can also be created using the gRPC client factory. An HTTP provider is configured using the ConfigurePrimaryHttpMessageHandler extension method.

builder.Services
    .AddGrpcClient<Greet.GreeterClient>(options =>
    {
        options.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(
        () => new GrpcWebHandler(new HttpClientHandler()));

For more information, see Configure gRPC-Web with the .NET gRPC client.

.NET Framework

.NET Framework has limited support for gRPC over HTTP/2. To enable gRPC over HTTP/2 on .NET Framework, configure the channel to use WinHttpHandler.

Requirements and restrictions to using WinHttpHandler:

  • Windows 10 Build 19622 or later.
  • A reference to System.Net.Http.WinHttpHandler version 6.0.0-preview.3.21201.4 or later.
  • Only unary and server streaming gRPC calls are supported.
  • Only gRPC calls over TLS are supported.
var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions
    {
        HttpHandler = new WinHttpHandler()
    });

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

Note

.NET Framework support is in its early stages and requires using pre-release software.

gRPC C# core-library

An alternative option for .NET Framework and Xamarin is to use gRPC C# core-library to make gRPC calls. It's a third party library that supports making gRPC calls over HTTP/2 on .NET Framework and Xamarin. gRPC C-core is not supported by Microsoft.

Additional resources