適用於 .NET 組態的 gRPC

發行項
11/06/2024

注意

這不是這篇文章的最新版本。如需目前的版本，請參閱本文的 .NET 9 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。如需目前的版本，請參閱本文的 .NET 9 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前的版本，請參閱本文的 .NET 9 版本。

設定服務選項

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。

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

共用方式為