127 lines
4.0 KiB
Markdown
127 lines
4.0 KiB
Markdown
---
|
|
title: Introduction to gRPC on .NET Core
|
|
author: juntaoluo
|
|
description: Learn about gRPC services with Kestrel server and the ASP.NET Core stack.
|
|
monikerRange: '>= aspnetcore-3.0'
|
|
ms.author: johluo
|
|
ms.date: 09/20/2019
|
|
uid: grpc/index
|
|
---
|
|
# Introduction to gRPC on .NET Core
|
|
|
|
By [John Luo](https://github.com/juntaoluo) and [James Newton-King](https://twitter.com/jamesnk)
|
|
|
|
[gRPC](https://grpc.io/docs/guides/) is a language agnostic, high-performance Remote Procedure Call (RPC) framework.
|
|
|
|
The main benefits of gRPC are:
|
|
* Modern, high-performance, lightweight RPC framework.
|
|
* Contract-first API development, using Protocol Buffers by default, allowing for language agnostic implementations.
|
|
* Tooling available for many languages to generate strongly-typed servers and clients.
|
|
* Supports client, server, and bi-directional streaming calls.
|
|
* Reduced network usage with Protobuf binary serialization.
|
|
|
|
These benefits make gRPC ideal for:
|
|
* Lightweight microservices where efficiency is critical.
|
|
* Polyglot systems where multiple languages are required for development.
|
|
* Point-to-point real-time services that need to handle streaming requests or responses.
|
|
|
|
## C# Tooling support for .proto files
|
|
|
|
gRPC uses a contract-first approach to API development. Services and messages are defined in *\*.proto* files:
|
|
|
|
```protobuf
|
|
syntax = "proto3";
|
|
|
|
service Greeter {
|
|
rpc SayHello (HelloRequest) returns (HelloReply);
|
|
}
|
|
|
|
message HelloRequest {
|
|
string name = 1;
|
|
}
|
|
|
|
message HelloReply {
|
|
string message = 1;
|
|
}
|
|
```
|
|
|
|
.NET types for services, clients and messages are automatically generated by including *\*.proto* files in a project:
|
|
|
|
* Add a package reference to [Grpc.Tools](https://www.nuget.org/packages/Grpc.Tools/) package.
|
|
* Add *\*.proto* files to the `<Protobuf>` item group.
|
|
|
|
```xml
|
|
<ItemGroup>
|
|
<Protobuf Include="Protos\greet.proto" />
|
|
</ItemGroup>
|
|
```
|
|
|
|
For more information on gRPC tooling support, see <xref:grpc/basics>.
|
|
|
|
## gRPC services on ASP.NET Core
|
|
|
|
gRPC services can be hosted on ASP.NET Core. Services have full integration with popular ASP.NET Core features such as logging, dependency injection (DI), authentication and authorization.
|
|
|
|
The gRPC service project template provides a starter service:
|
|
|
|
```csharp
|
|
public class GreeterService : Greeter.GreeterBase
|
|
{
|
|
private readonly ILogger<GreeterService> _logger;
|
|
|
|
public GreeterService(ILogger<GreeterService> logger)
|
|
{
|
|
_logger = logger;
|
|
}
|
|
|
|
public override Task<HelloReply> SayHello(HelloRequest request,
|
|
ServerCallContext context)
|
|
{
|
|
_logger.LogInformation("Saying hello to {Name}", request.Name);
|
|
return Task.FromResult(new HelloReply
|
|
{
|
|
Message = "Hello " + request.Name
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
`GreeterService` inherits from the `GreeterBase` type, which is generated from the `Greeter` service in the *\*.proto* file. The service is made accessible to clients in *Startup.cs*:
|
|
|
|
```csharp
|
|
app.UseEndpoints(endpoints =>
|
|
{
|
|
endpoints.MapGrpcService<GreeterService>();
|
|
});
|
|
```
|
|
|
|
To learn more about gRPC services on ASP.NET Core, see <xref:grpc/aspnetcore>.
|
|
|
|
## Call gRPC services with a .NET client
|
|
|
|
gRPC clients are concrete client types that are [generated from *\*.proto* files](xref:grpc/basics#generated-c-assets). The concrete gRPC client has methods that translate to the gRPC service in the *\*.proto* file.
|
|
|
|
```csharp
|
|
var channel = GrpcChannel.ForAddress("https://localhost:5001");
|
|
var client = new Greeter.GreeterClient(channel);
|
|
|
|
var response = await client.SayHello(
|
|
new HelloRequest { Name = "World" });
|
|
|
|
Console.WriteLine(response.Message);
|
|
```
|
|
|
|
A gRPC client is created using a channel, which represents a long-lived connection to a gRPC service. A channel can be created using `GrpcChannel.ForAddress`.
|
|
|
|
For more information on creating clients, and calling different service methods, see <xref:grpc/client>.
|
|
|
|
[!INCLUDE[](~/includes/gRPCazure.md)]
|
|
|
|
## Additional resources
|
|
|
|
* <xref:grpc/basics>
|
|
* <xref:grpc/aspnetcore>
|
|
* <xref:grpc/client>
|
|
* <xref:grpc/clientfactory>
|
|
* <xref:tutorials/grpc/grpc-start>
|