gRPC client factory-integratie in .NET

Door James Newton-King

gRPC-integratie met HttpClientFactory biedt een gecentraliseerde manier om gRPC-clients te maken. Het kan worden gebruikt als alternatief voor het configureren van zelfstandige gRPC-clientexemplaren. Factory-integratie is beschikbaar in het NuGet-pakket Grpc.Net.ClientFactory .

De fabriek biedt de volgende voordelen:

• Biedt een centrale locatie voor het configureren van logische gRPC-clientexemplaren.
• Beheert de levensduur van de onderliggende HttpClientMessageHandler.
• Automatische doorgifte van deadline en annulering in een ASP.NET Core gRPC-service.

gRPC-clients registreren

Als u een gRPC-client wilt registreren, kan de algemene AddGrpcClient-extensiemethode worden gebruikt binnen een exemplaar van WebApplicationBuilder bij het toegangspunt van de app in Program.cs, waarbij u de gRPC-getypeerde clientklasse en het serviceadres opgeeft.

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

Het type gRPC-client wordt geregistreerd als tijdelijk met afhankelijkheidsinjectie (DI). De client kan nu rechtstreeks worden geïnjecteerd en gebruikt in typen die door DI zijn gemaakt. ASP.NET Core MVC-controllers, SignalR hubs en gRPC-services zijn plaatsen waar gRPC-clients automatisch kunnen worden geïnjecteerd:

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 configureren

HttpClientFactory creëert de door de gRPC-client gebruikte HttpMessageHandler. Standaardmethoden HttpClientFactory kunnen worden gebruikt om middleware voor uitgaande aanvragen toe te voegen of om de onderliggende HttpClientHandler van het HttpClient volgende te configureren.

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

Zie HTTP-aanvragen maken met IHttpClientFactory voor meer informatie.

Interceptors configureren

gRPC-interceptors kunnen worden toegevoegd aan clients met behulp van de AddInterceptor methode.

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

De voorgaande code:

• Hiermee wordt het GreeterClient type geregistreerd.
• Hiermee configureert u een LoggingInterceptor voor deze client. LoggingInterceptor wordt eenmalig aangemaakt en gedeeld tussen GreeterClient instanties.

Standaard wordt een interceptor eenmaal aangemaakt en gedeeld tussen clients. Dit gedrag kan worden overschreven door een bereik op te geven bij het registreren van een interceptor. De clientfactory kan worden geconfigureerd om een nieuwe interceptor voor elke client te maken door InterceptorScope.Client te specificeren.

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

Het maken van onderscheppers met cliëntbereik is handig wanneer een interceptor scoped of tijdelijke services van DI vereist.

Een gRPC-interceptor of kanaalreferentie kan worden gebruikt om metagegevens Authorization bij elke aanvraag te verzenden. Zie Een Bearer-token verzenden met gRPC-clientfactory voor meer informatie over het configureren van verificatie.

Kanaal configureren

Aanvullende configuratie kan worden toegepast op een kanaal met behulp van de ConfigureChannel methode:

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

ConfigureChannel wordt doorgegeven aan een GrpcChannelOptions exemplaar. Zie Clientopties configureren voor meer informatie.

Opmerking

Sommige eigenschappen worden op GrpcChannelOptions ingesteld voordat de ConfigureChannel callback wordt uitgevoerd:

• HttpHandler is ingesteld op het resultaat van ConfigurePrimaryHttpMessageHandler.
• LoggerFactory is ingesteld op de ILoggerFactory zoals opgelost vanuit DI.

Deze waarden kunnen worden overschreven door ConfigureChannel.

Aanmeldgegevens

Een verificatieheader kan worden toegevoegd aan gRPC-aanroepen met behulp van de AddCallCredentials methode:

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;
    });

Zie Bearer-token met gRPC-clientfactory voor meer informatie over het configureren van aanroepreferenties.

Deadline- en annuleringspropagatie

gRPC-clients die in een gRPC-service door de fabriek zijn gemaakt, kunnen worden geconfigureerd met EnableCallContextPropagation() om de deadline en het annuleringstoken automatisch door te geven aan onderliggende aanroepen. De EnableCallContextPropagation() extensiemethode is beschikbaar in het NuGet-pakket Grpc.AspNetCore.Server.ClientFactory .

Het doorgeven van de oproepcontext werkt door de deadline en het annuleringstoken van de huidige gRPC-aanvraagcontext te lezen en deze automatisch door te geven aan uitgaande oproepen die door de gRPC-client worden gedaan. Het propagateren van de oproepcontext is een uitstekende manier om ervoor te zorgen dat complexe en geneste gRPC-scenario's altijd de deadline en annulering doorgeven.

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

Standaard genereert EnableCallContextPropagation een fout als de client buiten de context van een gRPC-aanroep wordt gebruikt. De fout is ontworpen om u te waarschuwen dat er geen aanroepcontext is om door te geven. Als u de client buiten een aanroepcontext wilt gebruiken, onderdrukt u de fout wanneer de client is geconfigureerd met SuppressContextNotFoundErrors:

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

Zie Betrouwbare gRPC-services met deadlines en annulering voor meer informatie over deadlines en RPC-annulering.

Geïdentificeerde clients

Normaal gesproken wordt een gRPC-clienttype eenmaal geregistreerd en vervolgens rechtstreeks door DI in de constructor van een type geïnjecteerd. Er zijn echter scenario's waarin het handig is om meerdere configuraties voor één client te hebben. Bijvoorbeeld een client die gRPC-aanroepen uitvoert met en zonder verificatie.

Meerdere clients met hetzelfde type kunnen worden geregistreerd door elke client een naam te geven. Elke benoemde client kan een eigen configuratie hebben. De algemene AddGrpcClient extensiemethode heeft een overbelasting die een naamparameter bevat:

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();
    });

De voorgaande code:

• Registreert het GreeterClient type twee keer, waarbij een unieke naam voor elke naam wordt opgegeven.
• Hiermee configureert u verschillende instellingen voor elke benoemde client. De GreeterAuthenticated registratie voegt referenties toe aan het kanaal, zodat gRPC-aanroepen met het kanaal worden geverifieerd.

Een met naam opgegeven gRPC-client wordt in de app-code gemaakt met behulp van GrpcClientFactory. Het type en de naam van de gewenste client worden opgegeven met behulp van de algemene GrpcClientFactory.CreateClient methode:

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

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

Aanvullende bronnen

• GRPC-services aanroepen met de .NET-client
• Betrouwbare gRPC-services met deadlines en annulering
• HTTP-aanvragen met IHttpClientFactory - ASP.NET Core