.NET での gRPC クライアントファクトリの統合

[アーティクル]
11/06/2024

Note

これは、この記事の最新バージョンではありません。現在のリリースについては、この記事の .NET 8 バージョンを参照してください。

警告

このバージョンの ASP.NET Core はサポート対象から除外されました。詳細については、「.NET および .NET Core サポートポリシー」を参照してください。現在のリリースについては、この記事の .NET 8 バージョンを参照してください。

重要

この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

現在のリリースについては、この記事の .NET 8 バージョンを参照してください。

作成者: James Newton-King

gRPC と HttpClientFactory の統合により、gRPC クライアントを一元的に作成する方法が提供されています。これは、スタンドアロンの gRPC クライアントインスタンスを構成するための代替手段として使用できます。ファクトリの統合は、Grpc.Net.ClientFactory NuGet パッケージで提供されています。

ファクトリには以下のような利点があります。

論理 gRPC クライアントインスタンスの構成を一元管理する場所となります。
基になる HttpClientMessageHandler の存続期間を管理します。
ASP.NET Core gRPC サービスで期限とキャンセルを自動伝達します。

gRPC クライアントを登録する

gRPC クライアントを登録するには、ジェネリック AddGrpcClient 拡張メソッドを Program.cs のアプリのエントリポイントにある WebApplicationBuilder のインスタンス内で使用して、gRPC の型指定されたクライアントクラスとサービスアドレスを指定することができます。

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

GRPC クライアントの種類は、依存関係の挿入 (DI) がある一時的なものとして登録されます。これで、DI によって作成される種類でクライアントを直接挿入し、使用できるようになります。 ASP.NET Core MVC コントローラー、SignalR ハブ、および gRPC サービスは、gRPC クライアントを自動的に挿入できる場所です。

public class AggregatorService : Aggregator.AggregatorBase
{
    private readonly Greeter.GreeterClient _client;

    public AggregatorService(Greeter.GreeterClient client)
    {
        _client = client;
    }

    public override async Task SayHellos(HelloRequest request,
        IServerStreamWriter<HelloReply> responseStream, ServerCallContext context)
    {
        // Forward the call on to the greeter service
        using (var call = _client.SayHellos(request))
        {
            await foreach (var response in call.ResponseStream.ReadAllAsync())
            {
                await responseStream.WriteAsync(response);
            }
        }
    }
}

HttpHandler を構成する

HttpClientFactory では、gRPC クライアントによって使用される HttpMessageHandler が作成されます。標準の HttpClientFactory メソッドを使用して、送信要求ミドルウェアを追加したり、HttpClient の基になる HttpClientHandler を構成したりすることができます。

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

詳細については、IHttpClientFactory を使用した HTTP 要求の作成に関するページを参照してください。

インターセプターを構成する

gRPC インターセプターは AddInterceptor メソッドを使ってクライアントに追加できます。

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .AddInterceptor<LoggingInterceptor>();

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

GreeterClient 型を登録します。
このクライアント用に LoggingInterceptor を構成します。 LoggingInterceptor は 1 回作成され、GreeterClient インスタンス間で共有されます。

既定では、インターセプターは 1 回作成され、クライアント間で共有されます。この動作は、インターセプターの登録時にスコープを指定することでオーバーライドできます。 InterceptorScope.Client を指定すると、クライアントごとに新しいインターセプターを作成するようにクライアントファクトリを構成できます。

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .AddInterceptor<LoggingInterceptor>(InterceptorScope.Client);

クライアントスコープのインターセプターを作成することは、DI のスコープ付きサービスまたは一時的なスコープ付きサービスがインターセプターに必要な場合に便利です。

gRPC インターセプターまたはチャネル資格情報は、各要求で Authorization メタデータを送信するために使用できます。認証の構成の詳細については、gRPC クライアントファクトリでのベアラートークンの送信に関する記事を参照してください。

チャネルを構成する

ConfigureChannel メソッドを使うと、チャネルに追加の構成を適用することができます。

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigureChannel(o =>
    {
        o.Credentials = new CustomCredentials();
    });

