.NET’te gRPC istemci fabrikası tümleştirmesi

Makale
11/06/2024

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Yayınlayan James Newton-King

ile HttpClientFactory gRPC tümleştirmesi, gRPC istemcileri oluşturmak için merkezi bir yol sunar. Tek başına gRPC istemci örneklerini yapılandırmaya alternatif olarak kullanılabilir. Fabrika tümleştirmesi Grpc.Net.ClientFactory NuGet paketinde kullanılabilir.

Fabrika aşağıdaki avantajları sunar:

Mantıksal gRPC istemci örneklerini yapılandırmak için merkezi bir konum sağlar.
Temel alınan HttpClientMessageHandleröğesinin ömrünü yönetir.
ASP.NET Core gRPC hizmetinde son tarih ve iptalin otomatik olarak yayılması.

gRPC istemcilerini kaydetme

GRPC istemcisini kaydetmek için genel AddGrpcClient uzantı yöntemi, gRPC türüne sahip istemci sınıfını ve hizmet adresini belirterek uygulamasının içindeki giriş noktasındaki Program.csbir örneği WebApplicationBuilder içinde kullanılabilir:

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

gRPC istemci türü, bağımlılık ekleme (DI) ile geçici olarak kaydedilir. İstemci artık doğrudan DI tarafından oluşturulan türlerde eklenebilir ve kullanılabilir. ASP.NET Core MVC denetleyicileri, SignalR hub'ları ve gRPC hizmetleri, gRPC istemcilerinin otomatik olarak eklenebileceği yerlerdir:

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'ı yapılandırma

HttpClientFactory , gRPC istemcisi tarafından kullanılan öğesini HttpMessageHandler oluşturur. Standart HttpClientFactory yöntemler giden istek ara yazılımı eklemek veya temel alınan HttpClientHandler HttpClientöğesini yapılandırmak için kullanılabilir:

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

Daha fazla bilgi için bkz . IHttpClientFactory kullanarak HTTP isteklerinde bulunma.

Kesme Noktası Oluşturucuları Yapılandırma

gRPC kesicileri yöntemi kullanılarak AddInterceptor istemcilere eklenebilir.

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

Yukarıdaki kod:

Türü kaydeder GreeterClient .
Bu istemci için bir LoggingInterceptor yapılandırılır. LoggingInterceptor bir kez oluşturulur ve örnekler arasında GreeterClient paylaşılır.

Varsayılan olarak, bir kesme noktası bir kez oluşturulur ve istemciler arasında paylaşılır. Bu davranış, bir kesme noktası kaydederken bir kapsam belirtilerek geçersiz kılınabilir. İstemci fabrikası, belirterek InterceptorScope.Clienther istemci için yeni bir kesme noktası oluşturacak şekilde yapılandırılabilir.

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

Bir kesme noktası DI'den kapsamlı veya geçici kapsamlı hizmetler gerektirdiğinde istemci kapsamlı kesme makineleri oluşturmak yararlıdır.

Her istekte meta veri göndermek Authorization için bir gRPC kesme noktası veya kanal kimlik bilgileri kullanılabilir. Kimlik doğrulamasını yapılandırma hakkında daha fazla bilgi için bkz . gRPC istemci fabrikası ile taşıyıcı belirteç gönderme.

Kanalı Yapılandır

Yöntem kullanılarak ConfigureChannel kanala ek yapılandırma uygulanabilir:

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

ConfigureChannel bir GrpcChannelOptions örnek geçirilir. Daha fazla bilgi için bkz . İstemci seçeneklerini yapılandırma.

Not

Geri çağırma çalıştırilmeden önce ConfigureChannel bazı özellikler ayarlanırGrpcChannelOptions:

HttpHandler , sonucuna ConfigurePrimaryHttpMessageHandlerayarlanır.
LoggerFactory , DI'den ILoggerFactory çözümlenene ayarlanır.

Bu değerler tarafından ConfigureChannelgeçersiz kılınabilir.

Çağrı kimlik bilgileri

gRPC çağrılarına şu yöntem kullanılarak AddCallCredentials bir kimlik doğrulama üst bilgisi eklenebilir:

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

Arama kimlik bilgilerini yapılandırma hakkında daha fazla bilgi için bkz . gRPC istemci fabrikası ile taşıyıcı belirteci.

Son tarih ve iptal yayma

Bir gRPC hizmetinde fabrika tarafından oluşturulan gRPC istemcileri, son tarih ve iptal belirtecini alt çağrılara otomatik olarak yaymak için ile EnableCallContextPropagation() yapılandırılabilir. EnableCallContextPropagation() Uzantı yöntemi Grpc.AspNetCore.Server.ClientFactory NuGet paketinde kullanılabilir.

Çağrı bağlamı yayma, geçerli gRPC isteği bağlamından son tarihi ve iptal belirtecini okuyarak ve bunları gRPC istemcisi tarafından yapılan giden çağrılara otomatik olarak yayarak çalışır. Çağrı bağlamı yayma, karmaşık, iç içe gRPC senaryolarının her zaman son tarihi ve iptali yaymasını sağlamanın mükemmel bir yoludur.

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

