usługi gRPC w języku C#gRPC services with C#

W tym dokumencie przedstawiono koncepcje niezbędne do pisania aplikacji gRPC w języku C#.This document outlines the concepts needed to write gRPC apps in C#. Tematy omówione tutaj dotyczą zarówno aplikacji gRPC opartych na procesorze C, jak i na ASP.NET Core.The topics covered here apply to both C-core-based and ASP.NET Core-based gRPC apps.

Ostrzeżenie

ASP.NET Core gRPC nie jest obecnie obsługiwana w Azure App Service lub IIS.ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. Implementacja protokołu HTTP/2 Http.Sys nie obsługuje nagłówków końcowych odpowiedzi HTTP, na których opiera się gRPC.The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. Aby uzyskać więcej informacji, zobacz ten problemw serwisie GitHub.For more information, see this GitHub issue.

plik PROTOproto file

gRPC używa podejścia pierwszego kontraktu do programowania interfejsu API.gRPC uses a contract-first approach to API development. Bufory protokołu (protobuf) są domyślnie używane jako język definicji interfejsu (IDL).Protocol buffers (protobuf) are used as the Interface Definition Language (IDL) by default. Plik * . proto zawiera:The *.proto file contains:

  • Definicja usługi gRPC.The definition of the gRPC service.
  • Komunikaty wysyłane między klientami a serwerami.The messages sent between clients and servers.

Aby uzyskać więcej informacji na temat składni plików protobuf, zobacz Tworzenie komunikatów protobuf dla aplikacji platformy .NET .For more information on the syntax of protobuf files, see Tworzenie komunikatów protobuf dla aplikacji platformy .NET.

Rozważmy na przykład plik Greeting. proto używany w temacie Rozpoczynanie pracy z usługą gRPC:For example, consider the greet.proto file used in Get started with gRPC service:

  • Definiuje Greeter usługę.Defines a Greeter service.
  • GreeterUsługa definiuje SayHello wywołanie.The Greeter service defines a SayHello call.
  • SayHello wysyła HelloRequest komunikat i odbiera HelloReply komunikat: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;
}

Jeśli chcesz zobaczyć Komentarze do kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym problemie z dyskusjąw witrynie GitHub.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

Dodawanie pliku. proto do # aplikacji CAdd a .proto file to a C# app

Plik * proto jest dołączany do projektu przez dodanie go do <Protobuf> grupy Items: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>

Domyślnie <Protobuf> odwołanie generuje konkretny klient i klasę bazową usługi.By default, a <Protobuf> reference generates a concrete client and a service base class. Atrybut elementu odwołania GrpcServices może służyć do ograniczania generowania elementów zawartości w języku C#.The reference element's GrpcServices attribute can be used to limit C# asset generation. Prawidłowe GrpcServices Opcje to:Valid GrpcServices options are:

  • Both (domyślnie, gdy nie istnieje)Both (default when not present)
  • Server
  • Client
  • None

Obsługa narzędzi C# dla plików. protoC# Tooling support for .proto files

Pakiet narzędzi GRPC. Tools jest wymagany do generowania zasobów C# z plików * . proto .The tooling package Grpc.Tools is required to generate the C# assets from *.proto files. Wygenerowane zasoby (pliki):The generated assets (files):

  • Są generowane w przypadku, gdy jest to wymagane, za każdym razem, gdy projekt jest skompilowany.Are generated on an as-needed basis each time the project is built.
  • Nie są dodawane do projektu ani zaewidencjonowane do kontroli źródła.Aren't added to the project or checked into source control.
  • Czy artefakt kompilacji znajduje się w katalogu obj .Are a build artifact contained in the obj directory.

Ten pakiet jest wymagany przez projekty serwera i klienta.This package is required by both the server and client projects. Grpc.AspNetCorePakietbinding zawiera odwołanie do Grpc.Tools .The Grpc.AspNetCore metapackage includes a reference to Grpc.Tools. Projekty serwera mogą Grpc.AspNetCore być dodawane przy użyciu Menedżera pakietów w programie Visual Studio lub poprzez dodanie <PackageReference> do pliku projektu: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" />

Projekty klienta należy bezpośrednio odwoływać Grpc.Tools się do innych pakietów wymaganych do korzystania z klienta gRPC.Client projects should directly reference Grpc.Tools alongside the other packages required to use the gRPC client. Pakiet narzędzi nie jest wymagany w czasie wykonywania, dlatego zależność jest oznaczona przy użyciu PrivateAssets="All" :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">

Wygenerowane elementy zawartości C#Generated C# assets

Pakiet narzędzi generuje typy C# reprezentujące komunikaty zdefiniowane w zawartych plikach * . proto .The tooling package generates the C# types representing the messages defined in the included *.proto files.

W przypadku zasobów po stronie serwera jest generowany abstrakcyjny typ podstawowy usługi.For server-side assets, an abstract service base type is generated. Typ podstawowy zawiera definicje wszystkich wywołań gRPC znajdujących się w pliku . proto .The base type contains the definitions of all the gRPC calls contained in the .proto file. Utwórz konkretną implementację usługi, która pochodzi z tego typu podstawowego i implementuje logikę dla wywołań gRPC.Create a concrete service implementation that derives from this base type and implements the logic for the gRPC calls. W przypadku greet.proto , przykładu opisanego wcześniej, GreeterBase generowany jest typ abstrakcyjny, który zawiera SayHello metodę wirtualną.For the greet.proto, the example described previously, an abstract GreeterBase type that contains a virtual SayHello method is generated. Konkretna implementacja GreeterService przesłania metodę i implementuje logikę obsługi wywołania gRPC.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
        });
    }
}

Dla zasobów po stronie klienta jest generowany konkretny typ klienta.For client-side assets, a concrete client type is generated. Wywołania gRPC w pliku . proto są tłumaczone na metody w konkretnym typie, który można wywołać.The gRPC calls in the .proto file are translated into methods on the concrete type, which can be called. W przypadku greet.proto , przykładu opisanego wcześniej, GreeterClient generowany jest konkretny typ.For the greet.proto, the example described previously, a concrete GreeterClient type is generated. Wywołaj, GreeterClient.SayHelloAsync Aby zainicjować wywołanie gRPC na serwerze.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();
}

Domyślnie zasoby serwera i klienta są generowane dla każdego pliku * . proto , który znajduje się w <Protobuf> grupie elementów.By default, server and client assets are generated for each *.proto file included in the <Protobuf> item group. Aby upewnić się, że tylko zasoby serwera są generowane w projekcie serwera, GrpcServices atrybut jest ustawiany na Server .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>

Podobnie atrybut jest ustawiany na Client w projektach klientów.Similarly, the attribute is set to Client in client projects.

Dodatkowe zasobyAdditional resources