Delen via

gRPC-Web in ASP.NET Core gRPC-apps

Note

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikel voor de huidige release.

Warning

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET- en .NET Core-ondersteuningsbeleid voor meer informatie. Zie de .NET 9-versie van dit artikel voor de huidige release.

Important

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikel voor de huidige release.

Door James Newton-King

Meer informatie over het configureren van een bestaande ASP.NET Core gRPC-service die kan worden aangeroepen vanuit browser-apps met behulp van het gRPC-Web-protocol . met gRPC-Web kunnen Browser JavaScript en Blazor apps gRPC-services aanroepen. Het is niet mogelijk om een HTTP/2 gRPC-service aan te roepen vanuit een browser-app. gRPC-services die worden gehost in ASP.NET Core kunnen worden geconfigureerd ter ondersteuning van gRPC-Web naast HTTP/2 gRPC.

Zie GRPC-services toevoegen aan een ASP.NET Core-app voor instructies over het toevoegen van een gRPC-service aan een bestaande ASP.NET Core-app.

Zie Een .NET gRPC-client en -server maken in ASP.NET Core voor instructies voor het maken van een gRPC-project.

ASP.NET Core gRPC-Web versus Envoy

Er zijn twee opties voor het toevoegen van gRPC-Web aan een ASP.NET Core-app:

  • Ondersteuning voor gRPC-Web naast gRPC HTTP/2 in ASP.NET Core. Deze optie maakt gebruik van middleware die door het Grpc.AspNetCore.Web pakket wordt geleverd.
  • Gebruik de gRPC-Web-ondersteuning van de Envoy-proxy om gRPC-Web te vertalen naar gRPC HTTP/2. De vertaalde oproep wordt vervolgens doorgestuurd naar de ASP.NET Core-app.

Er zijn voor- en nadelen voor elke benadering. Als de omgeving van een app al Gebruikmaakt van Envoy als proxy, kan het zinvol zijn om ook Envoy te gebruiken om gRPC-Web-ondersteuning te bieden. Voor een basisoplossing voor gRPC-Web waarvoor alleen ASP.NET Core is vereist, Grpc.AspNetCore.Web is dit een goede keuze.

gRPC-Web configureren in ASP.NET Core

gRPC-services die worden gehost in ASP.NET Core kunnen worden geconfigureerd ter ondersteuning van gRPC-Web naast HTTP/2 gRPC. gRPC-Web vereist geen wijzigingen in services. De enige wijziging is het instellen van de middleware in Program.cs.

GRPC-Web inschakelen met een ASP.NET Core gRPC-service:

  • Voeg een verwijzing naar het Grpc.AspNetCore.Web pakket toe.
  • Configureer de app voor het gebruik van gRPC-Web door toe te voegen UseGrpcWeb en EnableGrpcWeb aan 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();

De voorgaande code:

  • Voegt de gRPC-Web-middleware toe, UseGrpcWebna routering en vóór eindpunten.
  • Hiermee geeft u op dat de endpoints.MapGrpcService<GreeterService>() methode gRPC-Web ondersteunt met EnableGrpcWeb.

De gRPC-Web-middleware kan ook worden geconfigureerd, zodat alle services standaard gRPC-Web ondersteunen en EnableGrpcWeb niet vereist zijn. Geef new GrpcWebOptions { DefaultEnabled = true } op wanneer de middleware wordt toegevoegd.

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

Er is een bekend probleem waardoor gRPC-Web mislukt wanneer deze wordt gehost door HTTP.sys in .NET Core 3.x.

