使用 ASP.NET Core 的 gRPC 服务gRPC services with ASP.NET Core

本文内容

本文档演示如何通过 ASP.NET Core 开始使用 gRPC 服务。

先决条件Prerequisites

Visual Studio Code 说明使用用于 ASP.NET Core 的 .NET Core CLI 开发功能，如项目创建。可在任何平台（macOS、Linux 或 Windows）上或在任何代码编辑器中遵循这些说明。如果使用 Visual Studio Code 以外的其他内容，则可能需要进行少量更改。

开始使用 ASP.NET Core 中的 gRPC 服务Get started with gRPC service in ASP.NET Core

查看或下载示例代码（如何下载）。

请参阅 gRPC 服务入门，获取关于如何创建 gRPC 项目的详细说明。

在命令行中运行 dotnet new grpc -o GrpcGreeter。

将 gRPC 服务添加到 ASP.NET Core 应用Add gRPC services to an ASP.NET Core app

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPCConfigure gRPC

在 Startup.cs 中 ：

  • gRPC 通过 AddGrpc 方法启用。
  • 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。
  1. public class Startup
  2. {
  3.     // This method gets called by the runtime. Use this method to add services to the container.
  4.     // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
  5.     public void ConfigureServices(IServiceCollection services)
  6.     {
  7.         services.AddGrpc();
  8.     }
  10.     // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
  11.     public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  12.     {
  13.         if (env.IsDevelopment())
  14.         {
  15.             app.UseDeveloperExceptionPage();
  16.         }
  18.         app.UseRouting();
  20.         app.UseEndpoints(endpoints =>
  21.         {
  22.             // Communication with gRPC endpoints must be made through a gRPC client.
  23.             // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
  24.             endpoints.MapGrpcService<GreeterService>();
  25.         });
  26.     }
  27. }

若要查看翻译为非英语语言的代码注释，请在 此 GitHub 讨论问题中告诉我们。

ASP.NET Core 中间件和功能共享路由管道，因此可以将应用配置为提供其他请求处理程序。其他请求处理程序（如 MVC 控制器）与已配置的 gRPC 服务并行工作。

配置 KestrelConfigure Kestrel

Kestrel gRPC 终结点：

HTTP/2HTTP/2

gRPC 需要 HTTP/2。适用于 ASP.NET Core 的 gRPC 验证 HttpRequest.Protocol 为 HTTP/2。

Kestrel 在大多数新式操作系统上支持 HTTP/2。默认情况下，Kestrel 终结点配置为支持 HTTP/1.1 和 HTTP/2 连接。

TLSTLS

用于 gRPC 的 Kestrel 终结点应使用 TLS 进行保护。在开发环境中，当存在 ASP.NET Core 开发证书时，会在 https://localhost:5001 自动创建使用 TLS 进行保护的终结点。不需要任何配置。https 前缀验证 Kestrel 终结点是否正在使用 TLS。

在生产环境中，必须显式配置 TLS。以下 appsettings.json 示例中提供了使用 TLS 进行保护的 HTTP/2 终结点 ：

  1. {
  2.   "Kestrel": {
  3.     "Endpoints": {
  4.       "HttpsInlineCertFile": {
  5.         "Url": "https://localhost:5001",
  6.         "Protocols": "Http2",
  7.         "Certificate": {
  8.           "Path": "<path to .pfx file>",
  9.           "Password": "<certificate password>"
  10.         }
  11.       }
  12.     }
  13.   }
  14. }

或者，可以在 Program.cs 中配置 Kestrel 终结点 ：

  1. public static IHostBuilder CreateHostBuilder(string[] args) =>
  2.     Host.CreateDefaultBuilder(args)
  3.         .ConfigureWebHostDefaults(webBuilder =>
  4.         {
  5.             webBuilder.ConfigureKestrel(options =>
  6.             {
  7.                 options.Listen(IPAddress.Any, 5001, listenOptions =>
  8.                 {
  9.                     listenOptions.Protocols = HttpProtocols.Http2;
  10.                     listenOptions.UseHttps("<path to .pfx file>", 
  11.                         "<certificate password>");
  12.                 });
  13.             });
  14.             webBuilder.UseStartup<Startup>();
  15.         });

协议协商Protocol negotiation

TLS 的用途不仅限于保护通信。当终结点支持多个协议时，TLS 应用程序层协议协商 (ALPN) 握手可用于协商客户端与服务器之间的连接协议。此协商确定连接是使用 HTTP/1.1 还是 HTTP/2。

如果在不使用 TLS 的情况下配置了 HTTP/2 终结点，则必须将终结点的 ListenOptions.Protocols 设置为 HttpProtocols.Http2。如果没有 TLS，则无法使用具有多个协议（例如 HttpProtocols.Http1AndHttp2）的终结点，因为没有协商。到不安全终结点的所有连接均默认为 HTTP/1.1，且 gRPC 调用会失败。

有关使用 Kestrel 启用 HTTP/2 和 TLS 的详细信息，请参阅 Kestrel 终结点配置。

备注

macOS 不支持 ASP.NET Core gRPC 及 TLS。在 macOS 上成功运行 gRPC 服务需要其他配置。有关详细信息，请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用。

与 ASP.NET Core API 集成Integration with ASP.NET Core APIs

gRPC 服务对 ASP.NET Core 功能（如依赖关系注入 (DI) 和 日志记录）具有完全访问权限。例如，服务实现可以通过构造函数从 DI 容器解析记录器服务：

  1. public class GreeterService : Greeter.GreeterBase
  2. {
  3.     public GreeterService(ILogger<GreeterService> logger)
  4.     {
  5.     }
  6. }

默认情况下，gRPC 服务实现可以解析具有任意生存期（单一实例、范围内或暂时）的其他 DI 服务。

解析 gRPC 方法中的 HttpContextResolve HttpContext in gRPC methods

gRPC API 提供对某些 HTTP/2 消息数据（如方法、主机、标头和尾部）的访问权限。访问是通过传递到每个 gRPC 方法的 ServerCallContext 参数进行的：

  1. public class GreeterService : Greeter.GreeterBase
  2. {
  3.     public override Task<HelloReply> SayHello(
  4.         HelloRequest request, ServerCallContext context)
  5.     {
  6.         return Task.FromResult(new HelloReply
  7.         {
  8.             Message = "Hello " + request.Name
  9.         });
  10.     }
  11. }

ServerCallContext 不提供对所有 ASP.NET API 中 HttpContext 的完全访问权限。GetHttpContext 扩展方法提供对在 ASP.NET API 中表示基础 HTTP/2 消息的 HttpContext 的完全访问权限：

  1. public class GreeterService : Greeter.GreeterBase
  2. {
  3.     public override Task<HelloReply> SayHello(
  4.         HelloRequest request, ServerCallContext context)
  5.     {
  6.         var httpContext = context.GetHttpContext();
  7.         var clientCertificate = httpContext.Connection.ClientCertificate;
  9.         return Task.FromResult(new HelloReply
  10.         {
  11.             Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
  12.         });
  13.     }
  14. }

Azure 应用服务不支持 gRPCgRPC not supported on Azure App Service

警告

Azure 应用服务或 IIS 当前不支持 ASP.NET Core gRPC。Http.Sys 的 HTTP/2 实现不支持 gRPC 依赖的 HTTP 响应尾随标头。有关详细信息，请参阅此 GitHub 问题。

其他资源Additional resources