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
definujeSayHello
volání. SayHello
HelloRequest
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.proto
popsané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.proto
popsané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 Server
hodnotu .
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
Podobně je atribut nastaven na Client
v klientských projektech.
Další prostředky
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
definujeSayHello
volání. SayHello
HelloRequest
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.proto
popsané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.proto
popsané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 Server
hodnotu .
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
Podobně je atribut nastaven na Client
v klientských projektech.
Další prostředky
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro