Udostępnij za pośrednictwem


Usługi gRPC w środowisku C#

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy (Zasady obsługi platformy .NET Core). Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

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. protokołu (protobuf) są domyślnie używane jako język IDL (Interface Definition Language). 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 .
  • SayHelloHelloRequest wysyła 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;
}

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

.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 może służyć do ograniczania generowania GrpcServices zasobów języka 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żer pakietów w programie 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ć Grpc.Tools się do 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.protoopisanym wcześniej jest abstrakcyjny GreeterBase typ, który zawiera metodę wirtualną SayHello . Konkretna implementacja GreeterService zastępuje metodę i implementuje logikę obsługując wywołanie 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 greet.protoopisanym wcześniej jest generowany konkretny GreeterClient typ. 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 .proto pliku uwzględnionego <Protobuf> w grupie elementów. Aby upewnić się, że tylko zasoby serwera są generowane w projekcie serwera, GrpcServices atrybut jest ustawiony na Serverwartość .

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

Podobnie atrybut jest ustawiany na Client wartość w projektach klienckich.

Dodatkowe zasoby

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. protokołu (protobuf) są domyślnie używane jako język IDL (Interface Definition Language). 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 .
  • SayHelloHelloRequest wysyła 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;
}

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

.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 może służyć do ograniczania generowania GrpcServices zasobów języka 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żer pakietów w programie Visual Studio lub dodając element <PackageReference> do pliku projektu:

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

Projekty klienckie powinny bezpośrednio odwoływać Grpc.Tools się do 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.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>

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.protoopisanym wcześniej jest abstrakcyjny GreeterBase typ, który zawiera metodę wirtualną SayHello . Konkretna implementacja GreeterService zastępuje metodę i implementuje logikę obsługując wywołanie 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 greet.protoopisanym wcześniej jest generowany konkretny GreeterClient typ. Wywołanie metody GreeterClient.SayHelloAsync w celu zainicjowania wywołania gRPC na serwerze.

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 .proto pliku uwzględnionego <Protobuf> w grupie elementów. Aby upewnić się, że tylko zasoby serwera są generowane w projekcie serwera, GrpcServices atrybut jest ustawiony na Serverwartość .

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

Podobnie atrybut jest ustawiany na Client wartość w projektach klienckich.

Dodatkowe zasoby