ContextQMD
Back to Aspnetcore

Use gRPC client with .NET Standard 2.0

aspnetcore/grpc/netstandard.md

latest4.4 KB
Original Source

Use gRPC client with .NET Standard 2.0

[!INCLUDE]

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
  • 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 and Unity, can use gRPC-Web as an alternative.

csharp
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 xref:Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.ConfigurePrimaryHttpMessageHandler%2A extension method.

csharp
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.

[!IMPORTANT] gRPC-Web requires the client and server to support it. gRPC-Web can be quickly configured by an ASP.NET Core gRPC server. Other gRPC server implementations require a proxy to support gRPC-Web.

.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 xref:System.Net.Http.WinHttpHandler.

Requirements and restrictions to using WinHttpHandler:

  • Windows 11 or later, Windows Server 2019 or later.
    • gRPC client is fully supported on Windows 11 or later.
    • gRPC client is partially supported on Windows Server 2019 and Windows Server 2022. Unary and server streaming methods are supported. Client and bidirectional streaming methods are not supported.
  • A reference to System.Net.Http.WinHttpHandler version 6.0.1 or later.
  • Configure WinHttpHandler on the channel using GrpcChannelOptions.HttpHandler.
  • .NET Framework 4.6.1 or later.
  • Only gRPC calls over TLS are supported.
csharp
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] The gRPC client on .NET Framework is slower than on modern .NET versions. For improved gRPC performance, apps should be updated to use modern .NET.

gRPC C# core-library

An alternative option for .NET Framework has been to use gRPC C# core-library to make gRPC calls. gRPC C# core-library is:

  • A third party library that supports making gRPC calls over HTTP/2 on .NET Framework.
  • Not supported by Microsoft.
  • In maintenance mode and will be deprecated in favour of gRPC for .NET.
  • Not recommended for new apps.

Additional resources