Služby gRPC s C#

  • Článek
  • 3 min ke čtení

Tento dokument popisuje koncepty potřebné k psaní aplikací gRPC v jazyce C#. Tato témata se vztahují na aplikace gRPC založené na jádru jazyka CASP.NET Core založené na jazyce C.

Upozornění

ASP.NET Core gRPC má další požadavky pro použití s Azure App Service nebo službou IIS. Další informace o tom, kde lze použít gRPC, naleznete v tématu gRPC na platformách podporovaných .NET .

soubor proto

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

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

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

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

  • Definuje Greeter službu.
  • Služba Greeter definuje SayHello volání.
  • SayHello odešle zprávu HelloRequest a přijme 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ž angličtiny, dejte nám vědět v tomto problému diskuze na GitHubu.

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

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

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

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

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

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

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

  • Vygenerují se podle potřeby při každém vytvoření projektu.
  • Nepřidá se do projektu ani se nezadá do správy zdrojového kódu.
  • Jsou artefaktem sestavení obsaženým v adresáři obj.

Tento balíček vyžaduje serverový i klientský projekt. Grpc.AspNetCoreMetabalíček obsahuje odkaz na Grpc.Tools . Serverové projekty můžete přidat pomocí Správce balíčků v Visual Studio nebo přidáním do Grpc.AspNetCore souboru <PackageReference> projektu:

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

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

<PackageReference Include="Google.Protobuf" Version="3.18.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.39.0" />
<PackageReference Include="Grpc.Tools" Version="2.40.0">
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  <PrivateAssets>all</PrivateAssets>
</PackageReference>

Vygenerované prostředky jazyka C#

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

Pro prostředky 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. V greet.proto příkladu popsaném výše je vygenerován abstraktní typ, který obsahuje GreeterBase virtuální SayHello metodu. Konkrétní implementace GreeterService přepíše metodu a implementuje logiku zpracování 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
        });
    }
}

Pro prostředky na straně klienta se vygeneruje konkrétní typ klienta. Volání gRPC v souboru .proto se překládají na metody konkrétního typu, které lze volat. V greet.proto příkladu popsaném výše se vygeneruje GreeterClient konkrétní typ. Voláním GreeterClient.SayHelloAsync zahájíte 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ý soubor * .proto, který je součástí skupiny položek, generují <Protobuf> serverové a klientské prostředky. Aby se zajistilo, že se v projektu serveru vygenerují jenom prostředky serveru, je atribut GrpcServices nastavený na Server .

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

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

Další zdroje informací

Tento dokument popisuje koncepty potřebné k psaní aplikací gRPC v jazyce C#. Tato témata se vztahují na aplikace gRPC založené na jádru jazyka CASP.NET Core založené na jazyce C.

Upozornění

ASP.NET Core gRPC má další požadavky pro použití s Azure App Service nebo službou IIS. Další informace o tom, kde lze použít gRPC, naleznete v tématu gRPC na platformách podporovaných .NET .

soubor proto

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

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

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

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

  • Definuje Greeter službu.
  • Služba Greeter definuje SayHello volání.
  • SayHello odešle zprávu HelloRequest a přijme 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ž angličtiny, dejte nám vědět v tomto problému diskuze na GitHubu.

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

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

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

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

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

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

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

  • Vygenerují se podle potřeby při každém vytvoření projektu.
  • Nepřidá se do projektu ani se nezadá do správy zdrojového kódu.
  • Jsou artefaktem sestavení obsaženým v adresáři obj.

Tento balíček vyžaduje serverový i klientský projekt. Grpc.AspNetCoreMetabalíček obsahuje odkaz na Grpc.Tools . Serverové projekty můžete přidat pomocí Správce balíčků v Visual Studio nebo přidáním do Grpc.AspNetCore souboru <PackageReference> projektu:

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

Klientské projekty by měly přímo Grpc.Tools odkazovat na ostatní balíčky potřebné k použití klienta gRPC. Balíček nástrojů se za běhu nevyžaduje, takže závislost je označena pomocí 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">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

Vygenerované prostředky jazyka C#

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

Pro prostředky 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. V greet.proto příkladu popsaném výše je vygenerován abstraktní typ, který obsahuje GreeterBase virtuální SayHello metodu. Konkrétní implementace GreeterService přepíše metodu a implementuje logiku zpracování 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
        });
    }
}

Pro prostředky na straně klienta se vygeneruje konkrétní typ klienta. Volání gRPC v souboru .proto se překládají na metody konkrétního typu, které lze volat. V greet.proto příkladu popsaném výše se vygeneruje GreeterClient konkrétní typ. Voláním GreeterClient.SayHelloAsync zahájíte 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ý soubor * .proto, který je součástí skupiny položek, generují <Protobuf> serverové a klientské prostředky. Aby se zajistilo, že se v projektu serveru vygenerují jenom prostředky serveru, je atribut GrpcServices nastavený na Server .

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

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

Další materiály