varsayılan olarak, EnableCallContextPropagation istemci bir gRPC çağrısı bağlamının dışında kullanılıyorsa bir hata oluşturur. Hata, yaymak için bir çağrı bağlamı olmadığı konusunda sizi uyarmak için tasarlanmıştır. İstemciyi bir çağrı bağlamı dışında kullanmak istiyorsanız, istemci ile SuppressContextNotFoundErrorsyapılandırıldığında hatayı gizleyin:

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

Son tarihler ve RPC iptali hakkında daha fazla bilgi için bkz . Son tarihler ve iptal ile güvenilir gRPC hizmetleri.

Adlandırılmış istemciler

Genellikle bir gRPC istemci türü bir kez kaydedilir ve ardından DI tarafından doğrudan bir türün oluşturucusuna eklenir. Ancak, bir istemci için birden çok yapılandırmaya sahip olmak yararlı olan senaryolar vardır. Örneğin, kimlik doğrulamasıyla ve kimlik doğrulaması olmadan gRPC çağrıları yapan bir istemci.

Aynı türe sahip birden çok istemci, her istemciye bir ad verilerek kaydedilebilir. Adlandırılmış her istemcinin kendi yapılandırması olabilir. Genel AddGrpcClient uzantı yönteminin ad parametresi içeren bir aşırı yüklemesi vardır:

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

Yukarıdaki kod:

GreeterClient Türü iki kez kaydeder ve her birine benzersiz bir ad belirtir.
Adlandırılmış her istemci için farklı ayarlar yapılandırılır. Kayıt, GreeterAuthenticated kanalla yapılan gRPC çağrılarının kimliğinin doğrulanmış olması için kanala kimlik bilgileri ekler.

uygulama kodunda kullanılarak GrpcClientFactoryadlandırılmış bir gRPC istemcisi oluşturulur. İstenen istemcinin türü ve adı genel GrpcClientFactory.CreateClient yöntem kullanılarak belirtilir:

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

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

Ek kaynaklar

Fabrika aşağıdaki avantajları sunar:

Mantıksal gRPC istemci örneklerini yapılandırmak için merkezi bir konum sağlar
Temel alınanın ömrünü yönetir HttpClientMessageHandler
ASP.NET Core gRPC hizmetinde son tarih ve iptalin otomatik olarak yayılması

gRPC istemcilerini kaydetme

Bir gRPC istemcisini kaydetmek için, genel AddGrpcClient uzantı yöntemi içinde Startup.ConfigureServicesgRPC türündeki istemci sınıfı ve hizmet adresini belirterek kullanılabilir:

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'ı yapılandırma

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

Daha fazla bilgi için bkz . IHttpClientFactory kullanarak HTTP isteklerinde bulunma.

Kesme Noktası Oluşturucuları Yapılandırma

gRPC kesicileri yöntemi kullanılarak AddInterceptor istemcilere eklenebilir.

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

Yukarıdaki kod:

Türü kaydeder GreeterClient .
Bu istemci için bir LoggingInterceptor yapılandırılır. LoggingInterceptor bir kez oluşturulur ve örnekler arasında GreeterClient paylaşılır.

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

Bir kesme noktası DI'den kapsamlı veya geçici kapsamlı hizmetler gerektirdiğinde istemci kapsamlı kesme makineleri oluşturmak yararlıdır.

Kanalı Yapılandır

Yöntem kullanılarak ConfigureChannel kanala ek yapılandırma uygulanabilir:

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

ConfigureChannel bir GrpcChannelOptions örnek geçirilir. Daha fazla bilgi için bkz . İstemci seçeneklerini yapılandırma.

Not

Geri çağırma çalıştırilmeden önce ConfigureChannel bazı özellikler ayarlanırGrpcChannelOptions:

HttpHandler , sonucuna ConfigurePrimaryHttpMessageHandlerayarlanır.
LoggerFactory , DI'den ILoggerFactory çözümlenene ayarlanır.

Bu değerler tarafından ConfigureChannelgeçersiz kılınabilir.

Son tarih ve iptal yayma

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

Son tarihler ve RPC iptali hakkında daha fazla bilgi için bkz . Son tarihler ve iptal ile güvenilir gRPC hizmetleri.

Adlandırılmış istemciler

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

Yukarıdaki kod:

GreeterClient Türü iki kez kaydeder ve her birine benzersiz bir ad belirtir.
Adlandırılmış her istemci için farklı ayarlar yapılandırılır. Kayıt, GreeterAuthenticated kanalla yapılan gRPC çağrılarının kimliğinin doğrulanmış olması için kanala kimlik bilgileri ekler.

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

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

Aracılığıyla paylaş

.NET’te gRPC istemci fabrikası tümleştirmesi

gRPC istemcilerini kaydetme

HttpHandler'ı yapılandırma

Kesme Noktası Oluşturucuları Yapılandırma

Kanalı Yapılandır

Çağrı kimlik bilgileri

Son tarih ve iptal yayma

Adlandırılmış istemciler

Ek kaynaklar

gRPC istemcilerini kaydetme

HttpHandler'ı yapılandırma

Kesme Noktası Oluşturucuları Yapılandırma

Kanalı Yapılandır

Son tarih ve iptal yayma

Adlandırılmış istemciler

Ek kaynaklar

Ek kaynaklar