Tarayıcı uygulamalarında gRPC kullanma

, James bAyKiNg

grpc-Web protokolünü kullanarak var olan bir ASP.NET Core grpc hizmetini tarayıcı uygulamalarından çağrılabilir olacak şekilde yapılandırmayı öğrenin. gRPC-Web tarayıcı JavaScript ve Blazor uygulamalarının GRPC hizmetlerini çağırmasını sağlar. Tarayıcı tabanlı bir uygulamadan HTTP/2 gRPC hizmetini çağırmak mümkün değildir. ASP.NET Core 'de barındırılan grpc hizmetleri, grpc-Web ' i HTTP/2 grpc ile birlikte destekleyecek şekilde yapılandırılabilir.

mevcut bir ASP.NET Core uygulamasına grpc hizmeti ekleme hakkında yönergeler için bkz. bir ASP.NET Core uygulamasına grpc hizmetleri ekleme.

GRPC projesi oluşturma hakkında yönergeler için bkz ASP.NET Core .NET Core gRPC istemcisi ve sunucusu oluşturma ..

grpc-Web 'de ASP.NET Core ve envoy 'ye karşı

grpc-Web ' i bir ASP.NET Core uygulamasına eklemenin iki seçeneği vardır:

• ASP.NET Core 'de GRPC HTTP/2 ile birlikte gRPC-Web desteği. Bu seçenek, paket tarafından sağlanmış olan ara yazılımı kullanır Grpc.AspNetCore.Web .
• GRPC-Web ' i GRPC HTTP/2 ' ye çevirmek için Envoy proxy 'nin GRPC-Web desteğini kullanın. çevrilen çağrı daha sonra ASP.NET Core uygulamasına iletilir.

Her yaklaşımın olumlu ve olumsuz yönleri vardır. Bir uygulamanın ortamı zaten bir ara sunucu olarak kullanılıyorsa, gRPC-Web desteği sağlamak için de Envoy kullanılması mantıklı olabilir. yalnızca ASP.NET Core gerektiren grpc-Web için temel bir çözüm için Grpc.AspNetCore.Web iyi bir seçimdir.

ASP.NET Core 'de gRPC-Web yapılandırma

ASP.NET Core 'de barındırılan grpc hizmetleri, grpc-Web ' i HTTP/2 grpc ile birlikte destekleyecek şekilde yapılandırılabilir. gRPC-Web, hizmetlerde herhangi bir değişiklik yapılmasını gerektirmez. Tek değişiklik başlangıç yapılandırması ' dır.

grpc-Web ' i bir ASP.NET Core grpc hizmeti ile etkinleştirmek için:

• GRPC. AspNetCore. Web paketine bir başvuru ekleyin.
• Uygulamayı, UseGrpcWeb EnableGrpcWeb Başlangıç. cs ekleyerek ve aracılığıyla GRPC-Web kullanacak şekilde yapılandırın:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
}

public void Configure(IApplicationBuilder app)
{
    app.UseRouting();

    app.UseGrpcWeb(); // Must be added between UseRouting and UseEndpoints

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<GreeterService>().EnableGrpcWeb();
    });
}

Yukarıdaki kod:

• UseGrpcWebYönlendirme sonrasında ve bitiş noktalarından önce gRPC-Web ara yazılımını ekler.
• Yöntemi, endpoints.MapGrpcService<GreeterService>() Ile gRPC-Web ' i destekler EnableGrpcWeb .

Alternatif olarak, gRPC-Web ara yazılımı, tüm hizmetlerin varsayılan olarak gRPC-Web 'i desteklemesi ve gerekli olmaması için yapılandırılabilir EnableGrpcWeb . new GrpcWebOptions { DefaultEnabled = true }Ara yazılımın ne zaman ekleneceğini belirtin.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseGrpcWeb(new GrpcWebOptions { DefaultEnabled = true });

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

gRPC-Web ve CORS

Tarayıcı güvenliği, bir Web sayfasının Web sayfasını sunduğundan farklı bir etki alanına istek yapmasını engeller. Bu kısıtlama, tarayıcı uygulamalarıyla gRPC Web çağrıları yapmak için geçerlidir. Örneğin, tarafından sunulan bir tarayıcı uygulamasının https://www.contoso.com üzerinde barındırılan gRPC-Web hizmetlerinden çağrılması engellenir https://services.contoso.com . Bu kısıtlamayı rahatmak için çapraz kaynak kaynak paylaşımı (CORS) kullanılabilir.

Bir tarayıcı uygulamasının, çıkış noktaları arası gRPC-Web çağrıları yapmasına izin vermek için ASP.NET Core 'de CORS'yi ayarlayın. Yerleşik CORS desteğini kullanın ve gRPC 'ye özgü üst bilgileri ile kullanıma sunun WithExposedHeaders .

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();

    services.AddCors(o => o.AddPolicy("AllowAll", builder =>
    {
        builder.AllowAnyOrigin()
               .AllowAnyMethod()
               .AllowAnyHeader()
               .WithExposedHeaders("Grpc-Status", "Grpc-Message", "Grpc-Encoding", "Grpc-Accept-Encoding");
    }));
}

public void Configure(IApplicationBuilder app)
{
    app.UseRouting();

    app.UseGrpcWeb();
    app.UseCors();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<GreeterService>().EnableGrpcWeb()
                                                  .RequireCors("AllowAll");
    });
}

Yukarıdaki kod:

