Usługi gRPC w środowisku C#

W tym dokumencie opisano pojęcia niezbędne do pisania aplikacji gRPC w języku C#. Omówione tutaj tematy dotyczą zarówno aplikacji gRPC opartych na języku C, jak i ASP.NET Core.

plik proto

Usługa gRPC korzysta z podejścia opartego na kontraktach do tworzenia interfejsów API. Protocol Buffers (Protobuf) są domyślnie używane jako język opisu interfejsu (IDL). Plik .proto zawiera:

• Definicja usługi gRPC.
• Komunikaty wysyłane między klientami i serwerami.

Aby uzyskać więcej informacji na temat składni plików protobuf, zobacz Create Protobuf messages for .NET apps (Tworzenie komunikatów Protobuf dla aplikacji platformy .NET).

Rozważmy na przykład plik greet.proto używany w artykule Wprowadzenie do usługi gRPC:

• Definiuje usługę Greeter .
• Usługa Greeter definiuje wywołanie SayHello .
• SayHello wysyła HelloRequest wiadomość i odbiera HelloReply komunikat:

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

.proto Dodawanie pliku do aplikacji w języku C#

Plik .proto znajduje się w projekcie, dodając go do <Protobuf> grupy elementów:

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

Domyślnie odwołanie <Protobuf> generuje konkretnego klienta i klasę bazową usługi. Atrybut elementu odwołania GrpcServices może służyć do ograniczania generowania zasobów w C#. Prawidłowe GrpcServices opcje to:

• Both (wartość domyślna, jeśli nie jest obecna)
• Server
• Client
• None

Obsługa narzędzi języka C# dla plików .proto

Pakiet narzędzi Grpc.Tools jest wymagany do generowania zasobów języka C# z .proto plików. Wygenerowane zasoby (pliki):

• Są generowane zgodnie z potrzebami za każdym razem, gdy projekt jest kompilowany.
• Nie są dodawane do projektu ani sprawdzane w kontroli źródła.
• To artefakt kompilacji zawarty w katalogu obj .

Ten pakiet jest wymagany zarówno przez projekty serwera, jak i klienta. Metapakiet Grpc.AspNetCore zawiera odwołanie do Grpc.Tools. Projekty serwera mogą dodawać Grpc.AspNetCore przy użyciu Menedżera pakietów programu Visual Studio lub dodając element <PackageReference> do pliku projektu.

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

Projekty klienckie powinny bezpośrednio odwoływać się do Grpc.Tools oraz innych pakietów wymaganych do korzystania z klienta gRPC. Pakiet narzędzi nie jest wymagany w czasie wykonywania, więc zależność jest oznaczona za pomocą polecenia 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>

Wygenerowane zasoby języka C#

Pakiet narzędzi generuje typy języka C# reprezentujące komunikaty zdefiniowane w dołączonych .proto plikach.

W przypadku zasobów po stronie serwera generowany jest abstrakcyjny typ podstawowy usługi. Typ podstawowy zawiera definicje wszystkich wywołań gRPC zawartych w .proto pliku. Utwórz konkretną implementację usługi, która pochodzi z tego typu podstawowego i implementuje logikę wywołań gRPC. W przykładzie greet.proto opisanym wcześniej, generowany jest typ abstrakcyjny GreeterBase, który zawiera metodę wirtualną SayHello. Konkretna implementacja GreeterService zastępuje metodę i implementuje logikę wywołania gRPC.

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

W przypadku zasobów po stronie klienta generowany jest konkretny typ klienta. Wywołania gRPC w .proto pliku są tłumaczone na metody określonego typu, które można wywołać. W przykładzie opisanym wcześniej greet.proto generowany jest konkretny typ GreeterClient. Wywołanie metody GreeterClient.SayHelloAsync w celu zainicjowania wywołania gRPC na serwerze.

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

Domyślnie zasoby serwera i klienta są generowane dla każdego pliku .proto zawartego w grupie elementów <Protobuf>. Aby upewnić się, że tylko zasoby serwera są generowane w projekcie serwera, GrpcServicesatrybut jest ustawiony na Server.

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

Podobnie atrybut jest ustawiany na Client w projektach klienckich.

Dodatkowe zasoby

• Omówienie usługi gRPC na platformie .NET
• Tworzenie klienta i serwera gRPC platformy .NET w programie ASP.NET Core
• Usługi gRPC z platformą ASP.NET Core
• Wywoływanie usług gRPC za pomocą klienta platformy .NET