Delen via

gRPC-services met C#

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.

In dit document worden de concepten beschreven die nodig zijn voor het schrijven van gRPC-apps in C#. De onderwerpen die hier worden behandeld, zijn van toepassing op zowel C-core- als ASP.NET Core gRPC-apps.

proto file

gRPC maakt gebruik van een contract-first benadering voor API-ontwikkeling. Protocolbuffers (protobuf) worden standaard gebruikt als de Interface Definition Language (IDL). Het .proto bestand bevat:

  • De definitie van de gRPC-service.
  • De berichten die worden verzonden tussen clients en servers.

Zie Protobuf-berichten maken voor .NET-apps voor meer informatie over de syntaxis van protobuf-bestanden.

Denk bijvoorbeeld aan het bestand greet.proto dat wordt gebruikt in Aan de slag met gRPC-service:

  • Hiermee definieert u een Greeter service.
  • De Greeter service definieert een SayHello aanroep.
  • SayHello verzendt een HelloRequest bericht en ontvangt een HelloReply bericht:
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;
}

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

Een .proto bestand toevoegen aan een C#-app

Het .proto bestand wordt opgenomen in een project door het toe te voegen aan de <Protobuf> itemgroep:

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

Standaard genereert een <Protobuf> verwijzing een concrete client en een servicebasisklasse. Het kenmerk GrpcServices van het verwijzingselement kan worden gebruikt om de generatie van C#-assets te beperken. Geldige GrpcServices opties zijn:

  • Both (standaard als deze niet aanwezig is)
  • Server
  • Client
  • None

Tooling-ondersteuning voor C# voor .proto bestanden

Het hulpprogrammapakket Grpc.Tools is vereist om de C#-assets te genereren op basis van .proto bestanden. De gegenereerde middelen (bestanden):

  • Worden op een zo nodig basis gegenereerd elke keer dat het project wordt gebouwd.
  • Worden niet toegevoegd aan het project of ingecheckt in broncodebeheer.
  • Een buildartefact bevindt zich in de obj-map.

Dit pakket is vereist voor zowel de server- als clientprojecten. De Grpc.AspNetCore metapackage bevat een verwijzing naar Grpc.Tools. Serverprojecten kunnen Grpc.AspNetCore toevoegen met behulp van de Package Manager in Visual Studio of door een <PackageReference> toe te voegen aan het projectbestand.

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

Clientprojecten moeten rechtstreeks verwijzen naar Grpc.Tools, evenals de andere pakketten die nodig zijn voor het gebruik van de gRPC-client. Het hulpprogrammapakket is niet vereist tijdens runtime, dus de afhankelijkheid wordt gemarkeerd met 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>

Gegenereerde C#-assets

Het hulpprogrammapakket genereert de C#-typen die de berichten vertegenwoordigen die zijn gedefinieerd in de opgenomen .proto bestanden.

Voor assets aan de serverzijde wordt een abstract servicebasistype gegenereerd. Het basistype bevat de definities van alle gRPC-aanroepen in het .proto bestand. Maak een concrete service-implementatie die is afgeleid van dit basistype en implementeert de logica voor de gRPC-aanroepen. Voor het greet.protovoorbeeld dat eerder is beschreven, wordt een abstract GreeterBase type gegenereerd dat een virtuele SayHello methode bevat. Een concrete implementatie GreeterService overschrijft de methode en implementeert de logica die de gRPC-aanroep verwerkt.

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

Voor assets aan de clientzijde wordt een concreet clienttype gegenereerd. De gRPC-aanroepen in het .proto bestand worden omgezet in methoden op het concrete type, die kunnen worden aangeroepen. Voor het greet.protovoorbeeld dat eerder is beschreven, wordt een concreet GreeterClient type gegenereerd. Aanroep GreeterClient.SayHelloAsync om een gRPC-aanroep naar de server te starten.

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

Server- en clientassets worden standaard gegenereerd voor elk .proto bestand dat in de <Protobuf> itemgroep is opgenomen. Om ervoor te zorgen dat alleen de serverassets worden gegenereerd in een serverproject, wordt het GrpcServices kenmerk ingesteld op Server.

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

Op dezelfde manier wordt het kenmerk in clientprojecten ingesteld op Client.

