ASP.NET Core gRPC uygulamalarında gRPC-Web

Yayınlayan James Newton-King

gRPC-Web protokolunu kullanarak mevcut bir ASP.NET Core gRPC hizmetini tarayıcı uygulamalarından çağrılabilecek şekilde yapılandırmayı öğrenin. gRPC-Web, tarayıcı JavaScript ve Blazor uygulamalarının gRPC hizmetlerini çağırmasına olanak tanır. Tarayıcı tabanlı bir uygulamadan HTTP/2 gRPC hizmetini çağırmak mümkün değildir. ASP.NET Core'da barındırılan gRPC hizmetleri, HTTP/2 gRPC ile birlikte gRPC-Web'i destekleyecek şekilde yapılandırılabilir.

Mevcut bir ASP.NET Core uygulamasına gRPC hizmeti ekleme yönergeleri için bkz . ASP.NET Core uygulamasına gRPC hizmetleri ekleme.

gRPC projesi oluşturma yönergeleri için bkz . ASP.NET Core'da .NET Core gRPC istemcisi ve sunucusu oluşturma.

ASP.NET Core gRPC-Web ve Envoy karşılaştırması

bir ASP.NET Core uygulamasına gRPC-Web eklemeye yönelik iki seçenek vardır:

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

Her yaklaşımın avantajları ve dezavantajları vardır. Bir uygulamanın ortamı zaten Proxy olarak Envoy kullanıyorsa, gRPC-Web desteği sağlamak için Envoy'un kullanılması da mantıklı olabilir. gRPC-Web için yalnızca ASP.NET Core Grpc.AspNetCore.Web gerektiren temel bir çözüm için iyi bir seçimdir.

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

ASP.NET Core'da barındırılan gRPC hizmetleri, HTTP/2 gRPC ile birlikte gRPC-Web'i destekleyecek şekilde yapılandırılabilir. gRPC-Web, hizmetlerde herhangi bir değişiklik gerektirmez. Tek değişiklik, ara yazılımı içinde ayarlamaktır Program.cs.

ASP.NET Core gRPC hizmetiyle gRPC-Web'i etkinleştirmek için:

• Pakete Grpc.AspNetCore.Web bir başvuru ekleyin.
• ve EnableGrpcWeb ekleyerek UseGrpcWeb uygulamayı gRPC-Web kullanacak şekilde Program.csyapılandırın:

using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGrpc();

var app = builder.Build();

app.UseGrpcWeb();

app.MapGrpcService<GreeterService>().EnableGrpcWeb();
app.MapGet("/", () => "This gRPC service is gRPC-Web enabled and is callable from browser apps using the gRPC-Web protocol");

app.Run();

Yukarıdaki kod:

• gRPC-Web ara yazılımını, UseGrpcWebyönlendirmeden sonra ve uç noktalardan önce ekler.
• yönteminin endpoints.MapGrpcService<GreeterService>() ile gRPC-Web'i desteklediğini EnableGrpcWebbelirtir.

Alternatif olarak, gRPC-Web ara yazılımı, tüm hizmetlerin varsayılan olarak gRPC-Web'i desteklemesi ve EnableGrpcWeb gerekli olmadığı şekilde yapılandırılabilir. Ara yazılım eklendiğinde belirtin new GrpcWebOptions { DefaultEnabled = true } .

using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGrpc();

var app = builder.Build();

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

app.MapGrpcService<GreeterService>().EnableGrpcWeb();
app.MapGet("/", () => "All gRPC service are supported by default in this example, and are callable from browser apps using the gRPC-Web protocol");

app.Run();

Not

.NET Core 3.x'te HTTP.sys tarafından barındırıldığında gRPC-Web'in başarısız olmasına neden olan bilinen bir sorun vardır.

gRPC-Web'in HTTP.sys üzerinde çalışmasını sağlamak için geçici bir çözüm Grpc-web experimental ve UseHttpSys() ile kullanılabilir. (grpc/grpc-dotnet #853).

gRPC-Web ve CORS

Tarayıcı güvenliği, bir web sayfasının web sayfasına hizmet verenden farklı bir etki alanına istekte bulunmasını engeller. Bu kısıtlama, tarayıcı uygulamalarıyla gRPC-Web çağrıları yapmak için geçerlidir. Örneğin, tarafından https://www.contoso.com sunulan bir tarayıcı uygulamasının üzerinde https://services.contoso.combarındırılan gRPC-Web hizmetlerini çağırması engellenir. Bu kısıtlamayı gevşetmek için Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) kullanılabilir.

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

using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGrpc();

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

var app = builder.Build();

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

app.MapGrpcService<GreeterService>().EnableGrpcWeb()
                                    .RequireCors("AllowAll");

app.MapGet("/", () => "This gRPC service is gRPC-Web enabled, CORS enabled, and is callable from browser apps using the gRPC-Web protocol");

app.Run();

Yukarıdaki kod:

• CORS hizmetleri eklemek ve gRPC'ye özgü üst bilgileri kullanıma sunan bir CORS ilkesi yapılandırmak için çağrılar AddCors .
• Yönlendirme yapılandırmasından sonra ve uç nokta yapılandırmasından önce CORS ara yazılımını eklemek için çağrılar UseCors .
• yönteminin ile RequireCorsCORS'yi endpoints.MapGrpcService<GreeterService>() desteklediğini belirtir.

gRPC-Web ve akış

