針對 .NET 上的 gRPC 進行疑難排解

作者:James Newton-King

Note

這不是這篇文章的最新版本。 關於目前版本,請參閱本文的 .NET 11 版本。

Warning

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

本文件探討在 .NET 上開發 gRPC 應用程式時發生的常見問題。

用戶端與服務 SSL/TLS 組態不相符

gRPC 範本和範例預設會使用傳輸層安全性 (TLS) 來保護 gRPC 服務。 gRPC 用戶端必須使用安全連線,才能成功呼叫受保護的 gRPC 服務。

您可以在應用程式啟動時寫入的記錄中,驗證 ASP.NET Core gRPC 服務是否正在使用 TLS。 該服務將在 HTTPS 端點上接聽:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

.NET 用戶端必須在伺服器位址中使用 https ,才能使用安全連線進行呼叫:

var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new Greeter.GreeterClient(channel);

所有 gRPC 用戶端實作都支援 TLS。 其他語言的 gRPC 用戶端通常需要以 SslCredentials 設定的通道。 SslCredentials 指定客戶端將使用的憑證,且必須用它來取代不安全的憑證。 如需設定不同 gRPC 用戶端實作以使用 TLS 的範例,請參閱 gRPC 驗證。

呼叫具有不受信任/無效憑證的 gRPC 服務

.NET gRPC 用戶端需要服務具有受信任的憑證。 呼叫沒有受信任憑證的 gRPC 服務時,會傳回下列錯誤訊息:

未處理的例外狀況。 System.Net.Http.HttpRequestException:無法建立 SSL 連線,請查看內部例外狀況。 ---> System.Security.Authentication.AuthenticationException:根據驗證程序,遠端憑證無效。

如果您要在本機測試應用程式,但 ASP.NET Core HTTPS 開發憑證不受信任,則可能會看到此錯誤。 如需修正此問題的指示,請參閱信任 Windows 和 macOS上的 ASP.NET Core HTTPS 開發憑證。

如果您要在另一部電腦上呼叫 gRPC 服務,但無法信任該憑證,則可以將 gRPC 用戶端設定為忽略無效的憑證。 下列程式碼會使用 HttpClientHandler.ServerCertificateCustomValidationCallback 以允許在沒有受信任憑證的情況下進行呼叫:

var handler = new HttpClientHandler();
handler.ServerCertificateCustomValidationCallback = 
    HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

gRPC 用戶端處理站允許在沒有受信任憑證的情況下進行呼叫。 使用 ConfigurePrimaryHttpMessageHandler 擴充方法可在用戶端上設定處理常式:


var services = new ServiceCollection();

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(() =>
    {
        var handler = new HttpClientHandler();
        handler.ServerCertificateCustomValidationCallback =
            HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

        return handler;
    });

Warning

不受信任的憑證只應在應用程式開發期間使用。 生產應用程式應該一律使用有效的憑證。

使用 .NET 用戶端呼叫不安全的 gRPC 服務

.NET gRPC 用戶端可透過在伺服器位址中指定http呼叫不安全的 gRPC 服務。 例如: GrpcChannel.ForAddress("http://localhost:5000") 。

根據應用程式所使用的 .NET 版本,呼叫不安全的 gRPC 服務還有一些額外需求:

Important

不安全的 gRPC 服務必須裝載在僅限 HTTP/2 的連接埠上。 如需詳細資訊,請參閱 ASP.NET Core 通訊協定交涉。

無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

Kestrel在 .NET 8 之前的 macOS 上,不支援搭配 TLS 的 HTTP/2。 ASP.NET Core gRPC 範本和範例預設會使用 TLS。 當您嘗試啟動 gRPC 伺服器時,將會看到下列錯誤訊息:

無法在 IPv4 回送介面上繫結至 https://localhost:5001:「由於缺少 ALPN 支援,macOS 不支援透過 TLS 的 HTTP/2。」。

若要在 .NET 7 或更早版本中解決此問題,請將 和 gRPC 用戶端設定 Kestrel 為 不使用 TLS 的 HTTP/2。 您只能在開發期間執行此動作。 不使用 TLS 會導致在沒有加密的情況下傳送 gRPC 訊息。 如需詳細資訊,請參閱 .NET 7 中的 ASP.NET Core:無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式。

gRPC C# 資產不是從 .proto 檔案產生的程式碼

具體用戶端和服務基底類別的 gRPC 程式碼產生作業需要從專案參考 protobuf 檔案和工具。 您必須包含:

欲了解更多關於生成 gRPC C# 資產的資訊,請參閱 使用 C# 的 gRPC 服務。

裝載 gRPC 服務的 ASP.NET Core Web 應用程式只需要產生的服務基底類別:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>

發出 gRPC 呼叫的 gRPC 用戶端應用程式只需要產生的具體用戶端:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

WPF 專案無法從 .proto 檔案產生 gRPC C# 資產

WPF 專案存在一個已知問題,導致 gRPC 程式碼產生作業無法正常運作。 在 WPF 專案中參考 Grpc.Tools 和 .proto 檔案所生成的任何 gRPC 類型,都會在使用時導致編譯錯誤:

錯誤 CS0246:找不到名為 'MyGrpcServices' 的類型或命名空間名稱 (是否遺漏 using 指令或組件參考?)

您可以透過下列方式解決此問題:

  1. 建立新的 .NET 類別庫專案。
  2. 在新專案中,新增參考以啟用從 .proto 檔案產生 C# 程式碼的功能:
  3. 在 WPF 應用程式中,新增新專案的參考。

WPF 應用程式可以使用新類別庫專案中 gRPC 產生的類型。

呼叫裝載在子目錄中的 gRPC 服務

Warning

許多第三方 gRPC 工具不支援子目錄中裝載的服務。 請考慮尋找將 gRPC 裝載為根目錄的方法。

發出 gRPC 呼叫時,會忽略 gRPC 通道位址的路徑元件。 例如,GrpcChannel.ForAddress("https://localhost:5001/ignored_path") 在為服務進行 gRPC 呼叫的路由時不會使用 ignored_path。

