Dela via

gRPC-tjänster med C#

Note

Det här är inte den senaste versionen av den här artikeln. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Warning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i supportpolicyn för .NET och .NET Core. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Important

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

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 file

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.

Additional resources

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 file

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.28.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.11.4" />
<PackageReference Include="Grpc.Net.Client" Version="2.52.0" />
<PackageReference Include="Grpc.Tools" Version="2.28.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</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.

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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.

Additional resources