Een tijdelijke oplossing om gRPC-Web op HTTP.sys te laten werken is beschikbaar in Grpc-web Experimental en UseHttpSys()? (grpc/grpc-dotnet #853).

gRPC-Web en CORS

Browserbeveiliging voorkomt dat een webpagina aanvragen indient naar een ander domein dan het domein dat de webpagina heeft geleverd. Deze beperking geldt voor het maken van gRPC-web-aanroepen met browser-apps. Een browser-app die door https://www.contoso.com wordt aangeboden, wordt bijvoorbeeld geblokkeerd bij het aanroepen van gRPC-Web-services die worden gehost op https://services.contoso.com. CorS (Cross-Origin Resource Sharing) kan worden gebruikt om deze beperking te versoepelen.

Als u wilt toestaan dat een browser-app cross-origin gRPC-Web-aanroepen uitvoert, stelt u CORS in ASP.NET Core in. Gebruik de ingebouwde CORS-ondersteuning en stel gRPC-specifieke headers beschikbaar met 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();

De voorgaande code:

  • Aanroepen AddCors om CORS-services toe te voegen en een CORS-beleid te configureren waarmee gRPC-specifieke headers worden weergegeven.
  • Aanroepen UseCors om de CORS-middleware toe te voegen na de routeringsconfiguratie en vóór de configuratie van eindpunten.
  • Hiermee geeft u op dat de endpoints.MapGrpcService<GreeterService>() methode CORS ondersteunt met RequireCors.

gRPC-Web en streaming

Traditionele gRPC via HTTP/2 ondersteunt client-, server- en bidirectionele streaming. gRPC-Web biedt beperkte ondersteuning voor streaming:

  • gRPC-webbrowserclients bieden geen ondersteuning voor het aanroepen van clientstreaming- en bidirectionele streamingmethoden.
  • gRPC-Web .NET-clients bieden geen ondersteuning voor het aanroepen van clientstreaming- en bidirectionele streamingmethoden via HTTP/1.1.
  • ASP.NET Core gRPC-services die worden gehost in Azure App Service en IIS bieden geen ondersteuning voor bidirectionele streaming.

Wanneer u gRPC-Web gebruikt, raden we u alleen aan om unaire methoden en serverstreamingmethoden te gebruiken.

HTTP protocol

De ASP.NET Core gRPC-servicesjabloon, opgenomen in de .NET SDK, maakt een app die alleen is geconfigureerd voor HTTP/2. Dit is een goede standaardinstelling wanneer een app alleen ondersteuning biedt voor traditionele gRPC via HTTP/2. gRPC-Web werkt echter met zowel HTTP/1.1 als HTTP/2. Sommige platforms, zoals UWP of Unity, kunnen HTTP/2 niet gebruiken. Als u alle client-apps wilt ondersteunen, configureert u de server om HTTP/1.1 en HTTP/2 in te schakelen.

Het standaardprotocol bijwerken in appsettings.json:

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

U kunt ook eindpunten configureren Kestrel in opstartcode.

Voor het inschakelen van HTTP/1.1 en HTTP/2 op dezelfde poort is TLS vereist voor protocolonderhandeling. Zie ASP.NET Core gRPC-protocolonderhandeling voor meer informatie.

GRPC-Web aanroepen vanuit de browser

Browser-apps kunnen gRPC-Web gebruiken om gRPC-services aan te roepen. Er zijn enkele vereisten en beperkingen bij het aanroepen van gRPC-services met gRPC-Web vanuit de browser:

  • De server moet configuratie bevatten ter ondersteuning van gRPC-Web.
  • Clientstreaming- en bidirectionele streaming-aanroepen worden niet ondersteund. Serverstreaming wordt ondersteund.
  • Voor het aanroepen van gRPC-services in een ander domein is CORS-configuratie op de server vereist.

JavaScript gRPC-Web-client

Er bestaat een JavaScript gRPC-webclient. Zie JavaScript-clientcode schrijven met gRPC-Web voor instructies over het gebruik van gRPC-Web vanuit JavaScript.

gRPC-Web configureren met de .NET gRPC-client

De .NET gRPC-client kan worden geconfigureerd om gRPC-web-aanroepen te maken. Dit is handig voor Blazor WebAssembly apps die worden gehost in de browser en dezelfde HTTP-beperkingen van JavaScript-code hebben. Het aanroepen van gRPC-Web met een .NET-client is hetzelfde als HTTP/2 gRPC. De enige wijziging is hoe het kanaal wordt gemaakt.

GRPC-Web gebruiken:

  • Voeg een verwijzing naar het Grpc.Net.Client.Web pakket toe.
  • Zorg ervoor dat de verwijzing naar Grpc.Net.Client pakket versie 2.29.0 of hoger is.
  • Configureer het kanaal om de GrpcWebHandler te gebruiken:
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" });

De voorgaande code:

  • Hiermee configureert u een kanaal voor het gebruik van gRPC-Web.
  • Maakt een client aan en voert een aanroep uit via het kanaal.

GrpcWebHandler heeft de volgende configuratieopties:

  • InnerHandler: Het onderliggende systeem HttpMessageHandler dat de gRPC HTTP-aanvraag uitvoert, bijvoorbeeld HttpClientHandler.
  • GrpcWebMode: een opsommingstype dat aangeeft of de gRPC HTTP-aanvraag Content-Type is application/grpc-web of application/grpc-web-text.
    • GrpcWebMode.GrpcWeb hiermee configureert u het verzenden van inhoud zonder codering. Default value.
    • GrpcWebMode.GrpcWebText configureert base64-gecodeerde inhoud. Vereist voor serverstreaming-aanroepen in browsers.

GrpcChannelOptions.HttpVersion en GrpcChannelOptions.HttpVersionPolicy kan worden gebruikt om de HTTP-protocolversie te configureren.

Important

Gegenereerde gRPC-clients hebben synchrone en asynchrone methoden voor het aanroepen van unaire methoden. Bijvoorbeeld, SayHello is synchroon en SayHelloAsync is asynchroon. Asynchrone methoden zijn altijd vereist in Blazor WebAssembly. Als u een synchrone methode in een Blazor WebAssembly app aanroept, reageert de app niet meer.

Gebruik de gRPC Client Factory met gRPC-Web

Maak een .NET-client die compatibel is met gRPC-Web met behulp van de gRPC-clientfactory:

  • Voeg pakketverwijzingen toe aan het projectbestand voor de volgende pakketten:
  • Registreer een gRPC-client met afhankelijkheidsinjectie (DI) met behulp van de algemene AddGrpcClient extensiemethode. In een Blazor WebAssembly-app worden services bij de DI geregistreerd in Program.cs.
  • Configureer GrpcWebHandler met behulp van de ConfigurePrimaryHttpMessageHandler extensiemethode.
builder.Services
    .AddGrpcClient<Greet.GreeterClient>(options =>
    {
        options.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(
        () => new GrpcWebHandler(new HttpClientHandler()));

Voor meer informatie, zie gRPC-clientfactory-integratie in .NET.

Additional resources

Meer informatie over het configureren van een bestaande ASP.NET Core gRPC-service die kan worden aangeroepen vanuit browser-apps met behulp van het gRPC-Web-protocol . met gRPC-Web kunnen Browser JavaScript en Blazor apps gRPC-services aanroepen. Het is niet mogelijk om een HTTP/2 gRPC-service aan te roepen vanuit een browser-app. gRPC-services die worden gehost in ASP.NET Core kunnen worden geconfigureerd ter ondersteuning van gRPC-Web naast HTTP/2 gRPC.

Zie GRPC-services toevoegen aan een ASP.NET Core-app voor instructies over het toevoegen van een gRPC-service aan een bestaande ASP.NET Core-app.

Zie Een .NET gRPC-client en -server maken in ASP.NET Core voor instructies voor het maken van een gRPC-project.

Vergelijking van ASP.NET Core gRPC-Web en Envoy

Er zijn twee opties voor het toevoegen van gRPC-Web aan een ASP.NET Core-app:

  • Ondersteuning voor gRPC-Web naast gRPC HTTP/2 in ASP.NET Core. Deze optie maakt gebruik van middleware die door het Grpc.AspNetCore.Web pakket wordt geleverd.
  • Gebruik de gRPC-Web-ondersteuning van de Envoy-proxy om gRPC-Web te vertalen naar gRPC HTTP/2. De vertaalde oproep wordt vervolgens doorgestuurd naar de ASP.NET Core-app.

Er zijn voor- en nadelen voor elke benadering. Als de omgeving van een app al Gebruikmaakt van Envoy als proxy, kan het zinvol zijn om ook Envoy te gebruiken om gRPC-Web-ondersteuning te bieden. Voor een basisoplossing voor gRPC-Web waarvoor alleen ASP.NET Core is vereist, Grpc.AspNetCore.Web is dit een goede keuze.

gRPC-Web configureren in ASP.NET Core

gRPC-services die worden gehost in ASP.NET Core kunnen worden geconfigureerd ter ondersteuning van gRPC-Web naast HTTP/2 gRPC. gRPC-Web vereist geen wijzigingen in services. De enige wijziging is het instellen van de middleware in Program.cs.

GRPC-Web inschakelen met een ASP.NET Core gRPC-service:

  • Voeg een verwijzing naar het Grpc.AspNetCore.Web pakket toe.
  • Configureer de app voor het gebruik van gRPC-Web door toe te voegen UseGrpcWeb en EnableGrpcWeb aan 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();

De voorgaande code:

  • Voegt de gRPC-Web-middleware toe, UseGrpcWebna routering en vóór eindpunten.
  • Hiermee geeft u op dat de endpoints.MapGrpcService<GreeterService>() methode gRPC-Web ondersteunt met EnableGrpcWeb.

De gRPC-Web-middleware kan ook worden geconfigureerd, zodat alle services standaard gRPC-Web ondersteunen en EnableGrpcWeb niet vereist zijn. Geef new GrpcWebOptions { DefaultEnabled = true } op wanneer de middleware wordt toegevoegd.

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

Er is een bekend probleem waardoor gRPC-Web mislukt wanneer deze wordt gehost door HTTP.sys in .NET Core 3.x.

Een tijdelijke oplossing om gRPC-Web op HTTP.sys te laten werken is beschikbaar in Grpc-web Experimental en UseHttpSys()? (grpc/grpc-dotnet #853).

gRPC-Web en CORS

Browserbeveiliging voorkomt dat een webpagina aanvragen indient naar een ander domein dan het domein dat de webpagina heeft geleverd. Deze beperking geldt voor het maken van gRPC-web-aanroepen met browser-apps. Een browser-app die door https://www.contoso.com wordt aangeboden, wordt bijvoorbeeld geblokkeerd bij het aanroepen van gRPC-Web-services die worden gehost op https://services.contoso.com. CorS (Cross-Origin Resource Sharing) kan worden gebruikt om deze beperking te versoepelen.

Als u wilt toestaan dat een browser-app cross-origin gRPC-Web-aanroepen uitvoert, stelt u CORS in ASP.NET Core in. Gebruik de ingebouwde CORS-ondersteuning en stel gRPC-specifieke headers beschikbaar met 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();

De voorgaande code:

  • Aanroepen AddCors om CORS-services toe te voegen en een CORS-beleid te configureren waarmee gRPC-specifieke headers worden weergegeven.
  • Aanroepen UseCors om de CORS-middleware toe te voegen na de routeringsconfiguratie en vóór de configuratie van eindpunten.
  • Hiermee geeft u op dat de endpoints.MapGrpcService<GreeterService>() methode CORS ondersteunt met RequireCors.

gRPC-Web en streaming

Traditionele gRPC via HTTP/2 ondersteunt client-, server- en bidirectionele streaming. gRPC-Web biedt beperkte ondersteuning voor streaming:

  • gRPC-webbrowserclients bieden geen ondersteuning voor het aanroepen van clientstreaming- en bidirectionele streamingmethoden.
  • gRPC-Web .NET-clients bieden geen ondersteuning voor het aanroepen van clientstreaming- en bidirectionele streamingmethoden via HTTP/1.1.
  • ASP.NET Core gRPC-services die worden gehost in Azure App Service en IIS bieden geen ondersteuning voor bidirectionele streaming.

Wanneer u gRPC-Web gebruikt, raden we u alleen aan om unaire methoden en serverstreamingmethoden te gebruiken.

HTTP protocol

De ASP.NET Core gRPC-servicesjabloon, opgenomen in de .NET SDK, maakt een app die alleen is geconfigureerd voor HTTP/2. Dit is een goede standaardinstelling wanneer een app alleen ondersteuning biedt voor traditionele gRPC via HTTP/2. gRPC-Web werkt echter met zowel HTTP/1.1 als HTTP/2. Sommige platforms, zoals UWP of Unity, kunnen HTTP/2 niet gebruiken. Als u alle client-apps wilt ondersteunen, configureert u de server om HTTP/1.1 en HTTP/2 in te schakelen.

Het standaardprotocol bijwerken in appsettings.json:

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

U kunt ook eindpunten configureren Kestrel in opstartcode.

Voor het inschakelen van HTTP/1.1 en HTTP/2 op dezelfde poort is TLS vereist voor protocolonderhandeling. Zie ASP.NET Core gRPC-protocolonderhandeling voor meer informatie.

GRPC-Web aanroepen vanuit de browser

Browser-apps kunnen gRPC-Web gebruiken om gRPC-services aan te roepen. Er zijn enkele vereisten en beperkingen bij het aanroepen van gRPC-services met gRPC-Web vanuit de browser:

  • De server moet configuratie bevatten ter ondersteuning van gRPC-Web.
  • Clientstreaming- en bidirectionele streaming-aanroepen worden niet ondersteund. Serverstreaming wordt ondersteund.
  • Voor het aanroepen van gRPC-services in een ander domein is CORS-configuratie op de server vereist.

JavaScript gRPC-Web-client

Er bestaat een JavaScript gRPC-webclient. Zie JavaScript-clientcode schrijven met gRPC-Web voor instructies over het gebruik van gRPC-Web vanuit JavaScript.

gRPC-Web configureren met de .NET gRPC-client

De .NET gRPC-client kan worden geconfigureerd om gRPC-web-aanroepen te maken. Dit is handig voor Blazor WebAssembly apps die worden gehost in de browser en dezelfde HTTP-beperkingen van JavaScript-code hebben. Het aanroepen van gRPC-Web met een .NET-client is hetzelfde als HTTP/2 gRPC. De enige wijziging is hoe het kanaal wordt gemaakt.

GRPC-Web gebruiken:

  • Voeg een verwijzing naar het Grpc.Net.Client.Web pakket toe.
  • Zorg ervoor dat de verwijzing naar Grpc.Net.Client pakket versie 2.29.0 of hoger is.
  • Configureer het kanaal om de GrpcWebHandler te gebruiken:
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" });

De voorgaande code:

  • Hiermee configureert u een kanaal voor het gebruik van gRPC-Web.
  • Maakt een client aan en voert een aanroep uit via het kanaal.

GrpcWebHandler heeft de volgende configuratieopties:

  • InnerHandler: Het onderliggende systeem HttpMessageHandler dat de gRPC HTTP-aanvraag uitvoert, bijvoorbeeld HttpClientHandler.
  • GrpcWebMode: een opsommingstype dat aangeeft of de gRPC HTTP-aanvraag Content-Type is application/grpc-web of application/grpc-web-text.
    • GrpcWebMode.GrpcWeb hiermee configureert u het verzenden van inhoud zonder codering. Default value.
    • GrpcWebMode.GrpcWebText configureert base64-gecodeerde inhoud. Vereist voor serverstreaming-aanroepen in browsers.
  • HttpVersion: HTTP-protocol Version dat wordt gebruikt om in te stellen HttpRequestMessage.Version op de onderliggende gRPC HTTP-aanvraag. gRPC-Web vereist geen specifieke versie en overschrijft de standaardwaarde niet, tenzij opgegeven.

Important

Gegenereerde gRPC-clients hebben synchrone en asynchrone methoden voor het aanroepen van unaire methoden. Bijvoorbeeld, SayHello is synchroon en SayHelloAsync is asynchroon. Asynchrone methoden zijn altijd vereist in Blazor WebAssembly. Als u een synchrone methode in een Blazor WebAssembly app aanroept, reageert de app niet meer.

Gebruik de gRPC Client Factory met gRPC-Web

Maak een .NET-client die compatibel is met gRPC-Web met behulp van de gRPC-clientfactory:

  • Voeg pakketverwijzingen toe aan het projectbestand voor de volgende pakketten:
  • Registreer een gRPC-client met afhankelijkheidsinjectie (DI) met behulp van de algemene AddGrpcClient extensiemethode. In een Blazor WebAssembly-app worden services bij de DI geregistreerd in Program.cs.
  • Configureer GrpcWebHandler met behulp van de ConfigurePrimaryHttpMessageHandler extensiemethode.
builder.Services
    .AddGrpcClient<Greet.GreeterClient>(options =>
    {
        options.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(
        () => new GrpcWebHandler(new HttpClientHandler()));

Voor meer informatie, zie gRPC-clientfactory-integratie in .NET.

Additional resources

Meer informatie over het configureren van een bestaande ASP.NET Core gRPC-service die kan worden aangeroepen vanuit browser-apps met behulp van het gRPC-Web-protocol . met gRPC-Web kunnen Browser JavaScript en Blazor apps gRPC-services aanroepen. Het is niet mogelijk om een HTTP/2 gRPC-service aan te roepen vanuit een browser-app. gRPC-services die worden gehost in ASP.NET Core kunnen worden geconfigureerd ter ondersteuning van gRPC-Web naast HTTP/2 gRPC.

Zie GRPC-services toevoegen aan een ASP.NET Core-app voor instructies over het toevoegen van een gRPC-service aan een bestaande ASP.NET Core-app.

Zie Een .NET gRPC-client en -server maken in ASP.NET Core voor instructies voor het maken van een gRPC-project.

ASP.NET Core gRPC-Web versus Envoy

Er zijn twee opties voor het toevoegen van gRPC-Web aan een ASP.NET Core-app:

  • Ondersteuning voor gRPC-Web naast gRPC HTTP/2 in ASP.NET Core. Deze optie maakt gebruik van middleware die door het Grpc.AspNetCore.Web pakket wordt geleverd.
  • Gebruik de gRPC-Web-ondersteuning van de Envoy-proxy om gRPC-Web te vertalen naar gRPC HTTP/2. De vertaalde oproep wordt vervolgens doorgestuurd naar de ASP.NET Core-app.

Er zijn voor- en nadelen voor elke benadering. Als de omgeving van een app al Gebruikmaakt van Envoy als proxy, kan het zinvol zijn om ook Envoy te gebruiken om gRPC-Web-ondersteuning te bieden. Voor een basisoplossing voor gRPC-Web waarvoor alleen ASP.NET Core is vereist, Grpc.AspNetCore.Web is dit een goede keuze.

gRPC-Web configureren in ASP.NET Core

gRPC-services die worden gehost in ASP.NET Core kunnen worden geconfigureerd ter ondersteuning van gRPC-Web naast HTTP/2 gRPC. gRPC-Web vereist geen wijzigingen in services. De enige wijziging is opstartconfiguratie.

GRPC-Web inschakelen met een ASP.NET Core gRPC-service:

  • Voeg een verwijzing naar het Grpc.AspNetCore.Web pakket toe.
  • Configureer de app voor het gebruik van gRPC-Web door toe te voegen UseGrpcWeb en EnableGrpcWeb aan Startup.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();
    });
}

De voorgaande code:

  • Voegt de gRPC-Web-middleware toe, UseGrpcWebna routering en vóór eindpunten.
  • Hiermee geeft u op dat de endpoints.MapGrpcService<GreeterService>() methode gRPC-Web ondersteunt met EnableGrpcWeb.

De gRPC-Web-middleware kan ook worden geconfigureerd, zodat alle services standaard gRPC-Web ondersteunen en EnableGrpcWeb niet vereist zijn. Geef new GrpcWebOptions { DefaultEnabled = true } op wanneer de middleware wordt toegevoegd.

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

Note

Er is een bekend probleem waardoor gRPC-Web mislukt wanneer deze wordt gehost door HTTP.sys in .NET Core 3.x.

Een tijdelijke oplossing om gRPC-Web op HTTP.sys te laten werken is beschikbaar in Grpc-web Experimental en UseHttpSys()? (grpc/grpc-dotnet #853).

gRPC-Web en CORS

Browserbeveiliging voorkomt dat een webpagina aanvragen indient naar een ander domein dan het domein dat de webpagina heeft geleverd. Deze beperking geldt voor het maken van gRPC-web-aanroepen met browser-apps. Een browser-app die door https://www.contoso.com wordt aangeboden, wordt bijvoorbeeld geblokkeerd bij het aanroepen van gRPC-Web-services die worden gehost op https://services.contoso.com. CorS (Cross-Origin Resource Sharing) kan worden gebruikt om deze beperking te versoepelen.

Als u wilt toestaan dat een browser-app cross-origin gRPC-Web-aanroepen uitvoert, stelt u CORS in ASP.NET Core in. Gebruik de ingebouwde CORS-ondersteuning en stel gRPC-specifieke headers beschikbaar met 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");
    });
}

De voorgaande code:

  • Aanroepen AddCors om CORS-services toe te voegen en een CORS-beleid te configureren waarmee gRPC-specifieke headers worden weergegeven.
  • Aanroepen UseCors om de CORS-middleware toe te voegen na de routeringsconfiguratie en vóór de configuratie van eindpunten.
  • Hiermee geeft u op dat de endpoints.MapGrpcService<GreeterService>() methode CORS ondersteunt met RequireCors.

gRPC-Web en streaming

Traditionele gRPC via HTTP/2 ondersteunt client-, server- en bidirectionele streaming. gRPC-Web biedt beperkte ondersteuning voor streaming:

  • gRPC-webbrowserclients bieden geen ondersteuning voor het aanroepen van clientstreaming- en bidirectionele streamingmethoden.
  • gRPC-Web .NET-clients bieden geen ondersteuning voor het aanroepen van clientstreaming- en bidirectionele streamingmethoden via HTTP/1.1.
  • ASP.NET Core gRPC-services die worden gehost in Azure App Service en IIS bieden geen ondersteuning voor bidirectionele streaming.

Wanneer u gRPC-Web gebruikt, raden we u alleen aan om unaire methoden en serverstreamingmethoden te gebruiken.

HTTP protocol

De ASP.NET Core gRPC-servicesjabloon, opgenomen in de .NET SDK, maakt een app die alleen is geconfigureerd voor HTTP/2. Dit is een goede standaardinstelling wanneer een app alleen ondersteuning biedt voor traditionele gRPC via HTTP/2. gRPC-Web werkt echter met zowel HTTP/1.1 als HTTP/2. Sommige platforms, zoals UWP of Unity, kunnen HTTP/2 niet gebruiken. Als u alle client-apps wilt ondersteunen, configureert u de server om HTTP/1.1 en HTTP/2 in te schakelen.

Het standaardprotocol bijwerken in appsettings.json:

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

U kunt ook eindpunten configureren Kestrel in opstartcode.

Voor het inschakelen van HTTP/1.1 en HTTP/2 op dezelfde poort is TLS vereist voor protocolonderhandeling. Zie ASP.NET Core gRPC-protocolonderhandeling voor meer informatie.

GRPC-Web aanroepen vanuit de browser

Browser-apps kunnen gRPC-Web gebruiken om gRPC-services aan te roepen. Er zijn enkele vereisten en beperkingen bij het aanroepen van gRPC-services met gRPC-Web vanuit de browser:

  • De server moet configuratie bevatten ter ondersteuning van gRPC-Web.
  • Clientstreaming- en bidirectionele streaming-aanroepen worden niet ondersteund. Serverstreaming wordt ondersteund.
  • Voor het aanroepen van gRPC-services in een ander domein is CORS-configuratie op de server vereist.

JavaScript gRPC-Web-client

Er bestaat een JavaScript gRPC-webclient. Zie JavaScript-clientcode schrijven met gRPC-Web voor instructies over het gebruik van gRPC-Web vanuit JavaScript.

gRPC-Web configureren met de .NET gRPC-client

De .NET gRPC-client kan worden geconfigureerd om gRPC-web-aanroepen te maken. Dit is handig voor Blazor WebAssembly apps die worden gehost in de browser en dezelfde HTTP-beperkingen van JavaScript-code hebben. Het aanroepen van gRPC-Web met een .NET-client is hetzelfde als HTTP/2 gRPC. De enige wijziging is hoe het kanaal wordt gemaakt.

GRPC-Web gebruiken:

  • Voeg een verwijzing naar het Grpc.Net.Client.Web pakket toe.
  • Zorg ervoor dat de verwijzing naar Grpc.Net.Client pakket versie 2.29.0 of hoger is.
  • Configureer het kanaal om de GrpcWebHandler te gebruiken:
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" });

De voorgaande code:

  • Hiermee configureert u een kanaal voor het gebruik van gRPC-Web.
  • Maakt een client aan en voert een aanroep uit via het kanaal.

GrpcWebHandler heeft de volgende configuratieopties:

  • InnerHandler: Het onderliggende systeem HttpMessageHandler dat de gRPC HTTP-aanvraag uitvoert, bijvoorbeeld HttpClientHandler.
  • GrpcWebMode: een opsommingstype dat aangeeft of de gRPC HTTP-aanvraag Content-Type is application/grpc-web of application/grpc-web-text.
    • GrpcWebMode.GrpcWeb hiermee configureert u het verzenden van inhoud zonder codering. Default value.
    • GrpcWebMode.GrpcWebText configureert base64-gecodeerde inhoud. Vereist voor serverstreaming-aanroepen in browsers.
  • HttpVersion: HTTP-protocol Version dat wordt gebruikt om in te stellen HttpRequestMessage.Version op de onderliggende gRPC HTTP-aanvraag. gRPC-Web vereist geen specifieke versie en overschrijft de standaardwaarde niet, tenzij opgegeven.

Important

Gegenereerde gRPC-clients hebben synchrone en asynchrone methoden voor het aanroepen van unaire methoden. Bijvoorbeeld, SayHello is synchroon en SayHelloAsync is asynchroon. Asynchrone methoden zijn altijd vereist in Blazor WebAssembly. Als u een synchrone methode in een Blazor WebAssembly app aanroept, reageert de app niet meer.

Gebruik de gRPC Client Factory met gRPC-Web

Maak een .NET-client die compatibel is met gRPC-Web met behulp van de gRPC-clientfactory:

  • Voeg pakketverwijzingen toe aan het projectbestand voor de volgende pakketten:
  • Registreer een gRPC-client met afhankelijkheidsinjectie (DI) met behulp van de algemene AddGrpcClient extensiemethode. In een Blazor WebAssembly-app worden services bij de DI geregistreerd in Program.cs.
  • Configureer GrpcWebHandler met behulp van de ConfigurePrimaryHttpMessageHandler extensiemethode.
builder.Services
    .AddGrpcClient<Greet.GreeterClient>(options =>
    {
        options.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(
        () => new GrpcWebHandler(new HttpClientHandler()));

Voor meer informatie, zie gRPC-clientfactory-integratie in .NET.

Additional resources