適用於 .NET 組態的 gRPC

  • 發行項

設定服務選項

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 無 與每個 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 新增執行個體 使用 HttpMessageHandler 來進行 gRPC 呼叫。 用戶端可以設為設定自訂 HttpClientHandler 或將其他處理常式新增至 HTTP 管線以進行 gRPC 呼叫。 如果未指定 HttpMessageHandler，則會為具有自動處置功能的通道建立新的 HttpClientHandler 執行個體。
HttpClient null 使用 HttpClient 來進行 gRPC 呼叫。 此設定是 HttpHandler 的替代方案。
DisposeHttpClient false 如果設定為 true 並指定了 HttpMessageHandler 或 HttpClient，則在處置 GrpcChannel 時將分別處置 HttpHandler 或 HttpClient。
LoggerFactory null 用戶端使用 LoggerFactory 來記錄 gRPC 呼叫的相關資訊。 LoggerFactory 執行個體可以透過相依性插入進行解析，或使用 LoggerFactory.Create 建立。 如需設定記錄的範例，請參閱在 .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 重試次數上限。 此值會限制服務組態中指定的任何重試和對沖嘗試值。單獨設定此值並不會啟用重試。 服務組態中會啟用重試，您可以使用 ServiceConfig 來完成。 值 null 會移除重試次數上限。 如需重試的詳細資訊，請參閱使用 gRPC 重試的暫時性錯誤處理。
MaxRetryBufferSize 16 MB 在重試或對沖呼叫時，可用於儲存已傳送訊息的最大緩衝區大小（以位元組為單位）。 如果超出緩衝區限制，則不會再進行重試，並且除一個之外的所有對沖呼叫都將被取消。 此限制會套用至使用此通道進行的所有呼叫。 值 null 會移除重試緩衝區大小上限。
MaxRetryBufferPerCallSize 1 MB 在重試或對沖呼叫時，可用於儲存已傳送訊息的最大緩衝區大小（以位元組為單位）。 如果超出緩衝區限制，則不會再進行重試，並且除一個之外的所有對沖呼叫都將被取消。 此限制會套用至一個呼叫。 值 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。

如需不同處理常式及其組態選項的詳細資訊，請參閱：

其他資源