Code-First-gRPC-Dienste und -Clients mit .NET

Von James Newton-King und Marc Gravell

Code-First-gRPC verwendet .NET-Typen, um Dienst- und Nachrichtenverträge zu definieren.

Code-First ist eine gute Wahl, wenn ein gesamtes System .NET verwendet:

• .NET-Dienst- und -Datenvertragstypen können von .NET-Server und -Clients gemeinsam genutzt werden.
• Verhindert, dass Verträge in .proto-Dateien und Codegenerierung definiert werden müssen.

Code-First sollte nicht in mehrsprachigen Systemen verwendet werden. .NET-Dienst- und -Datenvertragstypen können nicht mit Nicht-.NET-Plattformen verwendet werden. Um einen mit Code-First geschriebenen gRPC-Dienst aufzurufen, müssen andere Plattformen einen .proto-Vertrag erstellen, der mit dem Dienst übereinstimmt.

protobuf-net.Grpc

Important

Hilfe zu protobuf-net.Grpc finden Sie auf der protobuf-net.Grpc-Website, oder erstellen Sie ein Problem im protobuf-net.Grpc-GitHub-Repository.

protobuf-net.Grpc ist ein Communityprojekt und wird von Microsoft nicht unterstützt. Die Code-First-Unterstützung wird Grpc.AspNetCore und Grpc.Net.Client hinzugefügt. Es werden mit Attributen versehene .NET-Typen verwendet, um die gRPC-Dienste und -Nachrichten einer App zu definieren.

Der erste Schritt beim Erstellen eines Code-First-gRPC-Diensts ist die Definition des Codevertrags:

• Erstellen Sie ein neues Projekt, das von Server und Client gemeinsam genutzt wird.
• Fügen Sie einen protobuf-net.Grpc-Paketverweis hinzu.
• Erstellen Sie Dienst- und Datenvertragstypen.

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

Der vorangehende Code:

• Definiert HelloRequest- und HelloReply-Nachrichten.
• Definiert die IGreeterService-Vertragsschnittstelle mit der unären SayHelloAsync-gRPC-Methode.

Der Dienstvertrag wird auf dem Server implementiert und vom Client aufgerufen.

Für Dienstschnittstellen definierte Methoden müssen abhängig von ihrem Typ mit bestimmten Signaturen übereinstimmen:

• Unary
• Serverstreaming
• Clientstreaming
• Bidirektionales Streaming

Weitere Informationen zum Definieren von Dienstverträgen finden Sie in der Dokumentation zu den ersten Schritten mit protobuf-net.GrpC.

Erstellen eines Code-First-gRPC-Diensts

So fügen Sie einen gRPC-Code-First-Dienst einer ASP.NET Core-App hinzu:

• Fügen Sie einen protobuf-net.Grpc.AspNetCore-Paketverweis hinzu.

• Fügen Sie dem freigegebenen Code-Vertragsprojekt einen Verweis hinzu.

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

• Erstellen Sie eine neue GreeterService.cs-Datei, und implementieren Sie die IGreeterService-Dienstschnittstelle:

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

• Aktualisieren Sie die Datei 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();
  

  Der oben hervorgehobene Code aktualisiert Folgendes:

  • AddCodeFirstGrpc registriert Dienste, die Code-First aktivieren.
  • MapGrpcService<GreeterService> fügt den Code-First-Dienstendpunkt hinzu.

Mit Code-First und .proto-Dateien implementierte gRPC-Dienste können in der gleichen App nebeneinander vorhanden sein. Für alle gRPC-Dienste wird die gRPC-Dienstkonfiguration verwendet.

Erstellen eines Code-First-gRPC-Clients

Ein Code-First-gRPC-Client verwendet den Dienstvertrag, um gRPC-Dienste aufzurufen.

• In der Datei .csproj des gRPC-Clients:

  • Fügen Sie einen protobuf-net.Grpc-Paketverweis hinzu.
  • Fügen Sie einen Grpc.Net.Client-Paketverweis hinzu.
  • Fügen Sie dem freigegebenen Code-Vertragsprojekt einen Verweis hinzu.

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

• Aktualisieren Sie die Datei program.cs des Clients.

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

Der Code in Program.cs des gRPC-Clients:

• Erstellt einen gRPC-Kanal.
• Erstellt einen Code-First-Client aus dem Kanal mit der CreateGrpcService<IGreeterService>-Erweiterungsmethode.
• Ruft den gRPC-Dienst mit SayHelloAsync auf.

Ein Code-First-gRPC-Client wird aus einem Kanal erstellt. Genau wie ein regulärer Client verwendet ein Code-First-Client seine Kanalkonfiguration.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Weitere Ressourcen

• protobuf-net. Grpc-Website
• protobuf-net.GrpC-GitHub-Repository