Services gRPC avec C#
Note
Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 de cet article.
Avertissement
Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 de cet article.
Important
Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.
Pour la version actuelle, consultez la version .NET 9 de cet article.
Ce document décrit les concepts nécessaires pour écrire des applications gRPC en C#. Les sujets abordés ici s’appliquent aux applications gRPC basées sur C-core et ASP.NET Core.
gRPC utilise une approche de type « Contrat en premier » pour le développement d’API. Les mémoires tampons de protocole (protobuf) sont utilisées comme langage de définition d’interface (IDL) par défaut. Le fichier .proto
contient :
- Définition du service gRPC.
- Messages envoyés entre les clients et les serveurs.
Pour plus d’informations sur la syntaxe des fichiers protobuf, consultez Créer des messages Protobuf pour les applications .NET.
Par exemple, considérez le fichier greet.proto utilisé dans Prise en main du service gRPC :
- Définit un service
Greeter
. - Le service
Greeter
définit un appelSayHello
. SayHello
envoie un messageHelloRequest
et reçoit un messageHelloReply
:
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;
}
Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.
Le fichier .proto
est inclus dans un projet en l’ajoutant au groupe d’éléments <Protobuf>
:
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
Par défaut, une référence <Protobuf>
génère un client concret et une classe de base de service. L’attribut GrpcServices
de l’élément de référence peut être utilisé pour limiter la génération de ressources C#. Les options GrpcServices
valides sont les suivantes :
Both
(valeur par défaut lorsqu’elle n’est pas présente)Server
Client
None
Le package d’outils Grpc.Tools est requis pour générer les ressources C# à partir de fichiers .proto
. Les ressources générées (fichiers) :
- Sont générées en fonction des besoins chaque fois que le projet est généré.
- Ne sont pas ajoutées au projet ou archivées dans le contrôle de code source.
- Sont un artefact de build contenu dans le répertoire obj.
Ce package est requis par les projets serveur et client. Le métapackage Grpc.AspNetCore
inclut une référence à Grpc.Tools
. Les projets serveur peuvent ajouter Grpc.AspNetCore
à l’aide du gestionnaire de package dans Visual Studio ou en ajoutant un <PackageReference>
au fichier projet :
<PackageReference Include="Grpc.AspNetCore" Version="2.32.0" />
Les projets client doivent faire directement référence à Grpc.Tools
avec les autres packages requis pour utiliser le client gRPC. Le package d’outils n’est pas nécessaire lors de l’exécution. La dépendance est donc marquée avec PrivateAssets="All"
:
<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>
Le package d’outils génère les types C# représentant les messages définis dans les fichiers .proto
inclus.
Pour les ressources côté serveur, un type de base de service abstrait est généré. Le type de base contient les définitions de tous les appels gRPC contenus dans le fichier .proto
. Créez une implémentation de service concrète qui dérive de ce type de base et implémente la logique pour les appels gRPC. Pour greet.proto
, l’exemple décrit précédemment, un type GreeterBase
abstrait qui contient une méthode SayHello
virtuelle est généré. Une implémentation concrète GreeterService
remplace la méthode et implémente la logique qui gère l’appel 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
});
}
}
Pour les ressources côté client, un type de client concret est généré. Les appels gRPC dans le fichier .proto
sont traduits en méthodes sur le type concret, qui peuvent être appelées. Pour greet.proto
, l’exemple décrit précédemment, un type GreeterClient
concret est généré. Appelez GreeterClient.SayHelloAsync
pour lancer un appel gRPC au serveur.
// 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();
Par défaut, les ressources serveur et client sont générées pour chaque fichier .proto
inclus dans le groupe d’éléments <Protobuf>
. Pour garantir que seules les ressources serveur sont générées dans un projet de serveur, l’attribut GrpcServices
est défini sur Server
.
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
De même, l’attribut est défini sur Client
dans les projets clients.
Ce document décrit les concepts nécessaires pour écrire des applications gRPC en C#. Les sujets abordés ici s’appliquent aux applications gRPC basées sur C-core et ASP.NET Core.
gRPC utilise une approche de type « Contrat en premier » pour le développement d’API. Les mémoires tampons de protocole (protobuf) sont utilisées comme langage de définition d’interface (IDL) par défaut. Le fichier .proto
contient :
- Définition du service gRPC.
- Messages envoyés entre les clients et les serveurs.
Pour plus d’informations sur la syntaxe des fichiers protobuf, consultez Créer des messages Protobuf pour les applications .NET.
Par exemple, considérez le fichier greet.proto utilisé dans Prise en main du service gRPC :
- Définit un service
Greeter
. - Le service
Greeter
définit un appelSayHello
. SayHello
envoie un messageHelloRequest
et reçoit un messageHelloReply
:
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;
}
Si vous souhaitez voir les commentaires de code traduits dans une langue autre que l’anglais, dites-le nous dans cette discussion GitHub.
Le fichier .proto
est inclus dans un projet en l’ajoutant au groupe d’éléments <Protobuf>
:
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
Par défaut, une référence <Protobuf>
génère un client concret et une classe de base de service. L’attribut GrpcServices
de l’élément de référence peut être utilisé pour limiter la génération de ressources C#. Les options GrpcServices
valides sont les suivantes :
Both
(valeur par défaut lorsqu’elle n’est pas présente)Server
Client
None
Le package d’outils Grpc.Tools est requis pour générer les ressources C# à partir de fichiers .proto
. Les ressources générées (fichiers) :
- Sont générées en fonction des besoins chaque fois que le projet est généré.
- Ne sont pas ajoutées au projet ou archivées dans le contrôle de code source.
- Sont un artefact de build contenu dans le répertoire obj.
Ce package est requis par les projets serveur et client. Le métapackage Grpc.AspNetCore
inclut une référence à Grpc.Tools
. Les projets serveur peuvent ajouter Grpc.AspNetCore
à l’aide du gestionnaire de package dans Visual Studio ou en ajoutant un <PackageReference>
au fichier projet :
<PackageReference Include="Grpc.AspNetCore" Version="2.28.0" />
Les projets client doivent faire directement référence à Grpc.Tools
avec les autres packages requis pour utiliser le client gRPC. Le package d’outils n’est pas nécessaire lors de l’exécution. La dépendance est donc marquée avec PrivateAssets="All"
:
<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>
Le package d’outils génère les types C# représentant les messages définis dans les fichiers .proto
inclus.
Pour les ressources côté serveur, un type de base de service abstrait est généré. Le type de base contient les définitions de tous les appels gRPC contenus dans le fichier .proto
. Créez une implémentation de service concrète qui dérive de ce type de base et implémente la logique pour les appels gRPC. Pour greet.proto
, l’exemple décrit précédemment, un type GreeterBase
abstrait qui contient une méthode SayHello
virtuelle est généré. Une implémentation concrète GreeterService
remplace la méthode et implémente la logique qui gère l’appel 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
});
}
}
Pour les ressources côté client, un type de client concret est généré. Les appels gRPC dans le fichier .proto
sont traduits en méthodes sur le type concret, qui peuvent être appelées. Pour greet.proto
, l’exemple décrit précédemment, un type GreeterClient
concret est généré. Appelez GreeterClient.SayHelloAsync
pour lancer un appel gRPC au serveur.
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();
}
Par défaut, les ressources serveur et client sont générées pour chaque fichier .proto
inclus dans le groupe d’éléments <Protobuf>
. Pour garantir que seules les ressources serveur sont générées dans un projet de serveur, l’attribut GrpcServices
est défini sur Server
.
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
De même, l’attribut est défini sur Client
dans les projets clients.
Commentaires sur ASP.NET Core
ASP.NET Core est un projet open source. Sélectionnez un lien pour fournir des commentaires :