.NET での gRPC のトラブルシューティング

作成者: James Newton-King

このドキュメントでは、.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 Core クライアントは、サーバー アドレスで 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;
    });

警告

信頼されていない証明書は、アプリの開発時にのみ使用してください。 実稼働アプリでは、常に有効な証明書を使用する必要があります。

.NET Core クライアントで安全でない 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 に設定する必要があります。 詳細については、Asp.Net Core 3.x: .NET クライアントで安全でない gRPC サービスを呼び出す場合に関するページを参照してください。

重要

セキュリティで保護されていない gRPC サービスは、HTTP/2 専用ポートでホストする必要があります。 詳細については、ASP.NET Core プロトコルのネゴシエーションに関する記事を参照してください。

MacOS で ASP.NET Core gRPC アプリを起動できない

Kestrel では、.NET 8 より前の macOS での TLS を使用する HTTP/2 はサポートされていません。 ASP.NET Core gRPC テンプレートとサンプルでは、既定で TLS を使用しています。 gRPC サーバーを起動しようとすると、次のエラー メッセージが表示されます。

Unable to bind to https://localhost:5001 on the IPv4 loopback interface:'HTTP/2 over TLS is not supported on macOS due to missing ALPN support.'. (IPv4 ループバック インターフェイスで https://localhost:5001 にバインドできません。'HTTP/2 over TLS は ALPN サポートがないため、macOS でサポートされていません。')

.NET 7 以前でこの問題を回避するには、TLS を "使わずに" HTTP/2 を使用するように Kestrel と gRPC クライアントを構成します。 これは開発時にのみ実行してください。 TLS を使用しないと、gRPC メッセージが暗号化されずに送信されます。 詳細については、Asp.Net Core 7.0: macOS で ASP.NET Core gRPC アプリを起動できない場合に関するページを参照してください。

gRPC C# アセットが .proto ファイルから生成されたコードでない

具象クライアントとサービス基本クラスの gRPC コード生成には、protobuf ファイルとツールをプロジェクトから参照する必要があります。 次のものを含める必要があります。

• <Protobuf> 項目グループで使用する .proto ファイル。 インポートされた .proto ファイルをプロジェクトで参照する必要があります。
• gRPC ツール パッケージ Grpc.Tools へのパッケージ参照。

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:型または名前空間の名前 'tMyGrpcServices' が見つかりませんでした (using ディレクティブまたはアセンブリ参照が指定されていることを確認してください)

この問題は次の方法で回避できます。

1. 新しい .NET Core クラス ライブラリ プロジェクトを作成します。
2. 新しいプロジェクトで、参照を追加して、.proto ファイルからの C# コード生成を有効にします。
   • 次のパッケージ参照を追加します。
     • Grpc.Tools
     • Grpc.Net.Client
     • Google.Protobuf
   • <Protobuf> 項目グループに .proto ファイルを追加します。
3. WPF アプリケーションで、新しいプロジェクトに参照を追加します。

WPF アプリケーションでは、新しいクラス ライブラリ プロジェクトから、gRPC によって生成された型を使用できます。

サブディレクトリでホストされている gRPC サービスの呼び出し

警告

多くのサードパーティ製 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" });

上記のコードでは次の操作が行われます。

• パス /MyApp を使用して SubdirectoryHandler を作成します。
• SubdirectoryHandler を使用するようにチャネルを構成します。
• SayHelloAsync を使用して gRPC サービスを呼び出します。 gRPC 呼び出しが https://localhost:5001/MyApp/greet.Greeter/SayHello に送信されます。

クライアント ファクトリは、SubdirectoryHandler で AddHttpMessageHandler を使用して構成することもできます。

HTTP/3 を使用するように gRPC クライアントを構成する

.NET gRPC クライアントは、.NET 6 以降で HTTP/3 をサポートします。 HTTP/3 がサポートされることを示す alt-svc 応答ヘッダーがサーバーからクライアントに送信された場合、クライアントは自動的にその接続を HTTP/3 にアップグレードします。 詳しくは、「ASP.NET Core Kestrel Web サーバーで HTTP/3 を使用する」を参照してください。

DelegatingHandler を使用すると、HTTP/3 の使用を gRPC クライアントに強制することができます。 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 パッケージは、protoc というバンドルされたネイティブ バイナリを使って .proto ファイルから .NET 型を生成します。 Alpine Linux のように Grpc.Tools のネイティブ バイナリがサポートしないプラットフォーム上で gRPC アプリを構築するには、追加の手順が必要です。

事前にコードを生成する

解決策の 1 つは、事前にコードを生成することです。

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 の場合、コミュニティが提供しているプロトコル バッファー コンパイラと gRPC プラグイン用パッケージが https://pkgs.alpinelinux.org/ に掲載されています。

# Build or install the binaries for your architecture.

# e.g. 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 ビルド統合ドキュメントを参照してください。