由於 gRPC 具有標準化的規範位址結構,因此會忽略位址路徑。 gRPC 位址結合了套件、服務和方法名稱:https://localhost:5001/PackageName.ServiceName/MethodName。

在某些情況下,應用程式需要包含具有 gRPC 呼叫的路徑。 例如,當 ASP.NET Core gRPC 應用程式裝載於 IIS 目錄,且該目錄必須包含在要求中時。 需要有路徑時,可以使用下列指定的自訂 SubdirectoryHandler 將其新增至 gRPC 呼叫:

public class SubdirectoryHandler : DelegatingHandler
{
    private readonly string _subdirectory;

    public SubdirectoryHandler(HttpMessageHandler innerHandler, string subdirectory)
        : base(innerHandler)
    {
        _subdirectory = subdirectory;
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var old = request.RequestUri;

        var url = $"{old.Scheme}://{old.Host}:{old.Port}";
        url += $"{_subdirectory}{request.RequestUri.AbsolutePath}";
        request.RequestUri = new Uri(url, UriKind.Absolute);

        return base.SendAsync(request, cancellationToken);
    }
}

SubdirectoryHandler 當 gRPC 通道建立時會使用。

var handler = new SubdirectoryHandler(new HttpClientHandler(), "/MyApp");

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

var reply = await client.SayHelloAsync(
                  new HelloRequest { Name = "GreeterClient" });

上述 程式碼:

  • 創建 SubdirectoryHandler 並設置路徑為 /MyApp。
  • 設定通道以使用 SubdirectoryHandler。
  • 使用 SayHelloAsync 呼叫 gRPC 服務。 gRPC 呼叫傳送至 https://localhost:5001/MyApp/greet.Greeter/SayHello。

或者,您可以使用 SubdirectoryHandler 為用戶端處理站設定 AddHttpMessageHandler。

將 gRPC 用戶端設定為使用 HTTP/3

.NET gRPC 用戶端在 .NET 6 或更新版本中支援 HTTP/3。 如果伺服器將指出伺服器支援 HTTP/3 的 alt-svc 回應標頭傳送給用戶端,則用戶端會將其連線自動升級至 HTTP/3。 如需詳細資訊,請參閱搭配 ASP.NET Core Kestrel 網頁伺服器使用 HTTP/3。

DelegatingHandler 可用來強制 gRPC 用戶端使用 HTTP/3。 強制使用 HTTP/3 可避免升級要求的額外負荷。 透過類似於下列內容的程式碼強制使用 HTTP/3:

public class Http3Handler : DelegatingHandler
{
    public Http3Handler() { }
    public Http3Handler(HttpMessageHandler innerHandler) : base(innerHandler) { }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.Version = HttpVersion.Version30;
        request.VersionPolicy = HttpVersionPolicy.RequestVersionExact;

        return base.SendAsync(request, cancellationToken);
    }
}

Http3Handler 當 gRPC 通道建立時會使用。 下列程式碼會建立設定為使用 Http3Handler 的通道。

var handler = new Http3Handler(new HttpClientHandler());

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

var reply = await client.SayHelloAsync(
                  new HelloRequest { Name = "GreeterClient" });

或者,您可以使用 Http3Handler 為用戶端處理站設定 AddHttpMessageHandler。

在 Alpine Linux 上建置 gRPC

Grpc.Tools 套件使用名為 .proto 的配套原生二進位檔案,從 檔案中產生 .NET 型別protoc。 若要在 Grpc.Tools 中的原生二進位檔案不支援的平台 (例如 Alpine Linux) 上建置 gRPC 應用程式,則需要執行其他步驟。

預先產生程式碼

其中一個解決方案是預先產生程式碼。

  1. 將 .proto 檔案和 Grpc.Tools 套件參考移至新專案。
  2. 將專案發行為 NuGet 套件,並將其上傳至 NuGet 提要。
  3. 更新應用程式以參考 NuGet 套件。

透過上述步驟,不再需要 Grpc.Tools 來建置應用程式,因為程式碼可預先產生。

自訂 Grpc.Tools 原生二進位檔案

Grpc.Tools 支援使用自訂原生二進位檔。 此功能可讓 gRPC 工具在其配套原生二進位檔案不支援的環境中執行。

建置或取得 protoc 和 grpc_csharp_plugin 原生二進位檔案,並將 Grpc.Tools 設定為使用這些檔案。 藉由設定下列環境變數來設定原生二進位檔案:

  • PROTOBUF_PROTOC - 完整路徑至協定緩衝區編譯器
  • GRPC_PROTOC_PLUGIN - 通往grpc_csharp_plugin的完整路徑

對於 Alpine Linux,可從 https://pkgs.alpinelinux.org/ 取得社群提供的 Protocol Buffers 編譯器及 gRPC 外掛程式套件。

# Build or install the binaries for your architecture.

# For Alpine Linux, the grpc-plugins package can be used.
# See https://pkgs.alpinelinux.org/package/edge/community/x86_64/grpc-plugins
apk add grpc-plugins  # Alpine Linux specific package installer

# Set environment variables for the built/installed protoc
# and grpc_csharp_plugin binaries
export PROTOBUF_PROTOC=/usr/bin/protoc
export GRPC_PROTOC_PLUGIN=/usr/bin/grpc_csharp_plugin

# When dotnet build runs, the Grpc.Tools NuGet package
# uses the binaries pointed to by the environment variables.
dotnet build

如需搭配不支援的架構使用 Grpc.Tools 的詳細資訊,請參閱 gRPC 建置整合文件。

來自 HttpClient.Timeout 的 gRPC 呼叫逾時

HttpClient 預設為 100 秒逾時。 若 GrpcChannel 設定為使用 HttpClient,長時間執行的 gRPC 串流呼叫若未在逾時時限內完成,則會遭到取消。

System.OperationCanceledException: The request was canceled due to the configured HttpClient.Timeout of 100 seconds elapsing.