• AddCorsCORS Hizmetleri ekleme ve gRPC 'ye özgü üst bilgileri kullanıma sunan BIR CORS ilkesini yapılandırma çağrıları.
• UseCorsYönlendirmeden ve bitiş noktalarından önce CORS ara yazılımını ekleme çağrıları.
• endpoints.MapGrpcService<GreeterService>()CORS 'yi ile desteklerken yöntemi belirtir RequiresCors .

gRPC-Web ve akış

HTTP/2 üzerinde geleneksel gRPC, akışı tüm yönlere göre destekler. gRPC-Web, akış için sınırlı destek sunar:

• gRPC-Web tarayıcısı istemcileri, istemci akışı ve çift yönlü akış yöntemlerinin çağrılmasını desteklemez.
• Azure App Service ve ııs 'de barındırılan ASP.NET Core grpc hizmetleri çift yönlü akışı desteklemez.

GRPC-Web kullanırken, yalnızca birli yöntemlerin ve sunucu akış yöntemlerinin kullanılması önerilir.

Tarayıcıdan gRPC-Web 'i çağırma

Tarayıcı uygulamaları GRPC hizmetlerini çağırmak için gRPC-Web kullanabilir. GRPC hizmetlerini tarayıcıda GRPC-Web ile çağırırken bazı gereksinimler ve sınırlamalar vardır:

• Sunucu, gRPC-Web ' i destekleyecek şekilde yapılandırılmış olmalıdır.
• İstemci akışı ve çift yönlü akış çağrıları desteklenmez. Sunucu akışı destekleniyor.
• Farklı bir etki alanında gRPC hizmetlerinin çağrılması için CORS 'nin sunucuda yapılandırılması gerekir.

JavaScript gRPC-Web istemcisi

Bir JavaScript gRPC-Web istemcisi vardır. JavaScript 'ten gRPC-Web kullanma hakkında yönergeler için bkz. gRPC-web Ile JavaScript istemci kodu yazma.

.NET gRPC istemcisiyle gRPC-Web yapılandırma

.NET gRPC istemcisi, gRPC-Web çağrıları yapmak için yapılandırılabilir. Bu, Blazor WebAssembly tarayıcıda barındırılan ve JavaScript koduyla aynı http kısıtlamalarına sahip olan uygulamalar için yararlıdır. Bir .NET istemcisiyle gRPC-Web ' i çağırmak http/2 gRPC ile aynıdır. Tek değişiklik, kanalın oluşturulma şekli olur.

GRPC-Web kullanmak için:

• GRPC .net. Client. Web paketine başvuru ekleyin.
• GRPC .net. Client paketine yönelik başvurunun 2.29.0 veya daha büyük olduğundan emin olun.
• Kanalı şunu kullanacak şekilde yapılandırın GrpcWebHandler :

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions
    {
        HttpHandler = new GrpcWebHandler(new HttpClientHandler())
    });

var client = new Greeter.GreeterClient(channel);
var response = await client.SayHelloAsync(new HelloRequest { Name = ".NET" });

Yukarıdaki kod:

• GRPC-Web kullanmak için bir kanal yapılandırır.
• Bir istemci oluşturur ve kanalı kullanarak bir çağrı yapar.

GrpcWebHandler Aşağıdaki yapılandırma seçeneklerine sahiptir:

• InnerHandler:, HttpMessageHandler Örneğin, GRPC http isteğini oluşturan temel HttpClientHandler .
• Grpcwebmode: GRPC http isteğinin veya olup olmadığını belirten bir numaralandırma türü Content-Type application/grpc-web application/grpc-web-text .
  • GrpcWebMode.GrpcWeb kodlamadan gönderilecek içeriği yapılandırır. Varsayılan değer.
  • GrpcWebMode.GrpcWebText içeriği Base64 kodlamalı olarak yapılandırır. Tarayıcılarda sunucu akış çağrıları için gereklidir.
• HttpVersion: Version TEMELDEKI GRPC http isteğindeki HttpRequestMessage. Version öğesini ayarlamak için kullanılan http protokolü. gRPC-Web belirli bir sürüm gerektirmez ve belirtilmediği takdirde varsayılanı geçersiz kılmaz.

GRPC istemci fabrikası ile gRPC-Web kullanma

GRPC istemci fabrikasıkullanılarak bir GRPC-Web uyumlu .NET istemcisi oluşturulabilir.

GRPC-Web ' i istemci fabrikası ile kullanmak için:

• Aşağıdaki paketler için proje dosyasına paket başvuruları ekleyin:
  • GRPC .net. Client. Web
  • GRPC .net. ClientFactory
• Genel genişletme yöntemini kullanarak bir gRPC istemcisini bağımlılık ekleme (dı) ile kaydedin AddGrpcClient . Bir Blazor WebAssembly uygulamada, HIZMETLER dı ile kaydedilir Program.cs .
• GrpcWebHandler ConfigurePrimaryHttpMessageHandler Uzantı yöntemini kullanarak yapılandırın.

builder.Services
    .AddGrpcClient<Greet.GreeterClient>(options =>
    {
        options.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(
        () => new GrpcWebHandler(new HttpClientHandler()));

Daha fazla bilgi için bkz. .NET'te gRPC istemci fabrikası tümleştirmesi.

Ek kaynaklar

• project GitHub Web istemcileri için grpc
• Çıkış Noktası Arası İstekleri (CORS) ASP.NET Core
• gRPC'den JSON Web API'leri oluşturma