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
aEnableGrpcWeb
doProgram.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
UseGrpcWeb
směrování a před koncové body. - Určuje, že
endpoints.MapGrpcService<GreeterService>()
metoda podporuje gRPC-Web sEnableGrpcWeb
.
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 při hostované http.sys v .NET Core 3.x.
Alternativní řešení pro práci gRPC-Web na HTTP.sys je k dispozici v Grpc-web experimentální a UseHttpSys()? (grpc/grpc-dotnet #853).
gRPC-Web a CORS
Zabezpečení prohlížeče brání webové stránce v provádění požadavků na jinou doménu, než je ta, která obsluhuje webovou stránku. 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 sRequireCors
.
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,HttpClientHandler
například .GrpcWebMode
: Typ výčtu, který určuje, zda jeapplication/grpc-web
požadavekContent-Type
gRPC HTTP neboapplication/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
: ProtokolVersion
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:
- 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 inProgram.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
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í middelwaru 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
aEnableGrpcWeb
doProgram.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
UseGrpcWeb
směrování a před koncové body. - Určuje, že
endpoints.MapGrpcService<GreeterService>()
metoda podporuje gRPC-Web sEnableGrpcWeb
.
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 při hostované http.sys v .NET Core 3.x.
Alternativní řešení pro práci gRPC-Web na HTTP.sys je k dispozici v Grpc-web experimentální a UseHttpSys()? (grpc/grpc-dotnet #853).
gRPC-Web a CORS
Zabezpečení prohlížeče brání webové stránce v provádění požadavků na jinou doménu, než je ta, která obsluhuje webovou stránku. 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 sRequireCors
.
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,HttpClientHandler
například .GrpcWebMode
: Typ výčtu, který určuje, zda jeapplication/grpc-web
požadavekContent-Type
gRPC HTTP neboapplication/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
: ProtokolVersion
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:
- 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 inProgram.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
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 konfigurace spuštění.
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
aEnableGrpcWeb
doStartup.cs
:
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();
});
}
Předchozí kód:
- Přidá middleware gRPC-Web za
UseGrpcWeb
směrování a před koncové body. - Určuje, že
endpoints.MapGrpcService<GreeterService>()
metoda podporuje gRPC-Web sEnableGrpcWeb
.
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.
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>();
});
}
}
Poznámka:
Existuje známý problém, který způsobuje selhání gRPC-Web při hostované http.sys v .NET Core 3.x.
Alternativní řešení pro práci gRPC-Web na HTTP.sys je k dispozici v Grpc-web experimentální a UseHttpSys()? (grpc/grpc-dotnet #853).
gRPC-Web a CORS
Zabezpečení prohlížeče brání webové stránce v provádění požadavků na jinou doménu, než je ta, která obsluhuje webovou stránku. 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.
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");
});
}
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 sRequireCors
.
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:5001", new GrpcChannelOptions
{
HttpHandler = new GrpcWebHandler(new HttpClientHandler())
});
var client = new Greeter.GreeterClient(channel);
var response = await client.SayHelloAsync(new HelloRequest { Name = ".NET" });
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,HttpClientHandler
například .GrpcWebMode
: Typ výčtu, který určuje, zda jeapplication/grpc-web
požadavekContent-Type
gRPC HTTP neboapplication/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
: ProtokolVersion
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:
- 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 inProgram.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
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro