gRPC-szolgáltatások C#-szal

Ez a dokumentum a gRPC-alkalmazások C#-ban való írásához szükséges fogalmakat ismerteti. Az itt tárgyalt témakörök a C-core-alapú és ASP.NET Core-alapú gRPC-alkalmazásokra is vonatkoznak.

proto fájl

A gRPC egy szerződés-első megközelítést használ az API-fejlesztéshez. A protokollpufferek (protobuf) alapértelmezés szerint az interfészdefiníciós nyelvként (IDL) használatosak. A .proto fájl a következőket tartalmazza:

• A gRPC szolgáltatás definíciója.
• Az ügyfelek és kiszolgálók között küldött üzenetek.

A Protobuf-fájlok szintaxisával kapcsolatos további információkért lásd: Protobuf-üzenetek létrehozása .NET-alkalmazásokhoz.

Vegyük például a gRPC szolgáltatás első lépéseiben használt greet.proto fájlt:

• Definiál egy Greeter szolgáltatást.
• A Greeter szolgáltatás meghatároz egy SayHello hívást.
• SayHello HelloRequest üzenetet küld, és üzenetet kapHelloReply:

syntax = "proto3";

option csharp_namespace = "GrpcGreeter";

package greet;

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply);
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings.
message HelloReply {
  string message = 1;
}

Ha szeretné, hogy a kódkommentárok angolon kívül más nyelvekre is le legyenek fordítva, jelezze nekünk a GitHub vitafórumkérdésénél.

.proto Fájl hozzáadása C#-alkalmazáshoz

A .proto fájl a projekt részét képezi az elemcsoporthoz <Protobuf> való hozzáadással:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>

Alapértelmezés szerint a <Protobuf> hivatkozás egy konkrét ügyfelet és egy alapszolgáltatás-osztályt hoz létre. A referenciaelem attribútuma GrpcServices a C#-objektumok létrehozásának korlátozására használható. Az érvényes GrpcServices beállítások a következők:

• Both (alapértelmezett, ha nincs jelen)
• Server
• Client
• None

C#-eszközök támogatása fájlokhoz .proto

A Grpc.Tools eszközcsomag szükséges a C#-objektumok fájlokból való .proto létrehozásához. A létrehozott objektumok (fájlok):

• Szükség szerint generálódnak minden alkalommal, amikor a projekt összeállításra kerül.
• Nincsenek hozzáadva a projekthez, és nincsenek beadva a forrásvezérlésbe.
• Az obj könyvtárban található build-artefaktumok.

Ezt a csomagot mind a kiszolgálói, mind az ügyfélprojektek igénylik. A Grpc.AspNetCore metacsomag tartalmaz egy hivatkozást a Grpc.Tools-re. A kiszolgálóprojekteken Grpc.AspNetCore hozzáadható a Visual Studio Csomagkezelőjének a használatával, vagy egy <PackageReference> hozzáadásával a projektfájlhoz.

<PackageReference Include="Grpc.AspNetCore" Version="2.32.0" />

Az ügyfélprojekteknek közvetlenül kell hivatkozniuk a Grpc.Tools-ra a gRPC-ügyfél használatához szükséges többi csomag mellett. Futtatókörnyezetben nincs szükség az eszközcsomagra, ezért a függőség a következővel PrivateAssets="All"van megjelölve:

<PackageReference Include="Google.Protobuf" Version="3.18.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.52.0" />
<PackageReference Include="Grpc.Tools" Version="2.40.0">
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  <PrivateAssets>all</PrivateAssets>
</PackageReference>

Létrehozott C#-eszközök

Az eszközcsomag létrehozza a belefoglalt .proto fájlokban definiált üzeneteket képviselő C#-típusokat.

Kiszolgálóoldali objektumok esetében a rendszer létrehoz egy absztrakt szolgáltatásbázis-típust. Az alaptípus tartalmazza a fájlban található összes gRPC-hívás definícióját .proto . Hozzon létre egy konkrét szolgáltatás-implementációt, amely ebből az alaptípusból származik, és implementálja a gRPC-hívások logikáját. A greet.protokorábban ismertetett példában egy virtuális GreeterBase metódust tartalmazó absztrakt SayHello típus jön létre. Egy konkrét implementáció GreeterService felülírja a metódust, és implementálja a gRPC-hívást kezelő logikát.

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;
    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }

    public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

Az ügyféloldali eszközök esetében egy konkrét ügyféltípus jön létre. A fájlban található .proto gRPC-hívások a konkrét típus metódusaiba vannak lefordítva, amelyek meghívhatók. greet.protoA korábban ismertetett példában egy konkrét GreeterClient típus jön létre. Hívd fel GreeterClient.SayHelloAsync-t, hogy kezdeményezhesd a gRPC hívást a kiszolgálóhoz.

// The port number must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:7042");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
                  new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();

Alapértelmezés szerint a kiszolgáló és ügyfél eszközök az elemcsoportban .proto szereplő minden <Protobuf> fájlhoz létrejönnek. Annak érdekében, hogy csak a kiszolgálói objektumok legyenek létrehozva egy kiszolgálóprojektben, az GrpcServices attribútum Serverértéke a következő lesz: .

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>

Hasonlóképpen az attribútum az ügyfélprojektekben is be van állítva Client .

További erőforrások

• .NET-alapú gRPC áttekintése
• .NET gRPC-ügyfél és -kiszolgáló létrehozása a ASP.NET Core-ban
• gRPC-szolgáltatások ASP.NET Core
• GRPC-szolgáltatások hívása a .NET-ügyféllel