4.1 KiB
| title | author | description | monikerRange | ms.author | ms.date | uid |
|---|---|---|---|---|---|---|
| gRPC services with C# | juntaoluo | Learn the basic concepts when writing gRPC services with C#. | >= aspnetcore-3.0 | johluo | 03/08/2019 | grpc/basics |
gRPC services with C#
This document outlines the basic concepts needed to write gRPC apps in C#. The topics covered here apply to both C-core based and ASP.NET Core based gRPC apps.
proto file
gRPC uses a contract-first approach to API development. Protocol buffers (protobuf) are used as the Interface Design Language (IDL) by default. The .proto file contains:
- The definition of the gRPC service.
- The messages sent between clients and servers.
For more information on the syntax of protobuf files, see the official documentation (protobuf).
For example, consider the greet.proto file used in Get started with gRPC service:
- Defines a
Greeterservice. - The
Greeterservice defines aSayHellocall. SayHellosends aHelloRequestmessage and receives aHelloResponsemessage:
Add a .proto file to a C# app
The .proto file is included in a project by adding it to the <Protobuf> item group:
C# Tooling support for .proto files
The tooling package Grpc.Tools is required to generate the C# assets from .proto files. The generated assets (files):
- Are generated on a as-needed basis each time the project is built.
- Are not added to the project or checked into source control.
- Are a build artifact contained in the obj directory.
This package is required by both the server and client projects. Grpc.Tools can be added by using the Package Manager in Visual Studio or adding a <PackageReference> to the project file:
The tooling package is not required at runtime, therefore, the dependency should be marked with PrivateAssets="All".
Generated C# assets
The tooling package will generate the C# types representing the messages defined in the included .proto files.
For server side assets, an abstract service base type is generated. The base type contains the definitions of all the gRPC calls contained in the .proto file. You then create a concrete service implementation derives from this base type and implements the logic for the gRPC calls. For the greet.proto example described previously, an abstract GreeterBase type that contains a virtual SayHello method is generated. A concrete implementation GreeterService overrides the method and implements the logic handling the gRPC call.
For client side assets, a concrete client type is generated. The gRPC calls in the .proto file are translated to methods on the concrete type which can be called. For the greet.proto example described previously, a concrete GreeterClient type is generated. The GreeterClient type contains a SayHello method that can be called to initiate a gRPC call to the server.
By default, both server and client assets are generated for each .proto file included in the <Protobuf> item group. To ensure only the server assets are generated in a server project, the GrpcServices attribute is set to Server.
Similarly, the attribute is set to Client in client projects.