gRPC-Web i ASP.NET Core gRPC-applikationer

Av James Newton-King

Lär dig hur du konfigurerar en befintlig ASP.NET Core gRPC-tjänst så att den kan anropas från webbläsarappar med hjälp av gRPC-Web-protokollet . gRPC-Web tillåter javaScript i webbläsaren och Blazor appar att anropa gRPC-tjänster. Det går inte att anropa en HTTP/2 gRPC-tjänst från en webbläsarbaserad app. gRPC-tjänster som finns i ASP.NET Core kan konfigureras för att stödja gRPC-Web tillsammans med HTTP/2 gRPC.

Anvisningar om hur du lägger till en gRPC-tjänst i en befintlig ASP.NET Core-app finns i Lägga till gRPC-tjänster i en ASP.NET Core-app.

Anvisningar om hur du skapar ett gRPC-projekt finns i Skapa en .NET gRPC-klient och -server i ASP.NET Core.

ASP.NET Core gRPC-Web kontra Envoy

Det finns två alternativ för hur du lägger till gRPC-Web i en ASP.NET Core-app:

• Stöd för gRPC-Web tillsammans med gRPC HTTP/2 i ASP.NET Core. Det här alternativet använder mellanprogram som tillhandahålls av Grpc.AspNetCore.Web paketet.
• Använd envoyproxyns gRPC-Web-stöd för att översätta gRPC-Web till gRPC HTTP/2. Det översatta anropet vidarebefordras sedan till ASP.NET Core-appen.

Det finns för- och nackdelar med varje metod. Om en apps miljö redan använder Envoy som proxy kan det vara klokt att även använda Envoy för att tillhandahålla stöd för gRPC-Web. För en grundläggande lösning för gRPC-Web som bara kräver ASP.NET Core är Grpc.AspNetCore.Web ett bra val.

Konfigurera gRPC-Web i ASP.NET Core

gRPC-tjänster som finns i ASP.NET Core kan konfigureras för att stödja gRPC-Web tillsammans med HTTP/2 gRPC. gRPC-Web kräver inga ändringar i tjänsterna. Den enda ändringen är att ange mellanprogrammet i Program.cs.

Så här aktiverar du gRPC-Web med en ASP.NET Core gRPC-tjänst:

• Lägg till en referens till Grpc.AspNetCore.Web paketet.
• Konfigurera appen så att den använder gRPC-Web genom att lägga till UseGrpcWeb och EnableGrpcWeb till 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();

Föregående kod:

• Lägger till mellanprogrammet gRPC-Web UseGrpcWeb, efter routning och före slutpunkter.
• Anger att endpoints.MapGrpcService<GreeterService>() metoden stöder gRPC-Web med EnableGrpcWeb.

Alternativt kan mellanprogrammet gRPC-Web konfigureras så att alla tjänster stöder gRPC-Web som standard och EnableGrpcWeb inte krävs. Ange new GrpcWebOptions { DefaultEnabled = true } när mellanprogrammet läggs till.

using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGrpc();

var app = builder.Build();

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

app.MapGrpcService<GreeterService>();
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();

Note

Det finns ett känt problem som gör att gRPC-Web misslyckas när den hanteras av HTTP.sys i .NET Core 3.x.

En lösning för att få gRPC-Web att arbeta med HTTP.sys finns i Grpc-web experimental och UseHttpSys()? (grpc/grpc-dotnet #853).

gRPC-Web och CORS

Webbläsarsäkerhet hindrar en webbsida från att göra begäranden till en annan domän än den som hanterade webbsidan. Den här begränsningen gäller för att göra gRPC-web-anrop med webbläsarappar. En webbläsarapp som hanteras av https://www.contoso.com blockeras till exempel från att anropa gRPC-Web-tjänster som finns på https://services.contoso.com. Resursdelning för korsande ursprung (CORS) kan användas för att lätta på den här begränsningen.

Om du vill tillåta att en webbläsarapp gör GRPC-Web-anrop mellan ursprung konfigurerar du CORS i ASP.NET Core. Använd det inbyggda CORS-stödet och exponera gRPC-specifika rubriker med 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", 
                "Grpc-Status-Details-Bin");
}));

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

Föregående kod:

• Anropar AddCors för att lägga till CORS-tjänster och konfigurera en CORS-princip som exponerar gRPC-specifika huvuden.
• Anrop UseCors för att lägga till CORS-mellanprogrammet efter routningskonfigurationen och före konfigurationen av slutpunkter.
• Anger att endpoints.MapGrpcService<GreeterService>() metoden stöder CORS med RequireCors.

gRPC-Web och direktuppspelning

Traditionell gRPC via HTTP/2 stöder klient-, server- och dubbelriktad direktuppspelning. gRPC-Web erbjuder begränsat stöd för direktuppspelning:

