Code-first gRPC usług i klientów z platformą .NET

Przez James Newton-King i Marc Gravell

Funkcja gRPC code-first używa typów platformy .NET do definiowania kontraktów usług i komunikatów.

Code-first to dobry wybór, gdy cały system używa platformy .NET:

• Typy kontraktów usług .NET i danych mogą być współużytkowane przez serwer .NET i klientów.
• Unika konieczności definiowania kontraktów w .proto plikach i generowaniu kodu.

Funkcja Code-first nie jest zalecana w systemach wielolotowych z wieloma językami. Typy kontraktów usług i danych platformy .NET nie mogą być używane z platformami non-.NET. Aby wywołać usługę gRPC napisaną przy użyciu funkcji code-first, inne platformy muszą utworzyć kontrakt zgodny z usługą .proto .

protobuf-net.Grpc

Important

Aby uzyskać pomoc dotyczącą narzędzia protobuf-net. Grpc, odwiedź protobuf-net. Witryna internetowa Grpc lub utwórz problem w witrynie protobuf-net. Repozytorium GitHub Grpc.

protobuf-net. Grpc jest projektem społeczności i nie jest obsługiwany przez firmę Microsoft. Dodaje obsługę funkcji code-first do Grpc.AspNetCore i Grpc.Net.Client. Używa ona typów platformy .NET z adnotacjami z atrybutami, aby zdefiniować usługi i komunikaty gRPC aplikacji.

Pierwszym krokiem tworzenia usługi gRPC opartej na kodzie jest zdefiniowanie kontraktu kodu:

• Utwórz nowy projekt, który będzie współużytkowany przez serwer i klienta.
• Dodaj protobuf-net . Dokumentacja pakietu Grpc .
• Tworzenie typów kontraktów usług i danych.

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

Powyższy kod ma następujące działanie:

• Definiuje HelloRequest i HelloReply komunikaty.
• Definiuje interfejs kontraktu IGreeterService z jednoargumentową SayHelloAsync metodą gRPC.

Kontrakt usługi jest implementowany na serwerze i wywoływany z klienta.

Metody zdefiniowane na interfejsach usługi muszą być zgodne z określonymi podpisami w zależności od tego, czy są:

• Unary
• Przesyłanie strumieniowe serwera
• Przesyłanie strumieniowe klienta
• Dwukierunkowe przesyłanie strumieniowe

Aby uzyskać więcej informacji na temat definiowania kontraktów usług, zobacz protobuf-net. Dokumentacja wprowadzająca do narzędzia Grpc.

Tworzenie usługi gRPC opartej na kodzie

Aby dodać usługę gRPC code-first do aplikacji ASP.NET Core:

• Dodaj protobuf-net . Dokumentacja pakietu Grpc.AspNetCore .

• Dodaj odwołanie do udostępnionego projektu kontraktu kodu.

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

• Utwórz nowy GreeterService.cs plik i zaimplementuj IGreeterService interfejs usługi:

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

• Program.cs Zaktualizuj plik:

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

  Powyższy wyróżniony kod aktualizuje następujące elementy:

  • AddCodeFirstGrpc rejestruje usługi, które włączają funkcję code-first.
  • MapGrpcService<GreeterService> dodaje punkt końcowy usługi code-first.

Usługi gRPC zaimplementowane za pomocą kodu i .proto pliki mogą współistnieć w tej samej aplikacji. Wszystkie usługi gRPC używają konfiguracji usługi gRPC.

Tworzenie klienta gRPC opartego na kodzie

Klient gRPC korzystający z kodu używa kontraktu usługi do wywoływania usług gRPC.

• W pliku klienta .csproj gRPC:

  • Dodaj protobuf-net . Dokumentacja pakietu Grpc .
  • Dodaj odwołanie do pakietu Grpc.Net.Client .
  • Dodaj odwołanie do udostępnionego projektu kontraktu kodu.

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

• Aktualizowanie klienta 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();
      }
  }
  
  
  

Poprzedni kod klienta Program.cs gRPC:

• Tworzy kanał gRPC.
• Tworzy klienta typu code-first z kanału przy użyciu CreateGrpcService<IGreeterService> metody rozszerzenia.
• Wywołuje usługę gRPC za pomocą polecenia SayHelloAsync.

Klient gRPC z kodem jest tworzony na podstawie kanału. Podobnie jak zwykły klient, klient korzystający z kodu używa konfiguracji kanału.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Dodatkowe zasoby

• protobuf-net. Witryna internetowa Grpc
• protobuf-net. Repozytorium GitHub grpc