Služby gRPC s jazykem C#

Tento dokument popisuje koncepty potřebné k psaní aplikací gRPC v jazyce C#. Tato témata se týkají aplikací GRPC založených na jádrech C i ASP.NET Core.

proto file

V gRPC se při vývoji rozhraní API používá přístup založený na kontraktech. Vyrovnávací paměti protokolu (protobuf) se ve výchozím nastavení používají jako IDL (Interface Definition Language). Soubor .proto obsahuje:

• Definice služby gRPC.
• Zprávy odeslané mezi klienty a servery.

Další informace o syntaxi souborů protobuf naleznete v tématu Vytváření zpráv Protobuf pro aplikace .NET.

Představte si například soubor greet.proto použitý ve službě Začínáme se službou gRPC:

• Definuje Greeter službu.
• Služba Greeter definuje SayHello volání.
• SayHelloHelloRequest odešle zprávu a obdrží HelloReply zprávu:

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

Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.

.proto Přidání souboru do aplikace v jazyce C#

Soubor .proto je součástí projektu tak, že ho přidáte <Protobuf> do skupiny položek:

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

Ve výchozím nastavení <Protobuf> odkaz generuje konkrétního klienta a základní třídu služby. Atribut referenčního prvku lze použít k omezení generování prostředků jazyka GrpcServices C#. Platné GrpcServices možnosti jsou:

• Both (výchozí hodnota, pokud není k dispozici)
• Server
• Client
• None

Podpora nástrojů jazyka C# pro soubory .proto

K vygenerování prostředků jazyka C# ze .proto souborů se vyžaduje balíček nástrojů Grpc.Tools. Vygenerované prostředky (soubory):

• Generují se podle potřeby při každém sestavení projektu.
• Nejsou přidány do projektu ani se změnami do správy zdrojového kódu.
• Jedná se o artefakt sestavení obsažený v adresáři obj .

Tento balíček vyžaduje jak serverové, tak klientské projekty. Metapackage Grpc.AspNetCore obsahuje odkaz na Grpc.Tools. Projekty serveru můžou přidat Grpc.AspNetCore pomocí Správce balíčků v sadě Visual Studio nebo přidáním <PackageReference> souboru projektu:

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

Klientské projekty by měly přímo odkazovat Grpc.Tools společně s ostatními balíčky potřebnými k použití klienta gRPC. Balíček nástrojů se nevyžaduje za běhu, takže závislost je označená PrivateAssets="All"takto:

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

Generované prostředky jazyka C#

Balíček nástrojů generuje typy jazyka C# představující zprávy definované v zahrnutých .proto souborech.

U prostředků na straně serveru se vygeneruje abstraktní základní typ služby. Základní typ obsahuje definice všech volání gRPC obsažených .proto v souboru. Vytvořte konkrétní implementaci služby, která je odvozena od tohoto základního typu, a implementuje logiku pro volání gRPC. V příkladu greet.protopopsaném výše se vygeneruje abstraktní GreeterBase typ, který obsahuje virtuální SayHello metodu. Konkrétní implementace GreeterService přepíše metodu a implementuje logiku, která zpracovává volání 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
        });
    }
}

U prostředků na straně klienta se vygeneruje konkrétní typ klienta. Volání gRPC v .proto souboru jsou přeložena do metod konkrétního typu, které lze volat. V příkladu greet.protopopsaném výše se vygeneruje konkrétní GreeterClient typ. Volání GreeterClient.SayHelloAsync pro zahájení volání gRPC na server.

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

Ve výchozím nastavení se pro každý .proto soubor zahrnutý ve <Protobuf> skupině položek vygenerují prostředky serveru a klienta. Aby se zajistilo, že se v projektu serveru generují pouze prostředky serveru, GrpcServices je atribut nastaven na Serverhodnotu .

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

Podobně je atribut nastaven na Client v klientských projektech.

Další materiály

• Přehled gRPC v .NET
• Vytvoření serveru a klienta .NET Core gRPC v ASP.NET Core
• Služby gRPC s ASP.NET Core
• Volání služeb gRPC pomocí klienta .NET