diff --git a/aspnetcore/grpc/netstandard.md b/aspnetcore/grpc/netstandard.md new file mode 100644 index 000000000000..a9bb959f692a --- /dev/null +++ b/aspnetcore/grpc/netstandard.md @@ -0,0 +1,85 @@ +--- +title: Use gRPC client with .NET Standard 2.0 +author: jamesnk +description: Learn how to use the .NET gRPC client in apps and libraries that support .NET Standard 2.0. +monikerRange: '>= aspnetcore-3.0' +ms.author: jamesnk +ms.date: 3/11/2021 +no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] +uid: grpc/netstandard +--- +# Use gRPC client with .NET Standard 2.0 + +By [James Newton-King](https://twitter.com/jamesnk) + +This article discusses how to use the .NET gRPC client with .NET implementations that support [.NET Standard 2.0](/dotnet/standard/net-standard). + +## .NET implementations + +The following .NET implementations (or later) support [Grpc.Net.Client](https://www.nuget.org/packages/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. + +```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" }); +``` + +For more information, see [Configure gRPC-Web with the .NET gRPC client](xref:grpc/browser#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 . + +Requirements and restrictions to using `WinHttpHandler`: + +* Windows 10 Build 19622 or later. +* A reference to the [System.Net.Http.WinHttpHandler](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/) NuGet package. +* Only unary and server streaming gRPC calls are supported. +* 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] +> .NET Framework support is in its early stages and requires using pre-release software. +> * Windows 10 Build 19622 or later is available as a [Windows Insiders](https://insider.windows.com/) build. +> * The required version of `System.Net.Http.WinHttpHandler` is not currently available on NuGet.org. The latest pre-release version is available on [this NuGet feed](https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet6/nuget/v3/index.json) should be used. + +## gRPC C# core-library + +An alternative option for .NET Framework and Xamarin is to use [gRPC C# core-library](https://grpc.io/docs/languages/csharp/quickstart/) 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 + +* +* +* [gRPC C# core-library](https://grpc.io/docs/languages/csharp/quickstart/) diff --git a/aspnetcore/grpc/supported-platforms.md b/aspnetcore/grpc/supported-platforms.md index 1d3dcc902559..f7d5575a3bd2 100644 --- a/aspnetcore/grpc/supported-platforms.md +++ b/aspnetcore/grpc/supported-platforms.md @@ -4,7 +4,7 @@ author: jamesnk description: Learn about the supported platforms for gRPC on .NET. monikerRange: '>= aspnetcore-3.0' ms.author: jamesnk -ms.date: 01/22/2021 +ms.date: 3/11/2021 no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] uid: grpc/supported-platforms --- @@ -12,33 +12,42 @@ uid: grpc/supported-platforms By [James Newton-King](https://twitter.com/jamesnk) -This article discusses the requirements and supported platforms for using gRPC with .NET. +This article discusses the requirements and supported platforms for using gRPC with .NET. There are different requirements for the two major gRPC workloads: -gRPC takes advantage of advanced features available in HTTP/2. HTTP/2 isn't supported everywhere, but a second wire-format using HTTP/1.1 is available for gRPC: +* [Hosting gRPC services in ASP.NET Core](#aspnet-core-grpc-server-requirements) +* [Calling gRPC from .NET client apps](#net-grpc-client-requirements) + +## Wire-formats + +gRPC takes advantage of advanced features available in HTTP/2. HTTP/2 isn't supported everywhere, but a second wire-format using HTTP/1.1 is available for gRPC: * [`application/grpc`](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md) - gRPC over HTTP/2 is how gRPC is typically used. -* [`application/grpc-web`](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) - gRPC-Web modifies the gRPC protocol to be compatible with HTTP/1.1. gRPC-Web can be used in more places, notably it is callable by browser apps. Two advanced gRPC features are no longer supported: client streaming and bidirectional streaming. +* [`application/grpc-web`](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) - gRPC-Web modifies the gRPC protocol to be compatible with HTTP/1.1. gRPC-Web can be used in more places. gRPC-Web can be used by browser apps and in networks without complete support for HTTP/2. Two advanced gRPC features are no longer supported: client streaming and bidirectional streaming. + +gRPC on .NET supports both wire-formats. `application/grpc` is used by default. gRPC-Web must be configured on the client and the server for successful gRPC-Web calls. For information on setting up gRPC-Web, see . -gRPC on .NET supports both wire-formats. gRPC over HTTP/2 is used by default. For information on setting up gRPC-Web, see . +## ASP.NET Core gRPC server requirements -## Device requirements +Hosting gRPC services with ASP.NET Core requires .NET Core 3.x or later. + +> [!div class="checklist"] +> +> * .NET 5 or later +> * .NET Core 3 -gRPC on .NET supports any device that .NET Core supports. +ASP.NET Core gRPC services can be hosted on all operating system that .NET Core supports. > [!div class="checklist"] > > * Windows > * Linux > * macOS† -> * Browsers‡ - -†[macOS doesn't support hosting ASP.NET Core apps with HTTPS](xref:grpc/troubleshoot#unable-to-start-aspnet-core-grpc-app-on-macos). gRPC clients on macOS can call remote services that use HTTPS. -‡Blazor WebAssembly apps can call gRPC services with gRPC-Web. +†[macOS doesn't support hosting ASP.NET Core apps with HTTPS](xref:grpc/troubleshoot#unable-to-start-aspnet-core-grpc-app-on-macos). -## ASP.NET Core server requirements +### Supported ASP.NET Core servers -gRPC services can be hosted on all built-in ASP.NET Core servers. +All built-in ASP.NET Core servers are supported. > [!div class="checklist"] > @@ -53,18 +62,7 @@ gRPC services can be hosted on all built-in ASP.NET Core servers. For information about configuring ASP.NET Core servers to run gRPC, see . -## .NET version requirements - -gRPC on .NET supports .NET Core 3 and .NET 5 or later. - -> [!div class="checklist"] -> -> * .NET 5 or later -> * .NET Core 3 - -gRPC on .NET doesn't support running on .NET Framework and Xamarin. [gRPC C# core-library](https://grpc.io/docs/languages/csharp/quickstart/) is a third party library that supports .NET Framework and Xamarin. gRPC C-core is not supported by Microsoft. - -## Azure services +### Azure services > [!div class="checklist"] > @@ -75,6 +73,32 @@ gRPC on .NET doesn't support running on .NET Framework and Xamarin. [gRPC C# cor Work is in-progress to improve support for gRPC with HTTP/2 in Azure App Service. For more information, see [this GitHub issue](https://github.com/dotnet/AspNetCore/issues/9020). +## .NET gRPC client requirements + +The [Grpc.Net.Client](https://www.nuget.org/packages/Grpc.Net.Client/) package supports gRPC calls over HTTP/2 on .NET Core 3 and .NET 5 or later. + +Limited support is available for gRPC over HTTP/2 on .NET Framework. Other .NET versions such as UWP, Xamarin and Unity don't have required HTTP/2 support, and must use gRPC-Web instead. + +The following table lists .NET implementations and their gRPC client support: + +| .NET implementation | gRPC over HTTP/2 | gRPC-Web | +|----------------------------------------------|--------------------|------------| +| .NET 5 or later | ✔️ | ✔️ | +| .NET Core 3 | ✔️ | ✔️ | +| .NET Core 2.1 | ❌ | ✔️ | +| .NET Framework 4.6.1 | ⚠️† | ✔️ | +| Blazor WebAssembly | ❌ | ✔️ | +| Mono 5.4 | ❌ | ✔️ | +| Xamarin.iOS 10.14 | ❌ | ✔️ | +| Xamarin.Android 8.0 | ❌ | ✔️ | +| Universal Windows Platform 10.0.16299 | ❌ | ✔️ | +| Unity 2018.1 | ❌ | ✔️ | + +†.NET Framework requires to be configured and Windows 10 Build 19622 or later. + +Using `Grpc.Net.Client` on .NET Framework or with gRPC-Web requires additional configuration. For more information, see . + ## Additional resources +* * [gRPC C# core-library](https://grpc.io/docs/languages/csharp/quickstart/) diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index d6193f4a43d2..1c9979aecc19 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -754,6 +754,8 @@ uid: grpc/deadlines-cancellation - name: Transient fault handling uid: grpc/retries + - name: .NET Standard 2.0 support + uid: grpc/netstandard - name: gRPC services with ASP.NET Core uid: grpc/aspnetcore - name: Supported platforms