gRPC JSON-omkodning i ASP.NET Core

Av James Newton-King

gRPC är ett RPC-ramverk (Remote Procedure Call) med höga prestanda. gRPC använder HTTP/2, streaming, Protobuf och meddelandekontrakt för att skapa högpresterande realtidstjänster.

En begränsning med gRPC är att inte alla plattformar kan använda den. Webbläsare har inte fullständigt stöd för HTTP/2, vilket gör REST API:er och JSON till det primära sättet att hämta data till webbläsarappar. Trots de fördelar som gRPC medför REST har API:er och JSON en viktig plats i moderna appar. Att skapa gRPC - och JSON-webb-API:er lägger till oönskade kostnader för apputveckling.

I det här dokumentet beskrivs hur du skapar JSON-webb-API:er med hjälp av gRPC-tjänster.

Översikt

gRPC JSON-transkodning är ett tillägg för ASP.NET Core som skapar RESTful JSON-API:er för gRPC-tjänster. När den har konfigurerats tillåter omkodning att appar anropar gRPC-tjänster med välbekanta HTTP-begrepp:

• HTTP-verb
• URL-parameterbindning
• JSON-begäranden/-svar

gRPC kan fortfarande användas för att anropa tjänster.

Anmärkning

gRPC JSON-omkodning ersätter gRPC HTTP API, ett alternativt experimentellt tillägg.

Usage

1. Lägg till en paketreferens till Microsoft.AspNetCore.Grpc.JsonTranscoding.

2. Registrera omkodning i serverns startkod genom att lägga till AddJsonTranscoding: I Program.cs filen ändrar du builder.Services.AddGrpc(); till builder.Services.AddGrpc().AddJsonTranscoding();.

3. Lägg till <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos> i egenskapsgruppen i projektfilen (.csproj):

   <Project Sdk="Microsoft.NET.Sdk.Web">
   
     <PropertyGroup>
       <TargetFramework>net8.0</TargetFramework>
       <Nullable>enable</Nullable>
       <ImplicitUsings>enable</ImplicitUsings>
       <InvariantGlobalization>true</InvariantGlobalization>
       <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos>
     </PropertyGroup>
   

4. Kommentera gRPC-metoder i dina .proto filer med HTTP-bindningar och vägar:

   syntax = "proto3";
   
   option csharp_namespace = "GrpcServiceTranscoding";
   import "google/api/annotations.proto";
   
   package greet;
   
   // The greeting service definition.
   service Greeter {
     rpc SayHello (HelloRequest) returns (HelloReply) {
       option (google.api.http) = {
         get: "/v1/greeter/{name}"
       };
     }
   }
   
   // The request message containing the user's name.
   message HelloRequest {
     string name = 1;
   }
   
   // The response message containing the greetings.
   message HelloReply {
     string message = 1;
   }
   

GRPC-metoden SayHello kan nu anropas som gRPC och som ett JSON-webb-API:

• Begäran: GET /v1/greeter/world
• Svar: { "message": "Hello world" }

Om servern har konfigurerats för att skriva loggar för varje begäran visar serverloggarna att en gRPC-tjänst kör HTTP-anropet. Omkodning mappar den inkommande HTTP-begäran till ett gRPC-meddelande och konverterar svarsmeddelandet till JSON.

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/1.1 GET https://localhost:5001/v1/greeter/world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /v1/greeter/{name}'
info: Server.GreeterService[0]
      Sending hello to world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /v1/greeter/{name}'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 1.996ms 200 application/json

Kommentera gRPC-metoder

gRPC-metoder måste kommenteras med en HTTP-regel innan de stöder transkodning. HTTP-regeln innehåller information om hur du anropar gRPC-metoden, till exempel HTTP-metoden och vägen.

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };
  }
}

Följande exempel:

• Definierar en Greeter tjänst med en SayHello metod. Metoden har en HTTP-regel angiven med namnet google.api.http.
• Metoden är tillgänglig med GET förfrågningar och /v1/greeter/{name} rutt.
• Fältet name i begärandemeddelandet är bundet till en vägparameter.

Det finns många alternativ för att anpassa hur en gRPC-metod binder till ett RESTful-API. Mer information om hur du kommenterar gRPC-metoder och anpassar JSON finns i Konfigurera HTTP och JSON för gRPC JSON-transkodning.

