gRPC-Web v aplikacích ASP.NET Core gRPC

Autor: James Newton-King

Zjistěte, jak nakonfigurovat existující službu ASP.NET Core gRPC, která se dá volat z aplikací prohlížeče pomocí protokolu gRPC-Web . gRPC-Web umožňuje prohlížeči JavaScript a Blazor aplikace volat služby gRPC. Službu HTTP/2 gRPC není možné volat z aplikace založené na prohlížeči. Služby gRPC hostované v ASP.NET Core je možné nakonfigurovat tak, aby podporovaly gRPC-Web společně s protokolem HTTP/2 gRPC.

Pokyny k přidání služby gRPC do existující aplikace ASP.NET Core najdete v tématu Přidání služeb gRPC do aplikace ASP.NET Core.

Pokyny k vytvoření projektu gRPC najdete v tématu Vytvoření klienta a serveru .NET Core gRPC v ASP.NET Core.

ASP.NET Core gRPC-Web versus Envoy

Existují dvě možnosti, jak přidat gRPC-Web do aplikace ASP.NET Core:

• Podpora gRPC-Web společně s gRPC HTTP/2 v ASP.NET Core Tato možnost používá middleware poskytovaný balíčkem Grpc.AspNetCore.Web .
• K překladu gRPC-Web na gRPC/2 použijte podporu proxy serveru envoy. Přeložené volání se pak přesměruje do aplikace ASP.NET Core.

Každý přístup má výhody a nevýhody. Pokud prostředí aplikace už jako proxy používá envoy, může být vhodné použít také envoy k poskytování podpory gRPC-Web. Pro základní řešení gRPC-Web, které vyžaduje pouze ASP.NET Core, Grpc.AspNetCore.Web je dobrou volbou.

Konfigurace gRPC-Web v ASP.NET Core

Služby gRPC hostované v ASP.NET Core je možné nakonfigurovat tak, aby podporovaly gRPC-Web společně s protokolem HTTP/2 gRPC. gRPC-Web nevyžaduje žádné změny služeb. Jedinou úpravou je nastavení middlewaru v Program.cs.

Povolení gRPC-Web pomocí služby ASP.NET Core gRPC:

• Přidejte odkaz na Grpc.AspNetCore.Web balíček.
• Nakonfigurujte aplikaci tak, aby používala gRPC-Web přidáním UseGrpcWeb a EnableGrpcWeb do Program.cs:

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

Předchozí kód:

• Přidá middleware gRPC-Web za UseGrpcWebsměrování a před koncové body.
• Určuje, že endpoints.MapGrpcService<GreeterService>() metoda podporuje gRPC-Web s EnableGrpcWeb.

Alternativně je možné nakonfigurovat middleware gRPC-Web tak, aby všechny služby ve výchozím nastavení podporovaly gRPC-Web a EnableGrpcWeb nejsou povinné. Zadejte new GrpcWebOptions { DefaultEnabled = true } , kdy se přidá middleware.

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

Poznámka:

Existuje známý problém, který způsobuje selhání gRPC-Web, když hostuje HTTP.sys v .NET Core 3.x.

