通过

适用于 .NET 的 gRPC 配置

  • 项目

注意

此版本不是本文的最新版本。 对于当前版本，请参阅此文的 .NET 8 版本。

警告

此版本的 ASP.NET Core 不再受支持。 有关详细信息，请参阅 .NET 和 .NET Core 支持策略。 对于当前版本，请参阅此文的 .NET 8 版本。

重要

此信息与预发布产品相关，相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

对于当前版本，请参阅此文的 .NET 8 版本。

配置服务选项

gRPC 服务在 Startup.cs 中使用 AddGrpc 进行配置。 配置选项位于 Grpc.AspNetCore.Server 包中。

下表描述了用于配置 gRPC 服务的选项：

选项 默认值 说明
MaxSendMessageSize null 可以从服务器发送的最大消息大小（以字节为单位）。 尝试发送超过配置的最大消息大小的消息会导致异常。 设置为 null时，消息的大小不受限制。
MaxReceiveMessageSize 4 MB 可以由服务器接收的最大消息大小（以字节为单位）。 如果服务器收到的消息超过此限制，则会引发异常。 增大此值可使服务器接收更大的消息，但可能会对内存消耗产生负面影响。 设置为 null时，消息的大小不受限制。
EnableDetailedErrors false 如果为 true，则当服务方法中引发异常时，会将详细异常消息返回到客户端。 默认值为 false。 将 EnableDetailedErrors 设置为 true 可能会泄漏敏感信息。
CompressionProviders gzip 用于压缩和解压缩消息的压缩提供程序的集合。 可以创建自定义压缩提供程序并将其添加到集合中。 默认已配置提供程序支持 gzip 压缩。
ResponseCompressionAlgorithm null 压缩算法用于压缩从服务器发送的消息。 该算法必须与 CompressionProviders 中的压缩提供程序匹配。 若要使算法可压缩响应，客户端必须通过在 grpc-accept-encoding 标头中进行发送来指示它支持算法。
ResponseCompressionLevel null 用于压缩从服务器发送的消息的压缩级别。
Interceptors None 随每个 gRPC 调用一起运行的侦听器的集合。 侦听器按注册顺序运行。 全局配置的侦听器在为单个服务配置的侦听器之前运行。

侦听器默认为每个请求设置生存期。 将调用侦听器构造函数，并从依赖关系注入 (DI) 解析参数。 还可以向 DI 注册侦听器类型，以重写其创建方式及其生存期。

与 ASP.NET Core 中间件相比，侦听器会提供类似的功能。 有关详细信息，请参阅 gRPC 侦听器与中间件。
IgnoreUnknownServices false 如果为 true，则对未知服务和方法的调用不会返回 UNIMPLEMENTED 状态，并且请求会传递到 ASP.NET Core 中的下一个注册中间件。

可以通过在 Startup.ConfigureServices 中向 AddGrpc 调用提供选项委托，为所有服务配置选项：

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.EnableDetailedErrors = true;
        options.MaxReceiveMessageSize = 2 * 1024 * 1024; // 2 MB
        options.MaxSendMessageSize = 5 * 1024 * 1024; // 5 MB
    });
}

用于单个服务的选项会替代 AddGrpc 中提供的全局选项，可以使用 AddServiceOptions<TService> 进行配置：

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc().AddServiceOptions<MyService>(options =>
    {
        options.MaxReceiveMessageSize = 2 * 1024 * 1024; // 2 MB
        options.MaxSendMessageSize = 5 * 1024 * 1024; // 5 MB
    });
}

服务侦听器默认为每个请求设置生存期。 使用 DI 注册侦听器类型会覆盖创建侦听器的方式及其生存期。

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.Interceptors.Add<LoggingInterceptor>();
    });
    services.AddSingleton<LoggingInterceptor>();
}

ASP.NET Core 服务器选项

Grpc.AspNetCore.Server 由 ASP.NET Core Web 服务器托管。 有许多适用于 ASP.NET Core 服务器的选项，包括 Kestrel、IIS 和 HTTP.sys。 每个服务器都提供了其他选项用于提供 HTTP 请求。

ASP.NET Core 应用使用的服务器是在应用启动代码中配置的。 默认服务器为 Kestrel。

有关不同服务器及其配置选项的详细信息，请参阅：

配置客户端选项

gRPC 客户端配置在 GrpcChannelOptions 中进行设置。 配置选项位于 Grpc.Net.Client 包中。

下表描述了用于配置 gRPC 通道的选项：