有幾種方法可以修正此錯誤。 第一個是將 HttpClient.Timeout 設定為較大的值。 Timeout.InfiniteTimeSpan 會停用逾時:

var handler = new HttpClientHandler();

var httpClient = new HttpClient(handler) { Timeout = Timeout.InfiniteTimeSpan };
var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpClient = httpClient });
var client = new Greeter.GreeterClient(channel);

或者,避免建立 HttpClient,改為設定 GrpcChannel.HttpHandler:

var handler = new HttpClientHandler();

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

本文件探討在 .NET 上開發 gRPC 應用程式時發生的常見問題。

用戶端與服務 SSL/TLS 組態不相符

gRPC 範本和範例預設會使用傳輸層安全性 (TLS) 來保護 gRPC 服務。 gRPC 用戶端必須使用安全連線,才能成功呼叫受保護的 gRPC 服務。

您可以在應用程式啟動時寫入的記錄中,驗證 ASP.NET Core gRPC 服務是否正在使用 TLS。 該服務將在 HTTPS 端點上接聽:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

.NET 用戶端必須在伺服器位址中使用 https ,才能使用安全連線進行呼叫:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    var channel = GrpcChannel.ForAddress("https://localhost:5001");
    var client = new Greet.GreeterClient(channel);
}

所有 gRPC 用戶端實作都支援 TLS。 其他語言的 gRPC 用戶端通常需要以 SslCredentials 設定的通道。 SslCredentials 指定客戶端將使用的憑證,且必須用它來取代不安全的憑證。 如需設定不同 gRPC 用戶端實作以使用 TLS 的範例,請參閱 gRPC 驗證。

呼叫具有不受信任/無效憑證的 gRPC 服務

.NET gRPC 用戶端需要服務具有受信任的憑證。 呼叫沒有受信任憑證的 gRPC 服務時,會傳回下列錯誤訊息:

未處理的例外狀況。 System.Net.Http.HttpRequestException:無法建立 SSL 連線,請查看內部例外狀況。 ---> System.Security.Authentication.AuthenticationException:根據驗證程序,遠端憑證無效。

如果您要在本機測試應用程式,但 ASP.NET Core HTTPS 開發憑證不受信任,則可能會看到此錯誤。 如需修正此問題的指示,請參閱信任 Windows 和 macOS上的 ASP.NET Core HTTPS 開發憑證。

如果您要在另一部電腦上呼叫 gRPC 服務,但無法信任該憑證,則可以將 gRPC 用戶端設定為忽略無效的憑證。 下列程式碼會使用 HttpClientHandler.ServerCertificateCustomValidationCallback 以允許在沒有受信任憑證的情況下進行呼叫:

var handler = new HttpClientHandler();
handler.ServerCertificateCustomValidationCallback = 
    HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greet.GreeterClient(channel);

gRPC 用戶端處理站允許在沒有受信任憑證的情況下進行呼叫。 使用 ConfigurePrimaryHttpMessageHandler 擴充方法可在用戶端上設定處理常式:

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(() =>
    {
        var handler = new HttpClientHandler();
        handler.ServerCertificateCustomValidationCallback = 
            HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

        return handler;
    });

Warning

不受信任的憑證只應在應用程式開發期間使用。 生產應用程式應該一律使用有效的憑證。

使用 .NET 用戶端呼叫不安全的 gRPC 服務

.NET gRPC 用戶端可透過在伺服器位址中指定http呼叫不安全的 gRPC 服務。 例如: GrpcChannel.ForAddress("http://localhost:5000") 。

根據應用程式所使用的 .NET 版本,呼叫不安全的 gRPC 服務還有一些額外需求:

  • .NET 5 或更新版本須使用 Grpc.Net.Client 2.32.0 版或更新版本。

  • .NET Core 3.x 須設定額外的組態。 應用程式必須將 System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport 開關設定為 true:

    // This switch must be set before creating the GrpcChannel/HttpClient.
    AppContext.SetSwitch(
        "System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true);
    
    // The port number(5000) must match the port of the gRPC server.
    var channel = GrpcChannel.ForAddress("http://localhost:5000");
    var client = new Greet.GreeterClient(channel);
    

只有 .NET Core 3.x 才需要 System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport 參數。 該參數不會在 .NET 5 中執行任何動作,也不是必要項目。

Important

不安全的 gRPC 服務必須裝載在僅限 HTTP/2 的連接埠上。 如需詳細資訊,請參閱 ASP.NET Core 通訊協定交涉。

無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

Kestrel在 macOS 上的 .NET 8 之前,不支援搭配 TLS 的 HTTP/2。 ASP.NET Core gRPC 範本和範例預設會使用 TLS。 當您嘗試啟動 gRPC 伺服器時,將會看到下列錯誤訊息:

無法在 IPv4 回送介面上繫結至 https://localhost:5001:「由於缺少 ALPN 支援,macOS 不支援透過 TLS 的 HTTP/2。」。

若要在 .NET 7 或更早版本中解決此問題,請將 和 gRPC 用戶端設定 Kestrel 為 不使用 TLS 的 HTTP/2。 您只能在開發期間執行此動作。 不使用 TLS 會導致在沒有加密的情況下傳送 gRPC 訊息。

Kestrel 必須在 Program.cs 中設定未使用 TLS 的 HTTP/2 端點:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    // Setup a HTTP/2 endpoint without TLS.
    options.ListenLocalhost(<5287>, o => o.Protocols =
        HttpProtocols.Http2);
});
  • 在上述的程式碼中,將 localhost 連接埠號碼 5287 取代為 gRPC 服務專案內 HTTP 中指定的 HTTPS (而不是 Properties/launchSettings.json) 連接埠號碼。

在未使用 TLS 的情況下設定 HTTP/2 端點時,必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 HttpProtocols.Http1AndHttp2 不能使用,因為 TLS 是協商 HTTP/2 的必要條件。 如果未使用 TLS,與端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

gRPC 用戶端也必須設定為不使用 TLS。 如需詳細資訊,請參閱 使用 .NET 用戶端呼叫不安全的 gRPC 服務。

