Clients et services gRPC code-first avec .NET

Par James Newton-King et Marc Gravell

gRPC code-first utilise des types .NET pour définir des contrats de message et de service.

Code-first est un choix judicieux quand un système entier utilise .NET :

• Les types de contrats de données et de service .NET peuvent être partagés entre le serveur et les clients .NET.
• Évite d’avoir à définir des contrats dans les fichiers .proto et la génération de code.

Code-first n’est pas recommandé dans les systèmes polyglottes à plusieurs langues. Les types de contrats de données et de service .NET ne peuvent pas être utilisés avec des plateformes non-.NET. Pour appeler un service gRPC écrit à l’aide de code-first, d’autres plateformes doivent créer un contrat .proto qui correspond au service.

protobuf-net.Grpc

Important

Pour obtenir de l’aide sur protobuf-net.Grpc, visitez le site web protobuf-net.Grpc ou créez un problème sur le dépôt GitHub protobuf-net.Grpc.

protobuf-net.Grpc est un projet communautaire qui n’est pas pris en charge par Microsoft. Il ajoute la prise en charge de code-first à Grpc.AspNetCore et Grpc.Net.Client. Il utilise des types .NET annotés avec des attributs pour définir les services et les messages gRPC d’une application.

La première étape de la création d’un service gRPC code-first consiste à définir le contrat de code :

• Créez un nouveau projet qui sera partagé par le serveur et le client.
• Ajoutez une référence de package protobuf-net.Grpc.
• Créez des types de contrats de données et de service.

using ProtoBuf.Grpc;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.Threading.Tasks;

namespace Shared.Contracts;

[DataContract]
public class HelloReply
{
    [DataMember(Order = 1)]
    public string Message { get; set; }
}

[DataContract]
public class HelloRequest
{
    [DataMember(Order = 1)]
    public string Name { get; set; }
}

[ServiceContract]
public interface IGreeterService
{
    [OperationContract]
    Task<HelloReply> SayHelloAsync(HelloRequest request,
        CallContext context = default);
}

Le code précédent :

• Définit les messages HelloRequest et HelloReply.
• Définit l’interface de contrat IGreeterService avec la méthode gRPC SayHelloAsync unaire.

Le contrat de service est implémenté sur le serveur et appelé à partir du client.

Les méthodes définies sur les interfaces de service doivent correspondre à certaines signatures selon qu’elles sont :

• Unaire
• Diffusion en continu du serveur
• Diffusion en continu du client
• Diffusion en continu bidirectionnelle

Pour plus d’informations sur la définition des contrats de service, consultez la documentation pour bien démarrer avec protobuf-net.Grpc.

Créer un service gRPC code-first

Pour ajouter le service gRPC code-first à une application ASP.NET Core :

• Ajoutez une référence de package protobuf-net.Grpc.AspNetCore.

• Ajoutez une référence au projet code-contract partagé.

  <Project Sdk="Microsoft.NET.Sdk.Web">
  
    <PropertyGroup>
      <TargetFramework>net6.0</TargetFramework>
      <Nullable>enable</Nullable>
      <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="protobuf-net.Grpc.AspNetCore" Version="1.0.152" />
    </ItemGroup>
  
    <ItemGroup>
        <ProjectReference Include="..\Shared\Shared.Contracts.csproj" />
    </ItemGroup>
  
  </Project>
  

• Créez un nouveau fichier GreeterService.cs et implémentez l’interface de service IGreeterService :

  using Shared.Contracts;
  using ProtoBuf.Grpc;
  
  public class GreeterService : IGreeterService
  {
      public Task<HelloReply> SayHelloAsync(HelloRequest request, CallContext context = default)
      {
          return Task.FromResult(
                  new HelloReply
                  {
                      Message = $"Hello {request.Name}"
                  });
      }
  }
  

• Mettez à jour le fichier Program.cs :

  using ProtoBuf.Grpc.Server;
  
  var builder = WebApplication.CreateBuilder(args);
  
  // Additional configuration is required to successfully run gRPC on macOS.
  // For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682
  
  // Add services to the container.
  builder.Services.AddCodeFirstGrpc();
  
  var app = builder.Build();
  
  // Configure the HTTP request pipeline.
  app.MapGrpcService<GreeterService>();
  app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");
  
  app.Run();
  

  Le code mis en surbrillance précédent met à jour les éléments suivants :

  • AddCodeFirstGrpc inscrit les services qui activent code-first.
  • MapGrpcService<GreeterService> ajoute le point de terminaison de service code-first.

Les services gRPC implémentés avec les fichiers code-first et .proto peuvent coexister dans la même application. Tous les services gRPC utilisent la configuration du service gRPC.

Créer un client gRPC code-first

Un client gRPC code-first utilise le contrat de service pour appeler les services gRPC.

• Dans le fichier .csproj du client gRPC :

  • Ajoutez une référence de package protobuf-net.Grpc.
  • Ajoutez une référence de package Grpc.Net.Client.
  • Ajoutez une référence au projet code-contract partagé.

  <Project Sdk="Microsoft.NET.Sdk">
  
    <PropertyGroup>
      <OutputType>Exe</OutputType>
      <TargetFramework>net6.0</TargetFramework>
      <ImplicitUsings>enable</ImplicitUsings>
      <Nullable>enable</Nullable>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="Grpc.Net.Client" Version="2.52.0" />
      <PackageReference Include="protobuf-net.Grpc" Version="1.0.152" />
    </ItemGroup>
      
    <ItemGroup>
      <ProjectReference Include="..\Shared\Shared.Contracts.csproj" />
    </ItemGroup>
  
  </Project>
  

• Mettre à jour le code program.cs client

  // See https://aka.ms/new-console-template for more information
  using Grpc.Net.Client;
  using ProtoBuf.Grpc.Client;
  using Shared.Contracts;
  
  namespace GrpcGreeterClient;
  
  internal class Program
  {
      private static async Task Main(string[] args)
      {
          using var channel = GrpcChannel.ForAddress("https://localhost:7184");
          var client = channel.CreateGrpcService<IGreeterService>();
  
          var reply = await client.SayHelloAsync(
              new HelloRequest { Name = "GreeterClient" });
  
          Console.WriteLine($"Greeting: {reply.Message}");
          Console.WriteLine("Press any key to exit...");
          Console.ReadKey();
      }
  }
  
  
  

Le code Program.cs client gRPC précédent :

• Crée un canal gRPC.
• Crée un client code-first à partir de ce canal avec la méthode d’extension CreateGrpcService<IGreeterService>.
• Appelle le service gRPC avec SayHelloAsync.

Un client gRPC code-first est créé à partir d’un canal. Tout comme un client standard, un client code-first utilise sa configuration de canal.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Ressources supplémentaires

• Site web protobuf-net.Grpc
• Référentiel GitHub protobuf-net.Grpc