Alternativní řešení pro práci s gRPC-Web na HTTP.sys je k dispozici v experimentálním grpc-web a useHttpSys()? (grpc/grpc-dotnet #853).

gRPC-Web a CORS

Zabezpečení prohlížeče zabraňuje tomu, aby webová stránka odesílala požadavky do jiné domény, než je ta, která webovou stránku obsluhuje. Toto omezení platí pro volání gRPC-Web v aplikacích prohlížeče. Například aplikace prohlížeče obsluhovaná službou https://www.contoso.com je blokována volání gRPC-Web services hostované na https://services.contoso.com. Sdílení prostředků mezi zdroji (CORS) se dá použít k uvolnění tohoto omezení.

Pokud chcete aplikaci prohlížeče povolit volání gRPC-Web mezi zdroji, nastavte CORS v ASP.NET Core. Použijte integrovanou podporu CORS a zpřístupňte hlavičky specifické pro gRPC pomocí WithExposedHeaders.

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

Předchozí kód:

• Volání AddCors pro přidání služeb CORS a konfigurace zásad CORS, která zveřejňuje hlavičky specifické pro gRPC.
• Volání UseCors pro přidání middlewaru CORS po konfiguraci směrování a před konfiguraci koncových bodů
• Určuje, že endpoints.MapGrpcService<GreeterService>() metoda podporuje CORS s RequireCors.

gRPC-Web a streamování

Tradiční gRPC přes HTTP/2 podporuje klientské, serverové a obousměrné streamování. gRPC-Web nabízí omezenou podporu streamování:

• Klienti webového prohlížeče gRPC nepodporují volání metod streamování klientů a obousměrného streamování.
• Klienti gRPC-Web .NET nepodporují volání metod streamování klientů a obousměrného streamování přes protokol HTTP/1.1.
• ASP.NET služby Core gRPC hostované ve službě Aplikace Azure Service a IIS nepodporují obousměrné streamování.

Při použití gRPC-Web doporučujeme používat pouze unární metody a metody streamování serveru.

Protokol HTTP

Šablona služby ASP.NET Core gRPC, která je součástí sady .NET SDK, vytvoří aplikaci, která je nakonfigurovaná jenom pro HTTP/2. Toto je dobré výchozí nastavení, když aplikace podporuje pouze tradiční gRPC přes HTTP/2. gRPC-Web ale funguje s HTTP/1.1 i HTTP/2. Některé platformy, jako je UPW nebo Unity, nemůžou používat PROTOKOL HTTP/2. Pokud chcete podporovat všechny klientské aplikace, nakonfigurujte server tak, aby povolil PROTOKOL HTTP/1.1 a HTTP/2.

Aktualizujte výchozí protokol v appsettings.json:

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

Případně nakonfigurujte Kestrel koncové body ve spouštěcím kódu.

Povolení protokolu HTTP/1.1 a HTTP/2 na stejném portu vyžaduje protokol TLS. Další informace najdete v tématu ASP.NET vyjednávání protokolu gRPC core.

Volání gRPC-Web z prohlížeče

Aplikace prohlížeče můžou používat gRPC-Web k volání služeb gRPC. Při volání služeb gRPC pomocí gRPC-Web z prohlížeče existují některé požadavky a omezení:

• Server musí obsahovat konfiguraci pro podporu gRPC-Web.
• Streamování klientů a obousměrná volání streamování se nepodporují. Podporuje se streamování serveru.
• Volání služeb gRPC v jiné doméně vyžaduje konfiguraci CORS na serveru.

JavaScript gRPC-Web client

Existuje javascriptový klient gRPC-Web. Pokyny k použití gRPC-Web z JavaScriptu najdete v tématu Psaní kódu klienta JavaScriptu pomocí gRPC-Web.

Konfigurace gRPC-Web pomocí klienta .NET gRPC

Klienta .NET gRPC lze nakonfigurovat tak, aby bylo možné provádět volání gRPC-Web. To je užitečné pro Blazor WebAssembly aplikace, které jsou hostované v prohlížeči a mají stejná omezení HTTP pro javascriptový kód. Volání gRPC-Web pomocí klienta .NET je stejné jako HTTP/2 gRPC. Jedinou úpravou je vytvoření kanálu.

Použití gRPC-Web:

• Přidejte odkaz na Grpc.Net.Client.Web balíček.
• Ujistěte se, že odkaz na Grpc.Net.Client balíček je verze 2.29.0 nebo novější.
• Nakonfigurujte kanál tak, aby používal:GrpcWebHandler

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

Předchozí kód:

• Nakonfiguruje kanál tak, aby používal gRPC-Web.
• Vytvoří klienta a zavolá pomocí kanálu.

GrpcWebHandler má následující možnosti konfigurace:

• InnerHandler: Podklad HttpMessageHandler , který provádí požadavek gRPC HTTP, HttpClientHandlernapříklad .
• GrpcWebMode: Typ výčtu, který určuje, zda je application/grpc-web požadavek Content-Type gRPC HTTP nebo application/grpc-web-text.
  • GrpcWebMode.GrpcWeb nakonfiguruje odesílání obsahu bez kódování. Výchozí hodnota.
  • GrpcWebMode.GrpcWebText konfiguruje obsah kódovaný podle base64. Vyžaduje se pro volání streamování serveru v prohlížečích.
• HttpVersion: Protokol Version HTTP použitý k nastavení HttpRequestMessage.Version základního požadavku gRPC HTTP. gRPC-Web nevyžaduje konkrétní verzi a nepřepíše výchozí nastavení, pokud není zadáno.

Důležité

Vygenerované klienty gRPC mají synchronní a asynchronní metody pro volání unárních metod. Je například SayHello synchronní a SayHelloAsync je asynchronní. Asynchronní metody jsou vždy vyžadovány v Blazor WebAssembly. Volání synchronní metody v Blazor WebAssembly aplikaci způsobí, že aplikace přestane reagovat.

Použití klientské továrny gRPC s gRPC-Web

Vytvořte klienta .NET kompatibilního s gRPC-Web pomocí klientské továrny gRPC:

• Přidejte odkazy na balíčky do souboru projektu pro následující balíčky:
  • Grpc.Net.Client.Web
  • Grpc.Net.ClientFactory
• Zaregistrujte klienta gRPC pomocí injektáže závislostí (DI) pomocí obecné AddGrpcClient metody rozšíření. Blazor WebAssembly V aplikaci jsou služby zaregistrované s di di in Program.cs.
• Nakonfigurujte GrpcWebHandler pomocí ConfigurePrimaryHttpMessageHandler metody rozšíření.

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

Další informace najdete v tématu integrace klientské továrny gRPC v .NET.

Další materiály

• gRPC pro projekt GitHubu pro webové klienty
• Povolení žádostí mezi zdroji (CORS) v ASP.NET Core
• Transkódování JSON gRPC v aplikacích ASP.NET Core gRPC