Additional resources

In dit document worden de concepten beschreven die nodig zijn voor het schrijven van gRPC-apps in C#. De onderwerpen die hier worden behandeld, zijn van toepassing op zowel C-core- als ASP.NET Core gRPC-apps.

proto file

gRPC maakt gebruik van een contract-first benadering voor API-ontwikkeling. Protocolbuffers (protobuf) worden standaard gebruikt als de Interface Definition Language (IDL). Het .proto bestand bevat:

  • De definitie van de gRPC-service.
  • De berichten die worden verzonden tussen clients en servers.

Zie Protobuf-berichten maken voor .NET-apps voor meer informatie over de syntaxis van protobuf-bestanden.

Denk bijvoorbeeld aan het bestand greet.proto dat wordt gebruikt in Aan de slag met gRPC-service:

  • Hiermee definieert u een Greeter service.
  • De Greeter service definieert een SayHello aanroep.
  • SayHello verzendt een HelloRequest bericht en ontvangt een HelloReply bericht:
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;
}

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

Een .proto bestand toevoegen aan een C#-app

Het .proto bestand wordt opgenomen in een project door het toe te voegen aan de <Protobuf> itemgroep:

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

Standaard genereert een <Protobuf> verwijzing een concrete client en een servicebasisklasse. Het kenmerk GrpcServices van het verwijzingselement kan worden gebruikt om de generatie van C#-assets te beperken. Geldige GrpcServices opties zijn:

  • Both (standaard als deze niet aanwezig is)
  • Server
  • Client
  • None

Tooling-ondersteuning voor C# voor .proto bestanden

Het hulpprogrammapakket Grpc.Tools is vereist om de C#-assets te genereren op basis van .proto bestanden. De gegenereerde middelen (bestanden):

  • Worden op een zo nodig basis gegenereerd elke keer dat het project wordt gebouwd.
  • Worden niet toegevoegd aan het project of ingecheckt in broncodebeheer.
  • Een buildartefact bevindt zich in de obj-map.

Dit pakket is vereist voor zowel de server- als clientprojecten. De Grpc.AspNetCore metapackage bevat een verwijzing naar Grpc.Tools. Serverprojecten kunnen Grpc.AspNetCore toevoegen met behulp van de Package Manager in Visual Studio of door een <PackageReference> toe te voegen aan het projectbestand.

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

Clientprojecten moeten rechtstreeks verwijzen naar Grpc.Tools, evenals de andere pakketten die nodig zijn voor het gebruik van de gRPC-client. Het hulpprogrammapakket is niet vereist tijdens runtime, dus de afhankelijkheid wordt gemarkeerd met 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>

Gegenereerde C#-assets

Het hulpprogrammapakket genereert de C#-typen die de berichten vertegenwoordigen die zijn gedefinieerd in de opgenomen .proto bestanden.

Voor assets aan de serverzijde wordt een abstract servicebasistype gegenereerd. Het basistype bevat de definities van alle gRPC-aanroepen in het .proto bestand. Maak een concrete service-implementatie die is afgeleid van dit basistype en implementeert de logica voor de gRPC-aanroepen. Voor het greet.protovoorbeeld dat eerder is beschreven, wordt een abstract GreeterBase type gegenereerd dat een virtuele SayHello methode bevat. Een concrete implementatie GreeterService overschrijft de methode en implementeert de logica die de gRPC-aanroep verwerkt.

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

Voor assets aan de clientzijde wordt een concreet clienttype gegenereerd. De gRPC-aanroepen in het .proto bestand worden omgezet in methoden op het concrete type, die kunnen worden aangeroepen. Voor het greet.protovoorbeeld dat eerder is beschreven, wordt een concreet GreeterClient type gegenereerd. Aanroep GreeterClient.SayHelloAsync om een gRPC-aanroep naar de server te starten.

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

Server- en clientassets worden standaard gegenereerd voor elk .proto bestand dat in de <Protobuf> itemgroep is opgenomen. Om ervoor te zorgen dat alleen de serverassets worden gegenereerd in een serverproject, wordt het GrpcServices kenmerk ingesteld op Server.

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

Op dezelfde manier wordt het kenmerk in clientprojecten ingesteld op Client.

Additional resources