Warning

不使用 TLS 的 HTTP/2 只應在應用程式開發期間使用。 生產應用程式應該一律使用傳輸安全性。 如需詳細資訊,請參閱 ASP.NET Core 的 gRPC 安全性考量。

gRPC C# 資產不是從 .proto 檔案產生的程式碼

具體用戶端和服務基底類別的 gRPC 程式碼產生作業需要從專案參考 protobuf 檔案和工具。 您必須包含:

欲了解更多關於生成 gRPC C# 資產的資訊,請參閱 使用 C# 的 gRPC 服務。

裝載 gRPC 服務的 ASP.NET Core Web 應用程式只需要產生的服務基底類別:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>

發出 gRPC 呼叫的 gRPC 用戶端應用程式只需要產生的具體用戶端:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

WPF 專案無法從 .proto 檔案產生 gRPC C# 資產

WPF 專案存在一個已知問題,導致 gRPC 程式碼產生作業無法正常運作。 在 WPF 專案中參考 Grpc.Tools 和 .proto 檔案所生成的任何 gRPC 類型,都會在使用時導致編譯錯誤:

錯誤 CS0246:找不到名為 'MyGrpcServices' 的類型或命名空間名稱 (是否遺漏 using 指令或組件參考?)

您可以透過下列方式解決此問題:

  1. 建立新的 .NET 類別庫專案。
  2. 在新專案中,新增參考以啟用從 .proto 檔案產生 C# 程式碼的功能:
  3. 在 WPF 應用程式中,新增新專案的參考。

WPF 應用程式可以使用新類別庫專案中 gRPC 產生的類型。

呼叫裝載在子目錄中的 gRPC 服務

Warning

許多第三方 gRPC 工具不支援子目錄中裝載的服務。 請考慮尋找將 gRPC 裝載為根目錄的方法。

發出 gRPC 呼叫時,會忽略 gRPC 通道位址的路徑元件。 例如,GrpcChannel.ForAddress("https://localhost:5001/ignored_path") 在為服務進行 gRPC 呼叫的路由時不會使用 ignored_path。

由於 gRPC 具有標準化的規範位址結構,因此會忽略位址路徑。 gRPC 位址結合了套件、服務和方法名稱:https://localhost:5001/PackageName.ServiceName/MethodName。

在某些情況下,應用程式需要包含具有 gRPC 呼叫的路徑。 例如,當 ASP.NET Core gRPC 應用程式裝載於 IIS 目錄,且該目錄必須包含在要求中時。 需要有路徑時,可以使用下列指定的自訂 SubdirectoryHandler 將其新增至 gRPC 呼叫:

/// <summary>
/// A delegating handler that adds a subdirectory to the URI of gRPC requests.
/// </summary>
public class SubdirectoryHandler : DelegatingHandler
{
    private readonly string _subdirectory;

    public SubdirectoryHandler(HttpMessageHandler innerHandler, string subdirectory)
        : base(innerHandler)
    {
        _subdirectory = subdirectory;
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var old = request.RequestUri;

        var url = $"{old.Scheme}://{old.Host}:{old.Port}";
        url += $"{_subdirectory}{request.RequestUri.AbsolutePath}";
        request.RequestUri = new Uri(url, UriKind.Absolute);

        return base.SendAsync(request, cancellationToken);
    }
}

SubdirectoryHandler 當 gRPC 通道建立時會使用。

var handler = new SubdirectoryHandler(new HttpClientHandler(), "/MyApp");

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greet.GreeterClient(channel);

var reply = await client.SayHelloAsync(new HelloRequest { Name = ".NET" });

上述 程式碼:

  • 創建 SubdirectoryHandler 並設置路徑為 /MyApp。
  • 設定通道以使用 SubdirectoryHandler。
  • 使用 SayHelloAsync 呼叫 gRPC 服務。 gRPC 呼叫傳送至 https://localhost:5001/MyApp/greet.Greeter/SayHello。

或者,您可以使用 SubdirectoryHandler 為用戶端處理站設定 AddHttpMessageHandler。

將 gRPC 用戶端設定為使用 HTTP/3

.NET gRPC 用戶端在 .NET 6 或更新版本中支援 HTTP/3。 如果伺服器將指出伺服器支援 HTTP/3 的 alt-svc 回應標頭傳送給用戶端,則用戶端會將其連線自動升級至 HTTP/3。 如需如何在伺服器上啟用 HTTP/3 的資訊,請參閱搭配 ASP.NET Core Kestrel 網頁伺服器使用 HTTP/3。

預設會啟用 .NET 8 中的 HTTP/3 支援。 .NET 6 和 .NET 7 中的 HTTP/3 支援必須透過專案檔中的組態旗標來啟用:

<ItemGroup>
  <RuntimeHostConfigurationOption Include="System.Net.SocketsHttpHandler.Http3Support" Value="true" />
</ItemGroup>

System.Net.SocketsHttpHandler.Http3Support 也可以使用 AppContext.SetSwitch 來設定。

DelegatingHandler 可用來強制 gRPC 用戶端使用 HTTP/3。 強制使用 HTTP/3 可避免升級要求的額外負荷。 透過類似於下列內容的程式碼強制使用 HTTP/3:

/// <summary>
/// A delegating handler that changes the request HTTP version to HTTP/3.
/// </summary>
public class Http3Handler : DelegatingHandler
{
    public Http3Handler() { }
    public Http3Handler(HttpMessageHandler innerHandler) : base(innerHandler) { }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.Version = HttpVersion.Version30;
        request.VersionPolicy = HttpVersionPolicy.RequestVersionExact;

        return base.SendAsync(request, cancellationToken);
    }
}

Http3Handler 當 gRPC 通道建立時會使用。 下列程式碼會建立設定為使用 Http3Handler 的通道。

var handler = new Http3Handler(new HttpClientHandler());

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greet.GreeterClient(channel);

var reply = await client.SayHelloAsync(new HelloRequest { Name = ".NET" });

