Split gRPC supported platforms doc into hosting services and calling services sections

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 <xref:System.Net.Http.WinHttpHandler>.
+
+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
+
+* <xref:grpc/client>
+* <xref:grpc/browser>
+* [gRPC C# core-library](https://grpc.io/docs/languages/csharp/quickstart/)

aspnetcore/grpc/supported-platforms.md

@@ -4,41 +4,50 @@ 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
 ---
 # gRPC on .NET 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 <xref:grpc/browser>.
 
-gRPC on .NET supports both wire-formats. gRPC over HTTP/2 is used by default. For information on setting up gRPC-Web, see <xref:grpc/browser>.
+## 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&dagger;
-> * Browsers&Dagger;
-
-&dagger;[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.
 
-&Dagger;Blazor WebAssembly apps can call gRPC services with gRPC-Web.
+&dagger;[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 <xref:grpc/aspnetcore#server-options>.
 
-## .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                         | ⚠️&dagger;        | ✔️         |
+| Blazor WebAssembly                           | ❌                | ✔️         |
+| Mono 5.4                                     | ❌                | ✔️         |
+| Xamarin.iOS 10.14                            | ❌                | ✔️         |
+| Xamarin.Android 8.0                          | ❌                | ✔️         |
+| Universal Windows Platform 10.0.16299        | ❌                | ✔️         |
+| Unity 2018.1                                 | ❌                | ✔️         |
+
+&dagger;.NET Framework requires <xref:System.Net.Http.WinHttpHandler> 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 <xref:grpc/netstandard>.
+
 ## Additional resources
 
+* <xref:grpc/netstandard>
 * [gRPC C# core-library](https://grpc.io/docs/languages/csharp/quickstart/)

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