IndependentReserve.Grpc.Tools 1.9.106

IndependentReserve.Grpc.Tools

Purpose

This package contains MSBuild tasks and targets for automatic generation of gRPC/Protobuf code from plain C# interface(s).

How it works

When this package is referenced by a project it adds itself into compilation pipeline in the following way:
For every depended project which is marked by GenerateGrpc attribute it loads all eligible C# interfaces and for every such source interface it generates the following code:

• a set of *.proto files defining gRPC service and messages plus the hierarchy of all DTO classes referenced by the source interface;
• a set of C# partial classes which provide implicit conversion operators for Protobuf ↔ DTO conversion for every generated *.proto file;
• gRPC service implementation which depends on source interface and internally calls this interface for corresponding interface method implementation;
• gRPC client class which implements the source interface by calling gRPC server via gRPC.

How to use it

To use this tool first you need to reference this NuGet package in your project via PackageReference, e.g.:

<ItemGroup>
  <PackageReference Include="IndependentReserve.Grpc.Tools" Version="1.9.*" />
</ItemGroup>

gRPC/Protobuf code generation

To generate all required gRPC/Protobuf code in a project you need to point it to a separate project which contains interface (or interfaces) which you want to generate gRPC/Protobuf types for. To do that simply add GenerateGrpc="true" attribute to ProjectReference element of the relevant source project, e.g.:

<ItemGroup>
  <ProjectReference Include="..\Service.Interface.csproj" GenerateGrpc="true" />
</ItemGroup>

By default the tool searches for all C# interfaces with the name matching Service$ regular expression (e.g. ISomeService) and generates all required gRPC-related code for every found interface.
To use a different pattern for interface search specify a custom regular expression (.NET flavor) via GrpcServicePattern attribute, e.g.:

<ItemGroup>
  <ProjectReference Include="..\Service.Interface.csproj" >
    <GenerateGrpc>true</GenerateGrpc>
    <GrpcServicePattern>I[^.]*ServiceInterface$</GrpcServicePattern>
  </ProjectReference>
</ItemGroup>  

Note: the source interfaces must be in a separate dependent project because the tool uses reflection to load and process source interfaces during the build.

All generated files are placed in obj/[Configuration]/[TargetFramework]/Grpc root folder and are automatically included into project's build.
All *.proto files are placed in Protos subfolder:

• [service-name].proto file: gRPC service definition file which defines all methods mirroring source interface methods;
• [service-name]Messages.proto file: this file contains all *Request and *Response messages referenced from [service-name].proto file;
• [class-name].proto files: a hierarchy of messages which are referenced (directly or indirectly) by messages from [service-name]Messages.proto.

All *.cs files are placed in Partials subfolder:

• [service-name]GrpcService.cs: gRPC service class:
  This class depends on the source interface and it is expected that the implementation of this interface passed to gRPC service class constructor (e.g. via dependency injection) contains the internal implementation of the service logic;
• [service-name]GrpcClient.cs: gRPC client implementation:
  This class implements source interface by calling the service via gRPC (using internal gRPC client class in turn generated by Grpc.Tools). For each method from source interface both synchronous and asynchronous methods are generated.
• [class-name].cs files: a set of partial C# classes which add implicit conversion operators (Protobuf ↔ DTO) to generated by Grpc.Tools C# classes.
  There is one to one correspondence between this set and [class-name].proto files set.

Among the above set of files normally only C# code is relevant to the user of this package. The Protobuf code can be considered internal. In practice a developer only needs to know about two classes:

• gRPC service: to host the service in ASP.NET;
• gRPC client: to call the service.

Both classes depend/implement the source interface while all conversion to/from Protobuf messages is hidden from a developer (and internally implemented using AutoMapper framework).

Example of generated C# code

If we pass the following source interface to the tool:

public interface ITestService
{
    int Plus(int a, int b);
}

it will generate the following gRPC service class:

public partial class TestServiceGrpcService : TestServiceBase
{
    private readonly ILogger<TestServiceGrpcService> _logger;
    private readonly ITestService _testService;

    public TestServiceGrpcService(
        ILogger<TestServiceGrpcService> logger,
        ITestService testService)
    {
        _logger = logger;
        _testService = testService;
    }

    public override async Task<PlusResponse> Plus(PlusRequest request, ServerCallContext context)
    {
        var args = MapperTo<ValueTuple<System.Int32, System.Int32>>.MapFrom(new { Item1 = request.A, Item2 = request.B });
        var result = _testService.Plus(args.Item1, args.Item2);
        return MapperTo<PlusResponse>.MapFrom(new { Result = result });
    }
}

along with the following gRPC client class:

public partial class TestServiceGrpcClient : GrpcClient, ITestService
{
    private readonly Lazy<TestServiceClient> _client;

    public TestServiceGrpcClient(IGrpcServiceConfiguration config, bool useGrpcWeb = true)
        : base(config, useGrpcWeb)
    {
        var invoker = Channel.CreateCallInvoker();
        SetupCallInvoker(ref invoker);
        _client = new(() => new(invoker));
    }

    partial void SetupCallInvoker(ref CallInvoker invoker);

    private TestServiceClient Client => _client.Value;

    public System.Int32 Plus(System.Int32 a, System.Int32 b)
    {
        var response = Client.Plus(MapperTo<PlusRequest>.MapFrom(new { A = a, B = b }));
        return MapperTo<Wrapper<System.Int32>>.MapFrom(response).Result;
    }

    public async Task<System.Int32> PlusAsync(System.Int32 a, System.Int32 b)
    {
        var response = await Client.PlusAsync(MapperTo<PlusRequest>.MapFrom(new { A = a, B = b }));
        return MapperTo<Wrapper<System.Int32>>.MapFrom(response).Result;
    }
}

DTO ↔ Protobuf conversion code test generation

This tool can also generate unit tests for DTO → gRPC → byte[] → gRPC → DTO (round-trip) conversion/serialization path which check that after conversion/serialization the source DTO content is matched by the resulting DTO content.
To add test generation step to a project add GenerateGrpcTests="true" attribute to the ProjectReference to the source interface project, e.g.:

<ItemGroup>
  <ProjectReference Include="..\Service.Interface.csproj" GenerateGrpcTests="true" />
</ItemGroup>

The tool then generates unit tests for every DTO referenced by the source interface. It uses xUnit since this test framework allows test input being provided by an external class via ClassData attribute. Every test is run against generated test data (random DTO content). By default it generates 1000 random DTO instances in every test. This limit can be controlled by setting Arbitrary.TestCount property, e.g.:

  public partial class ConversionTests
  {
      static ConversionTests()
      {
          Arbitrary.TestCount = 10000;
      }
  }

Note: GenerateGrpcTests="true" does not generate source Protobuf code (only tests) since normally unit tests are placed in a separate project which references a project which contains generated (via GenerateGrpc="true") Protobuf code. If you require both code and the tests to be generated in the same project add both GenerateGrpc and GenerateGrpcTests attributes to relevant ProjectReference.