或者,您可以使用 Http3Handler 為用戶端處理站設定 AddHttpMessageHandler。

在 Alpine Linux 上建置 gRPC

Grpc.Tools 套件使用名為 .proto 的配套原生二進位檔案,從 檔案中產生 .NET 型別protoc。 若要在 Grpc.Tools 中的原生二進位檔案不支援的平台 (例如 Alpine Linux) 上建置 gRPC 應用程式,則需要執行其他步驟。

預先產生程式碼

其中一個解決方案是預先產生程式碼。

  1. 將 .proto 檔案和 Grpc.Tools 套件參考移至新專案。
  2. 將專案發行為 NuGet 套件,並將其上傳至 NuGet 提要。
  3. 更新應用程式以參考 NuGet 套件。

透過上述步驟,不再需要 Grpc.Tools 來建置應用程式,因為程式碼可預先產生。

自訂 Grpc.Tools 原生二進位檔案

Grpc.Tools 支援使用自訂原生二進位檔。 此功能可讓 gRPC 工具在其配套原生二進位檔案不支援的環境中執行。

建置或取得 protoc 和 grpc_csharp_plugin 原生二進位檔案,並將 Grpc.Tools 設定為使用這些檔案。 藉由設定下列環境變數來設定原生二進位檔案:

  • PROTOBUF_PROTOC - 完整路徑至協定緩衝區編譯器
  • GRPC_PROTOC_PLUGIN - grpc_csharp_plugin 的完整路徑

對於 Alpine Linux,可從 https://pkgs.alpinelinux.org/ 取得社群提供的 Protocol Buffers 編譯器及 gRPC 外掛程式套件。

# Build or install the binaries for your architecture.

# For Alpine Linux, the grpc-plugins package can be used.
#  See https://pkgs.alpinelinux.org/package/edge/community/x86_64/grpc-plugins
apk add grpc-plugins  # Alpine Linux specific package installer

# Set environment variables for the built/installed protoc
# and grpc_csharp_plugin binaries
export PROTOBUF_PROTOC=/usr/bin/protoc
export GRPC_PROTOC_PLUGIN=/usr/bin/grpc_csharp_plugin

# When dotnet build runs, the Grpc.Tools NuGet package
# uses the binaries pointed to by the environment variables.
dotnet build

如需搭配不支援的架構使用 Grpc.Tools 的詳細資訊,請參閱 gRPC 建置整合文件。

來自 HttpClient.Timeout 的 gRPC 呼叫逾時

HttpClient 預設逾時時間設為 100 秒。 若 GrpcChannel 設定為使用 HttpClient,長時間執行的 gRPC 串流呼叫若未在逾時時限內完成,則會遭到取消。

System.OperationCanceledException: The request was canceled due to the configured HttpClient.Timeout of 100 seconds elapsing.

有幾種方法可以修正此錯誤。 第一個是將 HttpClient.Timeout 設定為較大的值。 Timeout.InfiniteTimeSpan 會停用逾時:

var handler = new HttpClientHandler();

var httpClient = new HttpClient(handler) { Timeout = Timeout.InfiniteTimeSpan };
var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpClient = httpClient });
var client = new Greeter.GreeterClient(channel);

或者,避免建立 HttpClient,改為設定 GrpcChannel.HttpHandler:

var handler = new HttpClientHandler();

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

本文件探討在 .NET 上開發 gRPC 應用程式時發生的常見問題。

用戶端與服務 SSL/TLS 組態不相符

gRPC 範本和範例預設會使用傳輸層安全性 (TLS) 來保護 gRPC 服務。 gRPC 用戶端必須使用安全連線,才能成功呼叫受保護的 gRPC 服務。

您可以在應用程式啟動時寫入的記錄中,驗證 ASP.NET Core gRPC 服務是否正在使用 TLS。 該服務將在 HTTPS 端點上接聽:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

.NET 用戶端必須在伺服器位址中使用 https ,才能使用安全連線進行呼叫:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    var channel = GrpcChannel.ForAddress("https://localhost:5001");
    var client = new Greet.GreeterClient(channel);
}

所有 gRPC 用戶端實作都支援 TLS。 其他語言的 gRPC 用戶端通常需要以 SslCredentials 設定的通道。 SslCredentials 指定客戶端將使用的憑證,且必須用它來取代不安全的憑證。 如需設定不同 gRPC 用戶端實作以使用 TLS 的範例,請參閱 gRPC 驗證。

呼叫具有不受信任/無效憑證的 gRPC 服務

.NET gRPC 用戶端需要服務具有受信任的憑證。 呼叫沒有受信任憑證的 gRPC 服務時,會傳回下列錯誤訊息:

未處理的例外狀況。 System.Net.Http.HttpRequestException:無法建立 SSL 連線,請查看內部例外狀況。 ---> System.Security.Authentication.AuthenticationException:根據驗證程序,遠端憑證無效。

如果您要在本機測試應用程式,但 ASP.NET Core HTTPS 開發憑證不受信任,則可能會看到此錯誤。 如需修正此問題的指示,請參閱信任 Windows 和 macOS上的 ASP.NET Core HTTPS 開發憑證。

如果您要在另一部電腦上呼叫 gRPC 服務,但無法信任該憑證,則可以將 gRPC 用戶端設定為忽略無效的憑證。 下列程式碼會使用 HttpClientHandler.ServerCertificateCustomValidationCallback 以允許在沒有受信任憑證的情況下進行呼叫:

var handler = new HttpClientHandler();
handler.ServerCertificateCustomValidationCallback = 
    HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greet.GreeterClient(channel);

gRPC 用戶端處理站允許在沒有受信任憑證的情況下進行呼叫。 使用 ConfigurePrimaryHttpMessageHandler 擴充方法可在用戶端上設定處理常式:

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(() =>
    {
        var handler = new HttpClientHandler();
        handler.ServerCertificateCustomValidationCallback = 
            HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

        return handler;
    });

Warning