• gRPC-webbläsarklienter stöder inte anropande klientströmning och dubbelriktade strömningsmetoder.
• gRPC-Web .NET-klienter stöder inte klientströmning och dubbelriktad strömning via HTTP/1.1.
• ASP.NET Core gRPC-tjänster som finns i Azure App Service och IIS stöder inte dubbelriktad direktuppspelning.

När du använder gRPC-Web rekommenderar vi endast användning av unary-metoder och metoder för serverströmning.

HTTP-protokoll

ASP.NET Core gRPC-tjänstmallen, som ingår i .NET SDK, skapar en app som endast har konfigurerats för HTTP/2. Detta är en bra standard när en app endast stöder traditionell gRPC via HTTP/2. gRPC-Web fungerar dock med både HTTP/1.1 och HTTP/2. Vissa plattformar, till exempel UWP eller Unity, kan inte använda HTTP/2. Konfigurera servern för att aktivera HTTP/1.1 och HTTP/2 för att stödja alla klientappar.

Uppdatera standardprotokollet i appsettings.json:

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

Du kan också konfigurera Kestrel slutpunkter i startkoden.

För att aktivera HTTP/1.1 och HTTP/2 på samma port krävs TLS för protokollförhandling. Mer information finns i ASP.NET Core gRPC-protokollförhandling.

Anropa gRPC-Web från webbläsaren

Webbläsarappar kan använda gRPC-Web för att anropa gRPC-tjänster. Det finns vissa krav och begränsningar när du anropar gRPC-tjänster med gRPC-Web från webbläsaren:

• Servern måste innehålla konfiguration för att stödja gRPC-Web.
• Klientströmning och dubbelriktade strömningsanrop stöds inte. Serverströmning stöds.
• Att anropa gRPC-tjänster på en annan domän kräver CORS-konfiguration på servern.

JavaScript gRPC-Web-klient

Det finns en JavaScript gRPC-Web-klient. Anvisningar om hur du använder gRPC-Web från JavaScript finns i skriva JavaScript-klientkod med gRPC-Web.

Konfigurera gRPC-Web med .NET gRPC-klienten

.NET gRPC-klienten kan konfigureras för att göra gRPC-Web-anrop. Detta är användbart för Blazor WebAssembly appar som finns i webbläsaren och har samma HTTP-begränsningar för JavaScript-kod. Att anropa gRPC-Web med en .NET-klient är detsamma som HTTP/2 gRPC. Den enda ändringen är hur kanalen skapas.

Så här använder du gRPC-Web:

• Lägg till en referens till Grpc.Net.Client.Web paketet.
• Kontrollera att referensen till Grpc.Net.Client paketet är version 2.29.0 eller senare.
• Konfigurera kanalen så att den GrpcWebHandleranvänder :

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

Föregående kod:

• Konfigurerar en kanal för att använda gRPC-Web.
• Skapar en klient och anropar med hjälp av kanalen.

GrpcWebHandler har följande konfigurationsalternativ:

• InnerHandler: Den underliggande HttpMessageHandler som gör gRPC HTTP-begäran, till exempel HttpClientHandler.
• GrpcWebMode: En uppräkningstyp som anger om gRPC HTTP-begäran Content-Type är application/grpc-web eller application/grpc-web-text.
  • GrpcWebMode.GrpcWeb konfigurerar sändning av innehåll utan kodning. Standardvärde.
  • GrpcWebMode.GrpcWebText konfigurerar base64-kodat innehåll. Krävs för serverströmningsanrop i webbläsare.

GrpcChannelOptions.HttpVersion och GrpcChannelOptions.HttpVersionPolicy kan användas för att konfigurera HTTP-protokollversionen.

Important

Genererade gRPC-klienter har synkrona och asynkrona metoder för att anropa unary-metoder. Till exempel SayHello är synkron och SayHelloAsync asynkron. Asynkrona metoder krävs alltid i Blazor WebAssembly. Att anropa en synkron metod i en Blazor WebAssembly-app gör att appen blir svarslös.

Använd gRPC-klientfabrik med gRPC-Web

Skapa en .NET-klient som är kompatibel med gRPC-Web med hjälp av gRPC-klientfabriken:

• Lägg till paketreferenser till projektfilen för följande paket:
  • Grpc.Net.Client.Web
  • Grpc.Net.ClientFactory
• Registrera en gRPC-klient med beroendeinmatning (DI) med hjälp av den generiska AddGrpcClient tilläggsmetoden. I en Blazor WebAssembly app registreras tjänster med DI i Program.cs.
• Konfigurera GrpcWebHandler med hjälp av ConfigurePrimaryHttpMessageHandler tilläggsmetoden.

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

Mer information finns i gRPC-klientfabriksintegrering i .NET.

Ytterligare resurser

• gRPC för GitHub-projekt för webbklienter
• Aktivera CORS (Cross-Origin Requests) i ASP.NET Core
• gRPC JSON-omkodning i ASP.NET Core gRPC-appar