选项 默认值 说明
HttpHandler 新实例 用于进行 gRPC 调用的 HttpMessageHandler。 可以将客户端设置为配置自定义 HttpClientHandler，或将附加处理程序添加到 gRPC 调用的 HTTP 管道。 如果未指定 HttpMessageHandler，则会通过自动处置为通道创建新 HttpClientHandler 实例。
HttpClient null 用于进行 gRPC 调用的 HttpClient。 此设置是 HttpHandler 的替代项。
DisposeHttpClient false 如果设置为 true 且指定了 HttpMessageHandler 或 HttpClient，则在处置 GrpcChannel 时，将分别处置 HttpHandler 或 HttpClient。
LoggerFactory null 客户端用于记录有关 gRPC 调用的信息的 LoggerFactory。 可以通过依赖项注入来解析或使用 LoggerFactory.Create 来创建 LoggerFactory 实例。 有关配置日志记录的示例，请参阅 .NET 上的 gRPC 中的日志记录和诊断。
MaxSendMessageSize null 可以从客户端发送的最大消息大小（以字节为单位）。 尝试发送超过配置的最大消息大小的消息会导致异常。 设置为 null时，消息的大小不受限制。
MaxReceiveMessageSize 4 MB 可以由客户端接收的最大消息大小（以字节为单位）。 如果客户端收到的消息超过此限制，则会引发异常。 增大此值可使客户端接收更大的消息，但可能会对内存消耗产生负面影响。 设置为 null时，消息的大小不受限制。
Credentials null 一个 ChannelCredentials 实例。 凭据用于将身份验证元数据添加到 gRPC 调用。
CompressionProviders gzip 用于压缩和解压缩消息的压缩提供程序的集合。 可以创建自定义压缩提供程序并将其添加到集合中。 默认已配置提供程序支持 gzip 压缩。
ThrowOperationCanceledOnCancellation false 如果设置为 true，则在取消调用或超过其截止时间时，客户端将引发 OperationCanceledException。
UnsafeUseInsecureChannelCallCredentials false 如果设置为 true，则 CallCredentials 应用于不安全通道发出的 gRPC 调用。 通过不安全的连接发送身份验证标头具有安全隐患，不应在生产环境中执行。
MaxRetryAttempts 5 最大重试次数。 该值限制服务配置中指定的任何重试和 hedging 尝试值。单独设置该值不会启用重试。 重试在服务配置中启用，可以使用 ServiceConfig 来启用。 null 值会删除最大重试次数限制。 有关重试的详细信息，请参阅通过 gRPC 重试进行暂时性故障处理。
MaxRetryBufferSize 16 MB 在重试或 hedging 调用时，可用于存储发送的消息的最大缓冲区大小（以字节为单位）。 如果超出了缓冲区限制，则不会再进行重试，并且仅保留一个 hedging 调用，其他 hedging 调用将会取消。 此限制将应用于通过通道进行的所有调用。 值 null 移除最大重试缓冲区大小限制。
MaxRetryBufferPerCallSize 1 MB 在重试或 hedging 调用时，可用于存储发送的消息的最大缓冲区大小（以字节为单位）。 如果超出了缓冲区限制，则不会再进行重试，并且仅保留一个 hedging 调用，其他 hedging 调用将会取消。 此限制将应用于一个调用。 值 null 移除每个调用的最大重试缓冲区大小限制。
ServiceConfig null gRPC 通道的服务配置。 服务配置可以用于配置 gRPC 重试。

下面的代码：

  • 设置通道上发送和接收的最大消息大小。
  • 创建客户端。
static async Task Main(string[] args)
{
    var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions
    {
        MaxReceiveMessageSize = 5 * 1024 * 1024, // 5 MB
        MaxSendMessageSize = 2 * 1024 * 1024 // 2 MB
    });
    var client = new Greeter.GreeterClient(channel);

    var reply = await client.SayHelloAsync(
                      new HelloRequest { Name = "GreeterClient" });
    Console.WriteLine("Greeting: " + reply.Message);
}

请注意，未使用 GrpcChannelOptions 配置客户端侦听器。 相反，客户端侦听器是使用带有通道的 Intercept 扩展方法配置的。 此扩展方法位于 Grpc.Core.Interceptors 命名空间中。

static async Task Main(string[] args)
{
    var channel = GrpcChannel.ForAddress("https://localhost:5001");
    var callInvoker = channel.Intercept(new LoggingInterceptor());
    var client = new Greeter.GreeterClient(callInvoker);

    var reply = await client.SayHelloAsync(
                      new HelloRequest { Name = "GreeterClient" });
    Console.WriteLine("Greeting: " + reply.Message);
}

System.Net 处理程序选项

Grpc.Net.Client 使用派生自 HttpMessageHandler 的 HTTP 传输发出 HTTP 请求。 每个处理程序都提供其他选项用于发出 HTTP 请求。

处理程序在通道上配置，可通过设置 GrpcChannelOptions.HttpHandler 重写。 .NET Core 3 和 .NET 5 或更高版本默认使用 SocketsHttpHandler。 .NET Framework 上的 gRPC 客户端应用应配置 WinHttpHandler。

有关不同处理程序及其配置选项的详细信息，请参阅：

其他资源