不受信任的憑證只應在應用程式開發期間使用。 生產應用程式應該一律使用有效的憑證。

使用 .NET 用戶端呼叫不安全的 gRPC 服務

.NET gRPC 用戶端可透過在伺服器位址中指定http呼叫不安全的 gRPC 服務。 例如: GrpcChannel.ForAddress("http://localhost:5000") 。

根據應用程式所使用的 .NET 版本,呼叫不安全的 gRPC 服務還有一些額外需求:

  • .NET 5 或更新版本須使用 Grpc.Net.Client 2.32.0 版或更新版本。

  • .NET Core 3.x 須設定額外的組態。 應用程式必須將 System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport 開關設定為 true:

    // This switch must be set before creating the GrpcChannel/HttpClient.
    AppContext.SetSwitch(
        "System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true);
    
    // The port number(5000) must match the port of the gRPC server.
    var channel = GrpcChannel.ForAddress("http://localhost:5000");
    var client = new Greet.GreeterClient(channel);
    

只有 .NET Core 3.x 才需要 System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport 參數。 該參數不會在 .NET 5 中執行任何動作,也不是必要項目。

Important

不安全的 gRPC 服務必須裝載在僅限 HTTP/2 的連接埠上。 如需詳細資訊,請參閱 ASP.NET Core 通訊協定交涉。

無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

Kestrel 在 .NET 8 之前的 macOS 上不支援搭配 TLS 的 HTTP/2。 ASP.NET Core gRPC 範本和範例預設會使用 TLS。 當您嘗試啟動 gRPC 伺服器時,將會看到下列錯誤訊息:

無法在 IPv4 回送介面上繫結至 https://localhost:5001:「由於缺少 ALPN 支援,macOS 不支援透過 TLS 的 HTTP/2。」。

若要在 .NET 7 或更早版本中解決此問題,請將 和 gRPC 用戶端設定 Kestrel 為 不使用 TLS 的 HTTP/2。 您只能在開發期間執行此動作。 不使用 TLS 會導致在沒有加密的情況下傳送 gRPC 訊息。

Kestrel 必須在 Program.cs 中設定不使用 TLS 的 HTTP/2 端點:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                // Setup a HTTP/2 endpoint without TLS.
                options.ListenLocalhost(5000, o => o.Protocols = 
                    HttpProtocols.Http2);
            });
            webBuilder.UseStartup<Startup>();
        });

在未使用 TLS 的情況下設定 HTTP/2 端點時,必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 HttpProtocols.Http1AndHttp2 不能使用,因為 TLS 是協商 HTTP/2 的必要條件。 如果未使用 TLS,與端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

gRPC 用戶端也必須設定為不使用 TLS。 如需詳細資訊,請參閱 使用 .NET 用戶端呼叫不安全的 gRPC 服務。

Warning

不使用 TLS 的 HTTP/2 只應在應用程式開發期間使用。 生產應用程式應該一律使用傳輸安全性。 如需詳細資訊,請參閱 ASP.NET Core 的 gRPC 安全性考量。

gRPC C# 資產不是從 .proto 檔案產生的程式碼

具體用戶端和服務基底類別的 gRPC 程式碼產生作業需要從專案參考 protobuf 檔案和工具。 您必須包含:

欲了解更多關於生成 gRPC C# 資產的資訊,請參閱 使用 C# 的 gRPC 服務。

裝載 gRPC 服務的 ASP.NET Core Web 應用程式只需要產生的服務基底類別:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>

發出 gRPC 呼叫的 gRPC 用戶端應用程式只需要產生的具體用戶端:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

WPF 專案無法從 .proto 檔案產生 gRPC C# 資產

WPF 專案存在一個已知問題,導致 gRPC 程式碼產生作業無法正常運作。 在 WPF 專案中參考 Grpc.Tools 和 .proto 檔案所生成的任何 gRPC 類型,都會在使用時導致編譯錯誤:

錯誤 CS0246:找不到名為 'MyGrpcServices' 的類型或命名空間名稱 (是否遺漏 using 指令或組件參考?)

您可以透過下列方式解決此問題:

  1. 建立新的 .NET 類別庫專案。
  2. 在新專案中,新增參考以啟用從 .proto 檔案產生 C# 程式碼的功能:
  3. 在 WPF 應用程式中,新增新專案的參考。

WPF 應用程式可以使用新類別庫專案中 gRPC 產生的類型。

呼叫裝載在子目錄中的 gRPC 服務

Warning

許多第三方 gRPC 工具不支援子目錄中裝載的服務。 請考慮尋找將 gRPC 裝載為根目錄的方法。

發出 gRPC 呼叫時,會忽略 gRPC 通道位址的路徑元件。 例如,GrpcChannel.ForAddress("https://localhost:5001/ignored_path") 在為服務進行 gRPC 呼叫的路由時不會使用 ignored_path。

由於 gRPC 具有標準化的規範位址結構,因此會忽略位址路徑。 gRPC 位址結合了套件、服務和方法名稱:https://localhost:5001/PackageName.ServiceName/MethodName。

在某些情況下,應用程式需要包含具有 gRPC 呼叫的路徑。 例如,當 ASP.NET Core gRPC 應用程式裝載於 IIS 目錄,且該目錄必須包含在要求中時。 需要有路徑時,可以使用下列指定的自訂 SubdirectoryHandler 將其新增至 gRPC 呼叫:

/// <summary>
/// A delegating handler that adds a subdirectory to the URI of gRPC requests.
/// </summary>
public class SubdirectoryHandler : DelegatingHandler
{
    private readonly string _subdirectory;

    public SubdirectoryHandler(HttpMessageHandler innerHandler, string subdirectory)
        : base(innerHandler)
    {
        _subdirectory = subdirectory;
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var old = request.RequestUri;

        var url = $"{old.Scheme}://{old.Host}:{old.Port}";
        url += $"{_subdirectory}{request.RequestUri.AbsolutePath}";
        request.RequestUri = new Uri(url, UriKind.Absolute);

        return base.SendAsync(request, cancellationToken);
    }
}