ConfigureChannel は GrpcChannelOptions インスタンスを渡されます。詳細については、クライアントオプションの構成に関するページを参照してください。

Note

GrpcChannelOptions 上の一部のプロパティは、ConfigureChannel コールバックが実行される前に設定されます。

HttpHandler は ConfigurePrimaryHttpMessageHandler の結果に設定されます。
LoggerFactory は、DI から解決された ILoggerFactory に設定されます。

これらの値は ConfigureChannel でオーバーライドできます。

資格情報を呼び出す

認証ヘッダーは、AddCallCredentials メソッドを使用して、gRPC 呼び出しに追加できます。

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .AddCallCredentials((context, metadata) =>
    {
        if (!string.IsNullOrEmpty(_token))
        {
            metadata.Add("Authorization", $"Bearer {_token}");
        }
        return Task.CompletedTask;
    });

呼び出しの資格情報の構成に関する詳細については、gRPC クライアントファクトリでのベアラートークンの送信に関する記事を参照してください。

期限とキャンセルの伝達

gRPC サービスでファクトリによって作成された gRPC クライアントは、EnableCallContextPropagation() を使用して、期限とキャンセルトークンが子の呼び出しに自動伝達されるように構成できます。 EnableCallContextPropagation() 拡張メソッドは Grpc.AspNetCore.Server.ClientFactory NuGet パッケージで提供されています。

呼び出しコンテキストの伝達は、現在の gRPC 要求コンテキストから期限とキャンセルトークンを読み取り、それらを、gRPC クライアントによって行われた送信呼び出しに自動的に伝達することによって機能します。呼び出しコンテキストの伝達は、複雑で入れ子になった gRPC のシナリオで、常に期限とキャンセルが確実に伝達されるようにする優れた方法です。

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .EnableCallContextPropagation();

既定では、クライアントが gRPC 呼び出しのコンテキスト外で使用されると、EnableCallContextPropagation によってエラーが発生します。このエラーは、伝達する呼び出しコンテキストが存在しないことを警告するために設計されています。クライアントを呼び出しコンテキストの外部で使用する場合は、クライアントが SuppressContextNotFoundErrors で構成されていると、エラーが抑制されます。

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .EnableCallContextPropagation(o => o.SuppressContextNotFoundErrors = true);

期限と RPC のキャンセルの詳細については、「期限とキャンセルを使用した信頼性の高い gRPC サービス」を参照してください。

名前付きクライアント

通常、gRPC クライアントの種類は一度登録され、DI によって型のコンストラクターに直接挿入されます。ただし、1 つのクライアントに複数の構成を設定すると便利な場合があります。たとえば、認証を使用して、または認証を使用せずに gRPC 呼び出しを行うクライアントなどです。

