Servizi e client gRPC code-first con .NET

Di James Newton-King e Marc Gravell

Code-first gRPC usa tipi .NET per definire contratti di servizio e messaggi.

Code-first è una scelta ottimale quando un intero sistema usa .NET:

• I tipi di contratto dati e del servizio .NET possono essere condivisi tra il server .NET e i client.
• Evita la necessità di definire contratti nei file e nella .proto generazione di codice.

Code-first non è consigliato nei sistemi poliglotta con più linguaggi. I tipi di contratto dati e del servizio .NET non possono essere usati con le piattaforme non-.NET. Per chiamare un servizio gRPC scritto usando code-first, le altre piattaforme devono creare un .proto contratto corrispondente al servizio.

protobuf-net.Grpc

Important

Per assistenza con protobuf-net. Grpc, visita il protobuf-net. Sito Web Grpc o creare un problema in protobuf-net. Repository GitHub grpc.

protobuf-net. Grpc è un progetto della community e non è supportato da Microsoft. Aggiunge il supporto code-first a Grpc.AspNetCore e Grpc.Net.Client. Usa tipi .NET annotati con attributi per definire i servizi e i messaggi gRPC di un'app.

Il primo passaggio per creare un servizio gRPC code-first consiste nel definire il contratto di codice:

• Creare un nuovo progetto che verrà condiviso dal server e dal client.
• Aggiungere un protobuf-net. Informazioni di riferimento sul pacchetto Grpc .
• Creare tipi di contratto dati e di servizio.

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

Il codice precedente:

• Definisce HelloRequest e HelloReply i messaggi.
• Definisce l'interfaccia IGreeterService del contratto con il metodo gRPC unario SayHelloAsync .

Il contratto di servizio viene implementato nel server e chiamato dal client.

I metodi definiti nelle interfacce del servizio devono corrispondere a determinate firme a seconda che siano:

• Unary
• Streaming del server
• Streaming client
• Streaming bidirezionale

Per altre informazioni sulla definizione dei contratti di servizio, vedere protobuf-net . Documentazione introduttiva di Grpc.

Creare un servizio gRPC code-first

Per aggiungere il servizio code-first gRPC a un'app ASP.NET Core:

• Aggiungere un protobuf-net. Informazioni di riferimento sul pacchetto Grpc.AspNetCore .

• Aggiungere un riferimento al progetto di contratto di codice condiviso.

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

• Creare un nuovo GreeterService.cs file e implementare l'interfaccia del IGreeterService servizio:

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

• Aggiornare il file 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();
  

  Il codice evidenziato precedente aggiorna quanto segue:

  • AddCodeFirstGrpc registra i servizi che abilitano code-first.
  • MapGrpcService<GreeterService> aggiunge l'endpoint di servizio code-first.

I servizi gRPC implementati con code-first e .proto file possono coesistere nella stessa app. Tutti i servizi gRPC usano la configurazione del servizio gRPC.

Creare un client gRPC code-first

Un client gRPC code-first usa il contratto di servizio per chiamare i servizi gRPC.

• Nel file client .csproj gRPC:

  • Aggiungere un protobuf-net. Informazioni di riferimento sul pacchetto Grpc .
  • Aggiungere un riferimento al pacchetto Grpc.Net.Client .
  • Aggiungere un riferimento al progetto di contratto di codice condiviso.

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

• Aggiornare il client program.cs

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

Codice client Program.cs gRPC precedente:

• Crea un canale gRPC.
• Crea un client code-first dal canale con il CreateGrpcService<IGreeterService> metodo di estensione.
• Chiama il servizio gRPC con SayHelloAsync.

Un client gRPC code-first viene creato da un canale. Proprio come un normale client, un client code-first usa la configurazione del canale.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Risorse aggiuntive

• protobuf-net. Sito Web Grpc
• protobuf-net. Repository GitHub grpc