SubdirectoryHandler 當 gRPC 通道建立時會使用。

var handler = new SubdirectoryHandler(new HttpClientHandler(), "/MyApp");

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greet.GreeterClient(channel);

var reply = await client.SayHelloAsync(new HelloRequest { Name = ".NET" });

上述 程式碼:

  • 創建 SubdirectoryHandler 並設置路徑為 /MyApp。
  • 設定通道以使用 SubdirectoryHandler。
  • 使用 SayHelloAsync 呼叫 gRPC 服務。 gRPC 呼叫傳送至 https://localhost:5001/MyApp/greet.Greeter/SayHello。

或者,您可以使用 SubdirectoryHandler 為用戶端處理站設定 AddHttpMessageHandler。

來自 HttpClient.Timeout 的 gRPC 呼叫逾時

HttpClient 預設為 100 秒逾時。 若 GrpcChannel 設定為使用 HttpClient,長時間執行的 gRPC 串流呼叫若未在逾時時限內完成,則會遭到取消。

System.OperationCanceledException: The request was canceled due to the configured HttpClient.Timeout of 100 seconds elapsing.

有幾種方法可以修正此錯誤。 第一個是將 HttpClient.Timeout 設定為較大的值。 Timeout.InfiniteTimeSpan 會停用逾時:

var handler = new HttpClientHandler();

var httpClient = new HttpClient(handler) { Timeout = Timeout.InfiniteTimeSpan };
var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpClient = httpClient });
var client = new Greeter.GreeterClient(channel);

或者,避免建立 HttpClient,改為設定 GrpcChannel.HttpHandler:

var handler = new HttpClientHandler();

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

本文件探討在 .NET 上開發 gRPC 應用程式時發生的常見問題。

用戶端與服務 SSL/TLS 組態不相符

gRPC 範本和範例預設會使用傳輸層安全性 (TLS) 來保護 gRPC 服務。 gRPC 用戶端必須使用安全連線,才能成功呼叫受保護的 gRPC 服務。

您可以在應用程式啟動時寫入的記錄中,驗證 ASP.NET Core gRPC 服務是否正在使用 TLS。 該服務將在 HTTPS 端點上接聽:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

.NET 用戶端必須在伺服器位址中使用 https ,才能使用安全連線進行呼叫:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    var channel = GrpcChannel.ForAddress("https://localhost:5001");
    var client = new Greet.GreeterClient(channel);
}

所有 gRPC 用戶端實作都支援 TLS。 其他語言的 gRPC 用戶端通常需要以 SslCredentials 設定的通道。 SslCredentials 指定客戶端將使用的憑證,且必須用它來取代不安全的憑證。 如需設定不同 gRPC 用戶端實作以使用 TLS 的範例,請參閱 gRPC 驗證。

呼叫具有不受信任/無效憑證的 gRPC 服務

.NET gRPC 用戶端需要服務具有受信任的憑證。 呼叫沒有受信任憑證的 gRPC 服務時,會傳回下列錯誤訊息:

未處理的例外狀況。 System.Net.Http.HttpRequestException:無法建立 SSL 連線,請查看內部例外狀況。 ---> System.Security.Authentication.AuthenticationException:根據驗證程序,遠端憑證無效。

如果您要在本機測試應用程式,但 ASP.NET Core HTTPS 開發憑證不受信任,則可能會看到此錯誤。 如需修正此問題的指示,請參閱信任 Windows 和 macOS上的 ASP.NET Core HTTPS 開發憑證。

如果您要在另一部電腦上呼叫 gRPC 服務,但無法信任該憑證,則可以將 gRPC 用戶端設定為忽略無效的憑證。 下列程式碼會使用 HttpClientHandler.ServerCertificateCustomValidationCallback 以允許在沒有受信任憑證的情況下進行呼叫:

var handler = new HttpClientHandler();
handler.ServerCertificateCustomValidationCallback = 
    HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greet.GreeterClient(channel);

gRPC 用戶端處理站允許在沒有受信任憑證的情況下進行呼叫。 使用 ConfigurePrimaryHttpMessageHandler 擴充方法可在用戶端上設定處理常式:

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(() =>
    {
        var handler = new HttpClientHandler();
        handler.ServerCertificateCustomValidationCallback = 
            HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

        return handler;
    });

Warning

不受信任的憑證只應在應用程式開發期間使用。 生產應用程式應該一律使用有效的憑證。

使用 .NET 用戶端呼叫不安全的 gRPC 服務

.NET gRPC 用戶端可透過在伺服器位址中指定http呼叫不安全的 gRPC 服務。 例如: GrpcChannel.ForAddress("http://localhost:5000") 。

根據應用程式所使用的 .NET 版本,呼叫不安全的 gRPC 服務還有一些額外需求:

  • .NET 5 或更新版本須使用 Grpc.Net.Client 2.32.0 版或更新版本。

  • .NET Core 3.x 須設定額外的組態。 應用程式必須將 System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport 開關設定為 true:

    // This switch must be set before creating the GrpcChannel/HttpClient.
    AppContext.SetSwitch(
        "System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true);
    
    // The port number(5000) must match the port of the gRPC server.
    var channel = GrpcChannel.ForAddress("http://localhost:5000");
    var client = new Greet.GreeterClient(channel);
    

只有 .NET Core 3.x 才需要 System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport 參數。 該參數不會在 .NET 5 中執行任何動作,也不是必要項目。

Important

不安全的 gRPC 服務必須裝載在僅限 HTTP/2 的連接埠上。 如需詳細資訊,請參閱 ASP.NET Core 通訊協定交涉。

無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

Kestrel 在 .NET 8 之前的 macOS 上,不支援透過 TLS 的 HTTP/2。 ASP.NET Core gRPC 範本和範例預設會使用 TLS。 當您嘗試啟動 gRPC 伺服器時,將會看到下列錯誤訊息:

無法在 IPv4 回送介面上繫結至 https://localhost:5001:「由於缺少 ALPN 支援,macOS 不支援透過 TLS 的 HTTP/2。」。

若要在 .NET 7 或更早版本中解決此問題,請將 和 gRPC 用戶端設定 Kestrel 為 不使用 TLS 的 HTTP/2。 您只能在開發期間執行此動作。 不使用 TLS 會導致在沒有加密的情況下傳送 gRPC 訊息。

Kestrel 必須在 Program.cs 中設定未使用 TLS 的 HTTP/2 端點:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                // Setup a HTTP/2 endpoint without TLS.
                options.ListenLocalhost(5000, o => o.Protocols = 
                    HttpProtocols.Http2);
            });
            webBuilder.UseStartup<Startup>();
        });

