gRPC-tjänster med C#

Det här dokumentet beskriver de begrepp som behövs för att skriva gRPC-appar i C#. Ämnena som beskrivs här gäller både C-core-baserade och ASP.NET Core-baserade gRPC-appar.

proto-fil

gRPC använder en kontraktsinriktad metod för API-utveckling. Protokollbuffertar (protobuf) används som standard som gränssnittsdefinitionsspråk (IDL). Filen .proto innehåller:

• Definitionen av gRPC-tjänsten.
• Meddelandena som skickas mellan klienter och servrar.

Mer information om syntaxen för protobuf-filer finns i Skapa Protobuf-meddelanden för .NET-appar.

Tänk till exempel på filen greet.proto som används i Kom igång med gRPC-tjänsten:

• Definierar en Greeter tjänst.
• Tjänsten Greeter definierar ett SayHello anrop.
• SayHello skickar ett HelloRequest meddelande och tar emot ett HelloReply meddelande:

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

Om du vill se kodkommentar översatta till andra språk än engelska kan du meddela oss i det här GitHub-diskussionsproblemet.

Lägga till en .proto fil i en C#-app

Filen .proto ingår i ett projekt genom att lägga till den i <Protobuf> objektgruppen:

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

Som standard genererar en <Protobuf> referens en konkret klient och en tjänstbasklass. Referenselementets GrpcServices attribut kan användas för att reglera C#-kodgenereringen. Giltiga GrpcServices alternativ är:

• Both (standard när det inte finns)
• Server
• Client
• None

Stöd för C#-verktyg för .proto filer

Verktygspaketet Grpc.Tools krävs för att generera C#-tillgångarna från .proto filer. De genererade tillgångarna (filer):

• Genereras efter behov varje gång projektet skapas.
• Läggs inte till i projektet eller checkas in i källkontrollen.
• Finns kompileringsartefakter i obj-katalogen.

Det här paketet krävs av både server- och klientprojekten. Metapaketet Grpc.AspNetCore innehåller en referens till Grpc.Tools. Serverprojekt kan lägga till Grpc.AspNetCore med hjälp av Package Manager i Visual Studio eller genom att lägga till en <PackageReference> i projektfilen:

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

Klientprojekt bör referera direkt Grpc.Tools tillsammans med de andra paket som krävs för att använda gRPC-klienten. Verktygspaketet krävs inte vid körning, så beroendet är markerat med PrivateAssets="All":

<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>

Genererade C#-resurser

Verktygspaketet genererar C#-typerna som representerar de meddelanden som definieras i de inkluderade .proto filerna.

För tillgångar på serversidan genereras en abstrakt tjänstbastyp. Bastypen innehåller definitionerna för alla gRPC-anrop som finns i .proto filen. Skapa en konkret tjänstimplementering som härleds från den här bastypen och implementerar logiken för gRPC-anropen. greet.protoI exemplet som beskrevs tidigare genereras en abstrakt GreeterBase typ som innehåller en virtuell SayHello metod. En konkret implementering GreeterService åsidosätter metoden och implementerar logikhanteringen av gRPC-anropet.

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

För tillgångar på klientsidan genereras en konkret klienttyp. gRPC-anropen i .proto-filen översätts till metoder hos den konkreta typen, som kan anropas. greet.protoI exemplet som beskrevs tidigare genereras en konkret GreeterClient typ. Anropa GreeterClient.SayHelloAsync för att initiera ett gRPC-anrop till servern.

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

Som standard genereras server- och klienttillgångar för varje .proto fil som ingår i <Protobuf> objektgruppen. För att säkerställa att endast servertillgångarna genereras i ett serverprojekt GrpcServices är attributet inställt på Server.

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

På samma sätt är attributet inställt på Client i klientprojekt.

Ytterligare resurser

• Översikt över gRPC på .NET
• Skapa en .NET gRPC-klient och -server i ASP.NET Core
• gRPC-tjänster med ASP.NET Core
• Anropa gRPC-tjänster med .NET-klienten