gRPC-Dienste mit C#gRPC services with C#

In diesem Artikel werden die Konzepte erläutert, die zum Schreiben von gRPC-Apps in C# erforderlich sind.This document outlines the concepts needed to write gRPC apps in C#. Die hier behandelten Themen gelten für gRPC-Apps, die auf C-Core und auf ASP.NET Core basieren.The topics covered here apply to both C-core-based and ASP.NET Core-based gRPC apps.

Warnung

ASP.NET Core gRPC wird derzeit nicht in Azure App Service oder IIS unterstützt.ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. Die HTTP/2-Implementierung von „Http.Sys“ unterstützt keine nachstehenden HTTP-Antwortheader, auf die gRPC sich stützt.The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. Weitere Informationen finden Sie in diesem GitHub-Issue.For more information, see this GitHub issue.

PROTO-Dateiproto file

gRPC verwendet einen Vertrag zuerst-Ansatz für die API-Entwicklung.gRPC uses a contract-first approach to API development. Protokollpuffer (protobuf) werden standardmäßig als IDL (Interface Definition Language) verwendet.Protocol buffers (protobuf) are used as the Interface Definition Language (IDL) by default. Die *.proto-Datei enthält Folgendes:The *.proto file contains:

  • Die Definition des gRPC-DienstsThe definition of the gRPC service.
  • Die zwischen Clients und Servern übermittelten NachrichtenThe messages sent between clients and servers.

Weitere Informationen zur Syntax von protobuf-Dateien finden Sie unter Erstellen von Protobuf-Nachrichten für .NET-Apps.For more information on the syntax of protobuf files, see Erstellen von Protobuf-Nachrichten für .NET-Apps.

Sehen Sie sich beispielsweise die Datei greet.proto an, die in den ersten Schritten mit dem gRPC-Dienst verwendet wird:For example, consider the greet.proto file used in Get started with gRPC service:

  • Die Datei definiert einen Greeter-Dienst.Defines a Greeter service.
  • Der Greeter-Dienst definiert einen SayHello-Aufruf.The Greeter service defines a SayHello call.
  • SayHello sendet eine HelloRequest-Nachricht und empfängt eine HelloReply-Nachricht:SayHello sends a HelloRequest message and receives a HelloReply message:
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;
}

Wenn Sie möchten, dass Codekommentare in anderen Sprachen als Englisch angezeigt werden, informieren Sie uns in diesem GitHub-Issue.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

Hinzufügen einer PROTO-Datei zu einer C#-AppAdd a .proto file to a C# app

Die *.proto-Datei wird in ein Projekt eingefügt, indem sie zur Elementgruppe <Protobuf> hinzugefügt wird:The *.proto file is included in a project by adding it to the <Protobuf> item group:

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

Durch einen <Protobuf>-Verweis werden standardmäßig ein konkreter Client und eine Dienstbasisklasse generiert.By default, a <Protobuf> reference generates a concrete client and a service base class. Mit dem Attribut GrpcServices des Verweiselements kann das Generieren von C#-Objekten beschränkt werden.The reference element's GrpcServices attribute can be used to limit C# asset generation. Gültige Optionen für GrpcServices sind:Valid GrpcServices options are:

  • Both (Standardwert, wenn nicht vorhanden)Both (default when not present)
  • Server
  • Client
  • None

C#-Toolunterstützung für PROTO-DateienC# Tooling support for .proto files

Das Toolpaket Grpc.Tools ist zum Generieren der C#-Ressourcen aus *.proto-Dateien erforderlich.The tooling package Grpc.Tools is required to generate the C# assets from *.proto files. Die generierten Ressourcen (Dateien):The generated assets (files):

  • Werden jedes Mal nach Bedarf generiert, wenn der Buildvorgang für das Projekt ausgeführt wird.Are generated on an as-needed basis each time the project is built.
  • Werden nicht zum Projekt hinzugefügt oder in der Quellcodeverwaltung eingecheckt.Aren't added to the project or checked into source control.
  • Sind Buildartefakte, die im obj-Verzeichnis enthalten sind.Are a build artifact contained in the obj directory.