在未使用 TLS 的情況下設定 HTTP/2 端點時,必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 HttpProtocols.Http1AndHttp2 不能使用,因為 TLS 是協商 HTTP/2 的必要條件。 如果未使用 TLS,與端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

gRPC 用戶端也必須設定為不使用 TLS。 如需詳細資訊,請參閱 使用 .NET 用戶端呼叫不安全的 gRPC 服務。

Warning

不使用 TLS 的 HTTP/2 只應在應用程式開發期間使用。 生產應用程式應該一律使用傳輸安全性。 如需詳細資訊,請參閱 ASP.NET Core 的 gRPC 安全性考量。

gRPC C# 資產不是從 .proto 檔案產生的程式碼

具體用戶端和服務基底類別的 gRPC 程式碼產生作業需要從專案參考 protobuf 檔案和工具。 您必須包含:

欲了解更多關於生成 gRPC C# 資產的資訊,請參閱 使用 C# 的 gRPC 服務。

裝載 gRPC 服務的 ASP.NET Core Web 應用程式只需要產生的服務基底類別:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>

發出 gRPC 呼叫的 gRPC 用戶端應用程式只需要產生的具體用戶端:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

WPF 專案無法從 .proto 檔案產生 gRPC C# 資產

WPF 專案存在一個已知問題,導致 gRPC 程式碼產生作業無法正常運作。 在 WPF 專案中參考 Grpc.Tools 和 .proto 檔案所生成的任何 gRPC 類型,都會在使用時導致編譯錯誤:

錯誤 CS0246:找不到名為 'MyGrpcServices' 的類型或命名空間名稱 (是否遺漏 using 指令或組件參考?)

您可以透過下列方式解決此問題:

  1. 建立新的 .NET 類別庫專案。
  2. 在新專案中,新增參考以啟用從 .proto 檔案產生 C# 程式碼的功能:
  3. 在 WPF 應用程式中,新增新專案的參考。

WPF 應用程式可以使用新類別庫專案中 gRPC 產生的類型。

呼叫裝載在子目錄中的 gRPC 服務

Warning

許多第三方 gRPC 工具不支援子目錄中裝載的服務。 請考慮尋找將 gRPC 裝載為根目錄的方法。

發出 gRPC 呼叫時,會忽略 gRPC 通道位址的路徑元件。 例如,GrpcChannel.ForAddress("https://localhost:5001/ignored_path") 在為服務進行 gRPC 呼叫的路由時不會使用 ignored_path。

由於 gRPC 具有標準化的規範位址結構,因此會忽略位址路徑。 gRPC 位址結合了套件、服務和方法名稱:https://localhost:5001/PackageName.ServiceName/MethodName。

在某些情況下,應用程式需要包含具有 gRPC 呼叫的路徑。 例如,當 ASP.NET Core gRPC 應用程式裝載於 IIS 目錄,且該目錄必須包含在要求中時。 需要有路徑時,可以使用下列指定的自訂 SubdirectoryHandler 將其新增至 gRPC 呼叫:

/// <summary>
/// A delegating handler that adds a subdirectory to the URI of gRPC requests.
/// </summary>
public class SubdirectoryHandler : DelegatingHandler
{
    private readonly string _subdirectory;

    public SubdirectoryHandler(HttpMessageHandler innerHandler, string subdirectory)
        : base(innerHandler)
    {
        _subdirectory = subdirectory;
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var old = request.RequestUri;

        var url = $"{old.Scheme}://{old.Host}:{old.Port}";
        url += $"{_subdirectory}{request.RequestUri.AbsolutePath}";
        request.RequestUri = new Uri(url, UriKind.Absolute);

        return base.SendAsync(request, cancellationToken);
    }
}

SubdirectoryHandler 當 gRPC 通道建立時會使用。

var handler = new SubdirectoryHandler(new HttpClientHandler(), "/MyApp");

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greet.GreeterClient(channel);

var reply = await client.SayHelloAsync(new HelloRequest { Name = ".NET" });

上述 程式碼:

  • 創建 SubdirectoryHandler 並設置路徑為 /MyApp。
  • 設定通道以使用 SubdirectoryHandler。
  • 使用 SayHelloAsync 呼叫 gRPC 服務。 gRPC 呼叫傳送至 https://localhost:5001/MyApp/greet.Greeter/SayHello。

或者,您可以使用 SubdirectoryHandler 為用戶端處理站設定 AddHttpMessageHandler。

來自 HttpClient.Timeout 的 gRPC 呼叫逾時

HttpClient 預設為 100 秒逾時。 若 GrpcChannel 設定為使用 HttpClient,長時間執行的 gRPC 串流呼叫若未在逾時時限內完成,則會遭到取消。

System.OperationCanceledException: The request was canceled due to the configured HttpClient.Timeout of 100 seconds elapsing.

有幾種方法可以修正此錯誤。 第一個是將 HttpClient.Timeout 設定為較大的值。 Timeout.InfiniteTimeSpan 會停用逾時設定:

var handler = new HttpClientHandler();

var httpClient = new HttpClient(handler) { Timeout = Timeout.InfiniteTimeSpan };
var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpClient = httpClient });
var client = new Greeter.GreeterClient(channel);

或者,避免建立 HttpClient,改為設定 GrpcChannel.HttpHandler:

var handler = new HttpClientHandler();

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);