Update docs on the recommended C# implementation (#1278)

* update README.md

* update implementation_comparison.md

* Update README.md

Co-authored-by: James Newton-King <[email protected]>

Co-authored-by: James Newton-King <[email protected]>

Author: jtattermusch

README.md

@@ -1,7 +1,5 @@
 # gRPC for .NET
 
-## Available now on .NET Core 3.0!
-
 gRPC is a modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere. gRPC enables client and server applications to communicate transparently, and simplifies the building of connected systems.
 
 gRPC functionality for .NET Core 3.0 includes:
@@ -10,10 +8,13 @@ gRPC functionality for .NET Core 3.0 includes:
 * [Grpc.Net.Client](https://www.nuget.org/packages/Grpc.Net.Client) – A gRPC client for .NET Core that builds upon the familiar `HttpClient`. The client uses new HTTP/2 functionality in .NET Core.
 * [Grpc.Net.ClientFactory](https://www.nuget.org/packages/Grpc.Net.ClientFactory) – gRPC client integration with `HttpClientFactory`. The client factory allows gRPC clients to be centrally configured and injected into your app with DI.
 
-Please note that gRPC for .NET does not replace [gRPC for C#](https://github.com/grpc/grpc/tree/master/src/csharp) (gRPC C# API over native C-core binaries). These implementations coexist and share many of the same APIs to avoid lock-in. There are currently no plans for one implementation to replace the other one. gRPC for C# is the recommended solution for frameworks that gRPC for .NET does not support, such as .NET Framework.
-
 For more information, see [An introduction to gRPC on .NET](https://docs.microsoft.com/aspnet/core/grpc/).
 
+## gRPC for .NET is now the recommended implementation!
+
+Starting from May 2021, gRPC for .NET is the recommended implemention of gRPC for C#. The original [gRPC for C#](https://github.com/grpc/grpc/tree/master/src/csharp) implementation (distributed as the `Grpc.Core` nuget package) is now in maintenance mode and will be deprecated in the future.
+See [blogpost](https://grpc.io/blog/grpc-csharp-future/) for more details.
+
 ## To start using gRPC for .NET
 
 The best place to start using gRPC for .NET is the gRPC template that comes with .NET Core 3.0. Use the template to [create a gRPC service website and client](https://docs.microsoft.com/aspnet/core/tutorials/grpc/grpc-start).

doc/implementation_comparison.md

@@ -11,14 +11,17 @@ This document summarizes the differences between the two available implementatio
 
 ## Criteria for choosing between grpc-dotnet and gRPC C#
 
-One might choose one or the other implementation mostly for one of these reasons
+Starting from May 2021, gRPC for .NET is the recommended implemention of gRPC for C#.
+The original [gRPC C#](https://github.com/grpc/grpc/tree/master/src/csharp) implementation (distributed as the `Grpc.Core` nuget package) is now in maintenance mode and will be deprecated in the future.
+See [blogpost](https://grpc.io/blog/grpc-csharp-future/) for more details.
 
-- avoid use of native code
-- ability to use one of the newer .NET Frameworks: grpc-dotnet requires at least .NET Core 3+ or .NET 5+ (.NET Core 3.1 LTS was released in December 2019 so legacy stacks might still be using an older framework)
-- want seamless integration with ASP.NET Core 3, dependency injection etc.
-- features available (see breakdown)
-- performance (while data we have data that seems to indicate that grpc-dotnet peforms at least as well as Grpc.Core, we strongly encourage to run your own benchmarks if performance matters for your application)
+Here are some key points in which the two implementation differ:
 
+- grpc-dotnet avoids the use of native code (while Grpc.Core use the native C-core library internally)
+- grpc-dotnet requires a newer version of .NET (see the "Framework supported" section)
+- grpc-dotnet server integrates seamlessly ASP.NET Core (and allows e.g. dependency injection)
+- performance (while data we have data that seems to indicate that grpc-dotnet peforms at least as well as Grpc.Core, we strongly encourage to run your own benchmarks if performance matters for your application)
+- features available (see breakdown below)
 ## Frameworks supported
 
 Grpc.Core supports a wide range of .NET Framework versions, included some very old ones. A more detailed overview is [here]( https://github.com/grpc/grpc/tree/master/src/csharp#supported-platforms)