Dieses Paket ist für die Server- und Clientprojekte erforderlich.This package is required by both the server and client projects. Das Metapaket Grpc.AspNetCore enthält einen Verweis auf Grpc.Tools.The Grpc.AspNetCore metapackage includes a reference to Grpc.Tools. Serverprojekte können Grpc.AspNetCore mithilfe des Paket-Managers in Visual Studio oder durch Hinzufügen von <PackageReference> zur Projektdatei hinzufügen:Server projects can add Grpc.AspNetCore using the Package Manager in Visual Studio or by adding a <PackageReference> to the project file:

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

Clientprojekte sollten direkt auf Grpc.Tools sowie auf die anderen zum Verwenden des gRPC-Clients erforderlichen Pakete verweisen.Client projects should directly reference Grpc.Tools alongside the other packages required to use the gRPC client. Das Toolpaket ist nicht zur Laufzeit erforderlich, darum ist die Abhängigkeit mit PrivateAssets="All" markiert:The tooling package isn't required at runtime, so the dependency is marked with PrivateAssets="All":

<PackageReference Include="Google.Protobuf" Version="3.11.4" />
<PackageReference Include="Grpc.Net.Client" Version="2.28.0" />
<PackageReference Include="Grpc.Tools" Version="2.28.1">

Generierte C#-RessourcenGenerated C# assets

Das Toolpaket generiert die C#-Typen, die die Nachrichten darstellen, die in den enthaltenen *.proto-Dateien definiert werden.The tooling package generates the C# types representing the messages defined in the included *.proto files.

Für serverseitige Ressourcen wird ein abstrakter Dienstbasistyp generiert.For server-side assets, an abstract service base type is generated. Der Basistyp enthält die Definitionen für alle gRPC-Aufrufe, die in der PROTO-Datei enthalten sind.The base type contains the definitions of all the gRPC calls contained in the .proto file. Erstellen Sie eine konkrete Dienstimplementierung, die von diesem Basistyp abgeleitet wird und die Logik für die gRPC-Aufrufe implementiert.Create a concrete service implementation that derives from this base type and implements the logic for the gRPC calls. Für das zuvor beschriebene Beispiel greet.proto wird ein abstrakter GreeterBase-Typ generiert, der eine virtuelle SayHello-Methode enthält.For the greet.proto, the example described previously, an abstract GreeterBase type that contains a virtual SayHello method is generated. Eine konkrete GreeterService-Implementierung überschreibt die Methode und implementiert die Logik, die den gRPC-Aufruf verarbeitet.A concrete implementation GreeterService overrides the method and implements the logic handling the gRPC call.

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 clientseitige Ressourcen wird ein konkreter Clienttyp generiert.For client-side assets, a concrete client type is generated. Die gRPC-Aufrufe in der PROTO-Datei werden in Methoden für den konkreten Typ übersetzt, die aufgerufen werden können.The gRPC calls in the .proto file are translated into methods on the concrete type, which can be called. Für das zuvor beschriebene Beispiel greet.proto wird ein konkreter GreeterClient-Typ generiert.For the greet.proto, the example described previously, a concrete GreeterClient type is generated. Rufen Sie GreeterClient.SayHelloAsync auf, um einen gRPC-Aufruf an den Server zu initiieren.Call GreeterClient.SayHelloAsync to initiate a gRPC call to the server.

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- und Clientressourcen werden standardmäßig für alle *.proto-Dateien generiert, die in der Elementgruppe <Protobuf> enthalten sind.By default, server and client assets are generated for each *.proto file included in the <Protobuf> item group. Das GrpcServices-Attribut wird auf Server festgelegt, um sicherzustellen, dass nur die Serverressourcen in einem Serverprojekt generiert werden.To ensure only the server assets are generated in a server project, the GrpcServices attribute is set to Server.

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

Entsprechend wird das Attribut bei Clientprojekten auf Client festgelegt.Similarly, the attribute is set to Client in client projects.

Zusätzliche RessourcenAdditional resources