Streamingtekniker

Traditionell gRPC via HTTP/2 stöder strömning i alla riktningar. Omkodning är endast begränsat till serverströmning. Klientströmning och dubbelriktade strömningsmetoder stöds inte.

Serverströmningsmetoder använder radavgränsad JSON. Varje meddelande som skrivs med WriteAsync serialiseras till JSON och följs av en ny rad.

Följande serverströmningsmetod skriver tre meddelanden:

public override async Task StreamingFromServer(ExampleRequest request,
    IServerStreamWriter<ExampleResponse> responseStream, ServerCallContext context)
{
    for (var i = 1; i <= 3; i++)
    {
        await responseStream.WriteAsync(new ExampleResponse { Text = $"Message {i}" });
        await Task.Delay(TimeSpan.FromSeconds(1));
    }
}

Klienten tar emot tre radavgränsade JSON-objekt:

{"Text":"Message 1"}
{"Text":"Message 2"}
{"Text":"Message 3"}

Observera att WriteIndented JSON-inställningen inte gäller för serverströmningsmetoder. Snygga utskrifter lägger till nya rader och blanksteg i JSON, som inte kan användas med radavgränsad JSON.

Visa eller ladda ned ett exempel på en ASP.NET Core gPRC-omkodning och strömmande app.

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. HTTP/2 är en bra standard när en app endast stöder traditionell gRPC via HTTP/2. Omkodning 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 om hur du konfigurerar HTTP-protokoll i en gRPC-app finns i ASP.NET Core gRPC-protokollförhandling.

gRPC JSON-omkodning jämfört med gRPC-Web

Både omkodning och gRPC-Web tillåter att gRPC-tjänster anropas från en webbläsare. Hur var och en gör detta är dock annorlunda:

• gRPC-Web låter webbläsarappar anropa gRPC-tjänster från webbläsaren med gRPC-Web-klienten och Protobuf. gRPC-Web kräver att webbläsarappen genererar en gRPC-klient och har fördelen att skicka små, snabba Protobuf-meddelanden.
• Med omkodning kan webbläsarappar anropa gRPC-tjänster som om de vore RESTful-API:er med JSON. Webbläsarappen behöver inte generera en gRPC-klient eller veta något om gRPC.

Den tidigare Greeter tjänsten kan anropas med javascript-API:er i webbläsaren:

var name = nameInput.value;

fetch('/v1/greeter/' + name)
  .then((response) => response.json())
  .then((result) => {
    console.log(result.message);
    // Hello world
  });

grpc-gateway

grpc-gateway är en annan teknik för att skapa RESTful JSON-API:er från gRPC-tjänster. Den använder samma .proto anteckningar för att mappa HTTP-begrepp till gRPC-tjänster.

grpc-gateway använder kodgenerering för att skapa en omvänd proxyserver. Den omvända proxyn översätter RESTful-anrop till gRPC+Protobuf och skickar anropen via HTTP/2 till gRPC-tjänsten. Fördelen med den här metoden är att gRPC-tjänsten inte känner till RESTful JSON-API:er. Alla gRPC-servrar kan använda grpc-gateway.

Samtidigt körs gRPC JSON-omkodning i en ASP.NET Core-app. Den deserialiserar JSON till Protobuf-meddelanden och anropar sedan gRPC-tjänsten direkt. Omkodning i ASP.NET Core erbjuder fördelar för .NET-apputvecklare:

• Mindre komplext: Både gRPC-tjänster och mappade RESTful JSON API körs på en och samma ASP.NET Core-app.
• Bättre prestanda: Omkodning deserialiserar JSON till Protobuf-meddelanden och anropar gRPC-tjänsten direkt. Det finns betydande prestandafördelar med att göra detta i processen jämfört med att göra ett nytt gRPC-anrop till en annan server.
• Lägre kostnad: Färre servrar resulterar i en mindre månatlig värdfaktura.

Information om installation och användning av grpc-gateway finns i GRPC-gateway README.

Ytterligare resurser

• Konfigurera HTTP och JSON för gRPC JSON-transkodning i ASP.NET Core-appar
• Använd OpenAPI med gRPC-JSON-transkodning i ASP.NET Core-appar
• Använda gRPC i webbläsarappar
• gRPC-Web i ASP.NET Core gRPC-applikationer