HTTP/2 üzerinden geleneksel gRPC istemci, sunucu ve çift yönlü akışı 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öntemlerini çağırmayı desteklemez.
• gRPC-Web .NET istemcileri HTTP/1.1 üzerinden istemci akışı ve çift yönlü akış yöntemlerini çağırmayı desteklemez.
• Azure Uygulaması Hizmetinde barındırılan ASP.NET Core gRPC hizmetleri ve IIS çift yönlü akışı desteklemez.

gRPC-Web kullanırken yalnızca birli yöntemlerin ve sunucu akış yöntemlerinin kullanılmasını öneririz.

HTTP protokolü

.NET SDK'sında bulunan ASP.NET Core gRPC hizmet şablonu, yalnızca HTTP/2 için yapılandırılmış bir uygulama oluşturur. Bir uygulama yalnızca HTTP/2 üzerinden geleneksel gRPC'yi desteklediğinde bu iyi bir varsayılan değerdir. Ancak gRPC-Web hem HTTP/1.1 hem de HTTP/2 ile çalışır. UWP veya Unity gibi bazı platformlar HTTP/2 kullanamaz. Tüm istemci uygulamalarını desteklemek için sunucuyu HTTP/1.1 ve HTTP/2'yi etkinleştirecek şekilde yapılandırın.

içindeki varsayılan protokolü güncelleştirin appsettings.json:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1AndHttp2"
    }
  }
}

Alternatif olarak başlangıç kodunda uç noktaları yapılandırınKestrel.

Aynı bağlantı noktasında HTTP/1.1 ve HTTP/2'nin etkinleştirilmesi, protokol anlaşması için TLS gerektirir. Daha fazla bilgi için bkz . ASP.NET Core gRPC protokolü anlaşması.

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

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

• Sunucunun gRPC-Web'i desteklemek için yapılandırma içermesi gerekir.
• İstemci akışı ve çift yönlü akış çağrıları desteklenmez. Sunucu akışı desteklenir.
• Farklı bir etki alanında gRPC hizmetlerini çağırmak için sunucuda CORS yapılandırması gerekir.

JavaScript gRPC-Web istemcisi

JavaScript gRPC-Web istemcisi var. JavaScript'ten gRPC-Web kullanma yönergeleri için bkz . gRPC-Web ile JavaScript istemci kodu yazma.

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

.NET gRPC istemcisi gRPC-Web çağrıları yapacak şekilde yapılandırılabilir. Bu, tarayıcıda barındırılan ve JavaScript koduyla aynı HTTP sınırlamalarına sahip uygulamalar için Blazor WebAssembly kullanışlıdır. .NET istemcisiyle gRPC-Web çağrısı http/2 gRPC ile aynıdır. Tek değişiklik kanalın nasıl oluşturulduğudur.

gRPC-Web kullanmak için:

• Pakete Grpc.Net.Client.Web bir başvuru ekleyin.
• Paket başvurusunun Grpc.Net.Client sürüm 2.29.0 veya üzeri olduğundan emin olun.
• kanalını kullanmak GrpcWebHandleriçin yapılandırın:

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

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

Yukarıdaki kod:

• Bir kanalı gRPC-Web kullanacak şekilde yapılandırılır.
• bir istemci oluşturur ve kanalı kullanarak bir çağrı yapar.

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

• InnerHandler: gRPC HTTP isteğini yapan temel alınan HttpMessageHandler , örneğin, HttpClientHandler.
• GrpcWebMode: gRPC HTTP isteğinin Content-Type application/grpc-web veya application/grpc-web-textolup olmadığını belirten bir numaralandırma türü.
  • GrpcWebMode.GrpcWeb kodlama olmadan içerik göndermeyi yapılandırıyor. Varsayılan değer.
  • GrpcWebMode.GrpcWebText base64 ile kodlanmış içeriği yapılandırıyor. Tarayıcılardaki sunucu akış çağrıları için gereklidir.
• HttpVersion: Temel alınan gRPC HTTP isteğinde ayarlamak HttpRequestMessage.Version için kullanılan HTTP protokolüVersion. gRPC-Web belirli bir sürüm gerektirmez ve belirtilmedikçe varsayılanı geçersiz kılmaz.

Önemli

Oluşturulan gRPC istemcileri, tekli yöntemleri çağırmak için zaman uyumlu ve zaman uyumsuz yöntemlere sahiptir. Örneğin, SayHello zaman uyumlu ve SayHelloAsync zaman uyumsuzdur. zaman uyumsuz yöntemler her zaman içinde Blazor WebAssemblygereklidir. Uygulamada zaman uyumlu bir Blazor WebAssembly yöntemi çağırmak, uygulamanın yanıt vermemeye başlamasına neden olur.

gRPC-Web ile gRPC istemci fabrikasını kullanma

gRPC istemci fabrikasını kullanarak gRPC-Web ile uyumlu bir .NET istemcisi oluşturun:

• Aşağıdaki paketler için proje dosyasına paket başvuruları ekleyin:
  • Grpc.Net.Client.Web
  • Grpc.Net.ClientFactory
• Genel AddGrpcClient uzantı yöntemini kullanarak bağımlılık ekleme (DI) ile bir gRPC istemcisi kaydedin. Bir Blazor WebAssembly uygulamada, hizmetler içinde DI'ye Program.cskaydedilir.
• uzantı yöntemini kullanarak ConfigurePrimaryHttpMessageHandler yapılandırınGrpcWebHandler.

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

• Web İstemcileri için gRPC GitHub projesi
• ASP.NET Core'da Çıkış Noktaları Arası İstekleri (CORS) Etkinleştirme
• ASP.NET Core gRPC uygulamalarında gRPC JSON kodlaması dönüştürme