各クライアントに名前を付けることで、同じ種類の複数のクライアントを登録できます。名前付きの各クライアントには、独自の構成を含めることができます。ジェネリック AddGrpcClient 拡張メソッドには、name パラメーターを含むオーバーロードがあります。

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>("Greeter", o =>
    {
        o.Address = new Uri("https://localhost:5001");
    });

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>("GreeterAuthenticated", o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigureChannel(o =>
    {
        o.Credentials = new CustomCredentials();
    });

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

GreeterClient 型を 2 回登録し、それぞれに一意の名前を指定します。
名前付きクライアントごとに異なる設定を構成します。 GreeterAuthenticated 登録によって資格情報がチャネルに追加され、それを使用して実行された gRPC 呼び出しが認証されるようになります。

名前付き gRPC クライアントは、GrpcClientFactory を使用してアプリコードで作成されます。目的のクライアントの型と名前は、ジェネリック GrpcClientFactory.CreateClient メソッドを使用して指定されます。

public class AggregatorService : Aggregator.AggregatorBase
{
    private readonly Greeter.GreeterClient _client;

    public AggregatorService(GrpcClientFactory grpcClientFactory)
    {
        _client = grpcClientFactory.CreateClient<Greeter.GreeterClient>("GreeterAuthenticated");
    }
}

その他のリソース

ファクトリには以下のような利点があります。

論理 gRPC クライアントインスタンスの構成を一元管理する場所となります
基になる HttpClientMessageHandler の存続期間を管理します
ASP.NET Core gRPC サービスで期限とキャンセルを自動伝達

gRPC クライアントを登録する

gRPC クライアントを登録するには、ジェネリック AddGrpcClient 拡張メソッドを Startup.ConfigureServices 内で使用して、gRPC の型指定されたクライアントクラスとサービスアドレスを指定します。

services.AddGrpcClient<Greeter.GreeterClient>(o =>
{
    o.Address = new Uri("https://localhost:5001");
});

public class AggregatorService : Aggregator.AggregatorBase
{
    private readonly Greeter.GreeterClient _client;

    public AggregatorService(Greeter.GreeterClient client)
    {
        _client = client;
    }

    public override async Task SayHellos(HelloRequest request,
        IServerStreamWriter<HelloReply> responseStream, ServerCallContext context)
    {
        // Forward the call on to the greeter service
        using (var call = _client.SayHellos(request))
        {
            await foreach (var response in call.ResponseStream.ReadAllAsync())
            {
                await responseStream.WriteAsync(response);
            }
        }
    }
}

HttpHandler を構成する

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

詳細については、IHttpClientFactory を使用した HTTP 要求の作成に関するページを参照してください。

インターセプターを構成する

gRPC インターセプターは AddInterceptor メソッドを使ってクライアントに追加できます。

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .AddInterceptor<LoggingInterceptor>();

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

GreeterClient 型を登録します。
このクライアント用に LoggingInterceptor を構成します。 LoggingInterceptor は 1 回作成され、GreeterClient インスタンス間で共有されます。

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .AddInterceptor<LoggingInterceptor>(InterceptorScope.Client);

チャネルを構成する

ConfigureChannel メソッドを使うと、チャネルに追加の構成を適用することができます。

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigureChannel(o =>
    {
        o.Credentials = new CustomCredentials();
    });

ConfigureChannel は GrpcChannelOptions インスタンスを渡されます。詳細については、クライアントオプションの構成に関するページを参照してください。

Note

GrpcChannelOptions 上の一部のプロパティは、ConfigureChannel コールバックが実行される前に設定されます。

HttpHandler は ConfigurePrimaryHttpMessageHandler の結果に設定されます。
LoggerFactory は、DI から解決された ILoggerFactory に設定されます。

これらの値は ConfigureChannel でオーバーライドできます。

期限とキャンセルの伝達

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .EnableCallContextPropagation();

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .EnableCallContextPropagation(o => o.SuppressContextNotFoundErrors = true);

期限と RPC のキャンセルの詳細については、「期限とキャンセルを使用した信頼性の高い gRPC サービス」を参照してください。

名前付きクライアント

services
    .AddGrpcClient<Greeter.GreeterClient>("Greeter", o =>
    {
        o.Address = new Uri("https://localhost:5001");
    });

services
    .AddGrpcClient<Greeter.GreeterClient>("GreeterAuthenticated", o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigureChannel(o =>
    {
        o.Credentials = new CustomCredentials();
    });

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

GreeterClient 型を 2 回登録し、それぞれに一意の名前を指定します。
名前付きクライアントごとに異なる設定を構成します。 GreeterAuthenticated 登録によって資格情報がチャネルに追加され、それを使用して実行された gRPC 呼び出しが認証されるようになります。

public class AggregatorService : Aggregator.AggregatorBase
{
    private readonly Greeter.GreeterClient _client;

    public AggregatorService(GrpcClientFactory grpcClientFactory)
    {
        _client = grpcClientFactory.CreateClient<Greeter.GreeterClient>("GreeterAuthenticated");
    }
}

次の方法で共有

.NET での gRPC クライアント ファクトリの統合

gRPC クライアントを登録する

HttpHandler を構成する

インターセプターを構成する

チャネルを構成する

資格情報を呼び出す

期限とキャンセルの伝達

名前付きクライアント

その他のリソース

gRPC クライアントを登録する

HttpHandler を構成する

インターセプターを構成する

チャネルを構成する

期限とキャンセルの伝達

名前付きクライアント

その他のリソース

その他のリソース

.NET での gRPC クライアントファクトリの統合