Služby gRPC s jazykem C#

Tento článek obsahuje přehled konceptů potřebných k psaní aplikací gRPC v jazyce C#. Uvedené informace platí pro aplikace gRPC založené na C i ASP.NET Core.

Kontrola souboru .proto

V gRPC se při vývoji rozhraní API používá přístup založený na kontraktech. Protocol Buffers (protobuf) se ve výchozím nastavení používají jako Interface Definition Language (IDL). 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.

Zvažte soubor greet.proto použitý v kurzu Vytvoření klienta a serveru gRPC v ASP.NET Core:

• Soubor definuje Greeter službu.
• Služba Greeter definuje SayHello volání.
• Volání SayHello odešle HelloRequest zprávu a obdrží HelloReply zprávu.

Soubor obsahuje následující kód:

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

Přidání souboru .proto 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 prvku GrpcServices lze použít k omezení generování prostředků v 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

Balíček nástrojů Grpc.Tools je nutný k vygenerování prostředků jazyka C# ze souborů .proto .

Vygenerované prostředky (soubory) mají následující charakteristiky:

• Při každém sestavení projektu se vygenerují podle potřeby.
• Nepřidávají se do projektu ani se nezapisují do správy verzí.
• Jedná se o artefakt sestavení, který se nachází v adresáři obj.

Serverové i klientské projekty vyžadují tento balíček. Metapackage Grpc.AspNetCore obsahuje odkaz na Grpc.Tools. Serverové projekty mohou přidat Grpc.AspNetCore pomocí Správce balíčků v Visual Studio nebo přidáním <PackageReference> do 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" nastavením:

<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é soubory jazyka C#

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

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 v souboru .proto . Vytvořte konkrétní implementaci služby, která je odvozena od tohoto základního typu, a implementuje logiku pro volání gRPC. Pro soubor greet.proto použitý v předchozím příkladu 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 souboru .proto jsou přeložena do metod konkrétního typu, které lze volat. Pro soubor greet.proto použitý v předchozím příkladu 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í jsou prostředky serveru a klienta generovány pro každý soubor .proto zahrnutý ve <Protobuf> skupině prvků. Aby se v projektu serveru generovaly pouze prostředky serveru, je atribut GrpcServices nastaven na hodnotu Server.

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

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

Související obsah

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