使用 ASP.NET Core 的 gRPC 服务

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

先决条件

Visual Studio

• 带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。

  

Visual Studio Code

• Visual Studio Code
• 用于 Visual Studio Code 的 C#（最新版本）
• .NET 8.0 SDK

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

Visual Studio for Mac

• Visual Studio 2022 for Mac（最新版本）

  重要

  Microsoft 已宣布停用 Visual Studio for Mac。 从 2024 年 8 月 31 日起，将不再支持 Visual Studio for Mac。 替代方案包括：

  • 带有 C# 开发工具包 和相关扩展（如 .NET MAUI 和 Unity）的 Visual Studio Code。
  • 在 Mac 虚拟机中的 Windows 上运行的 Visual Studio IDE。
  • 在云虚拟机中的 Windows 上运行的 Visual Studio IDE。

  有关详细信息，请参阅 Visual Studio for Mac 停用公告。

开始使用 ASP.NET Core 中的 gRPC 服务

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

Visual Studio

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

Visual Studio Code / Visual Studio for Mac

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

将 gRPC 服务添加到 ASP.NET Core 应用

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPC

在 Program.cs中：

• gRPC 通过 AddGrpc 方法启用。
• 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。

using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

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

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

服务器选项

gRPC 服务可由所有内置 ASP.NET Core 服务器托管。

• Kestrel
• TestServer
• IIS†
• HTTP.sys†

†需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本。

有关为 ASP.NET Core 应用选择正确服务器的详细信息，请参阅 ASP.NET Core 中的 Web 服务器实现。

Kestrel

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。 Kestrel 侧重于最佳性能和内存利用率，但它没有 HTTP.sys 中的某些高级功能，如端口共享。

Kestrel gRPC 终结点：

• 需要 HTTP/2。
• 应使用传输层安全性 (TLS) 进行保护。

HTTP/2

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

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

TLS

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

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

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

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

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

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

协议协商

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 不支持使用 .NET 8 之前版本的 ASP.NET Core gRPC 及 TLS。 使用 .NET 7 或更早版本时，在 macOS 上成功运行 gRPC 服务需要其他配置。 有关详细信息，请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用。

IIS

Internet Information Services (IIS) 是一种灵活、安全且可管理的 Web 服务器，用于托管 Web 应用（包括 ASP.NET Core）。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 IIS 托管 gRPC 服务。

必须将 IIS 配置为使用 TLS 和 HTTP/2。 有关详细信息，请参阅将 ASP.NET Core 与 IIS 上的 HTTP/2 配合使用。

HTTP.sys

HTTP.sys 是仅在 Windows 上运行的适用于 ASP.NET Core 的 Web 服务器。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 HTTP.sys 托管 gRPC 服务。

必须将 HTTP.sys 配置为使用 TLS 和 HTTP/2。 有关详细信息，请参阅 HTTP.sys Web 服务器 HTTP/2 支持。

非 ASP.NET Core 项目中的主机 gRPC

ASP.NET Core gRPC 服务器通常从 gRPC 模板创建。 模板创建的项目文件使用 Microsoft.NET.SDK.Web 作为 SDK：

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Microsoft.NET.SDK.Web SDK 值会自动添加对 ASP.NET Core 框架的引用。 该引用允许应用使用托管服务器所需的 ASP.NET Core 类型。

可以使用以下项目文件设置将 gRPC 服务器添加到 非 ASP.NET Core 项目：

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

上面的项目文件可完成以下操作：

• 不要使用 Microsoft.NET.SDK.Web 作为 SDK。
• 向 Microsoft.AspNetCore.App 添加框架引用。
  • 该框架引用允许非 ASP.NET Core 应用（例如 Windows 服务、WPF 应用或 WinForms 应用）使用 ASP.NET Core API。
  • 该应用现在可以使用 ASP.NET Core API 来启动 ASP.NET Core 服务器。
• 添加 gRPC 要求：
  • NuGet 包对 Grpc.AspNetCore 进行引用。
  • .proto 文件 。

有关使用 Microsoft.AspNetCore.App 框架引用的详细信息，请参阅使用 ASP.NET Core 共享框架。

与 ASP.NET Core API 集成

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

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

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

解析 gRPC 方法中的 HttpContext

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

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

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

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

其他资源

• 在 ASP.NET Core 中创建 .NET Core gRPC 客户端和服务器
• .NET 上的 gRPC 概述
• 使用 C# 的 gRPC 服务
• ASP.NET Core 中的 Kestrel Web 服务器