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
Ważne
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:
- Definiuje
HelloRequest
iHelloReply
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ą:
- Jednoargumentowy
- 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 zaimplementujIGreeterService
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>
<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
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
Ważne
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.
[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:
- Definiuje
HelloRequest
iHelloReply
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ług muszą być zgodne z określonymi sygnaturami w zależności od tego, czy są jednoargumentowe, przesyłanie strumieniowe serwera, przesyłanie strumieniowe klienta lub 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.
Utwórz nowy GreeterService.cs
plik i zaimplementuj IGreeterService
interfejs usługi:
public class GreeterService : IGreeterService
{
public Task<HelloReply> SayHelloAsync(HelloRequest request, CallContext context = default)
{
return Task.FromResult(
new HelloReply
{
Message = $"Hello {request.Name}"
});
}
}
Startup.cs
Zaktualizuj plik:
public void ConfigureServices(IServiceCollection services)
{
services.AddCodeFirstGrpc();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapGrpcService<GreeterService>();
});
}
Powyższy kod:
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. Aby wywołać usługę gRPC przy użyciu klienta opartego na kodzie:
- Dodaj protobuf-net . Dokumentacja pakietu Grpc .
- Dodaj odwołanie do udostępnionego projektu kontraktu kodu.
- Dodaj odwołanie do pakietu Grpc.Net.Client .
using var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = channel.CreateGrpcService<IGreeterService>();
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine($"Greeting: {reply.Message}");
Powyższy kod:
- 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
Opinia
https://aka.ms/ContentUserFeedback.
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź:Prześlij i wyświetl opinię dla