Služby gRPC s jazykem C#

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

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

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

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.

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

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