Automatic generation of gRPC server and client code from .NET interfaces When referenced by a project, this package adds itself into the compilation pipeline in the following way: For every dependent project which is marked by the GenerateGrpc attribute, it loads all eligible C# interfaces and for every such interface generates the following code: - A set of *.proto files for the hierarchy of DTO classes referenced by the source interface; - A set of C# conversion (partial) classes which provide implicit conversion operators for "gRPC - DTO" conversion for every generated *.proto file; - A gRPC server implementation which depends on source interface (via DI) and internally calls this interface for corresponding interface method implementation; - A gRPC client class which implements source interface by calling gRPC server via gRPC.
License
—
Deps
4
Install Size
—
Vulns
✓ 0
Published
Aug 13, 2024
$ dotnet add package IndependentReserve.Grpc.ToolsThis package contains MSBuild tasks and targets for automatic generation of gRPC/Protobuf code from plain C# interface(s).
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:
*.proto files defining gRPC service and messages plus the hierarchy of all DTO classes referenced by the source interface;partial classes which provide implicit conversion operators for Protobuf ↔ DTO conversion for every generated *.proto file;To generate all required gRPC/Protobuf code in a project you need to point the package 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 public interfaces which names match 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 I[service-name] source interface methods;[service-name]/Messages/*.proto files: these files contain 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:[service-name]GrpcClient.cs: gRPC client implementation:[class-name].cs files: a set of partial C# classes which add implicit conversion operators (Protobuf ↔ DTO) to generated by Grpc.Tools C# classes.[class-name].proto files set.From the above set of files normally only C# code is relevant to the user of this package. The Protobuf code can be (and should be) considered internal. In practice developer only needs to know about two classes:
[service-name]GrpcService.cs: to host the service in ASP.NET Core;[service-name]GrpcClient.cs: to call the service.Both classes either depend or implement the source interface while all boilerplate conversion to/from Protobuf messages is handled by AutoMapper framework.
Boolean, Int32, String, etc.) or one of built-in .NET-specific types from IndependentReserve.Grpc package (e.g.: Decimal, Guid, DateTime etc.) is directly convertible;IEnumerable<> interface, including IDictionary<,>) or a single-dimensional array (including jagged arrays) with elements of convertible type are convertible;default value in source type.The following .NET entities are ignored (i.e. they are not convertible):
IEnumerable<> interface);The following .NET entities are not currently supported (i.e. they are currently not convertible) but they might be supported in future versions:
Int32;ref and out source interface method parameters;The tool takes into account nullable annotations when they are available. Generally not-nullable arguments and type members produce more efficient Protobuf code. This is especially noticeable in collections, e.g. serialisation of a property of type string[] is several times faster than serialisation of a similar property but of type string?[].
Generated code use gRPC streaming to handle return type of a method or a single argument of a method of type IEnumerable<> or IAsyncEnumerable<>.
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;
}
}This tool can also generate unit tests for DTO → Protobuf → byte[] → Protobuf → DTO (round-trip) conversion/serialization path which check that after round-trip transformations the resulting "after" DTO content is equal to the source "before" DTO content.
To add test generation step to a project add GenerateGrpcTests="true" attribute to ProjectReference referencing source interface project, e.g.:
<ItemGroup>
<ProjectReference Include="..\Service.Interface.csproj" GenerateGrpcTests="true" />
</ItemGroup>The tool will then generate unit tests for every source interface method which test conversion/serialisation of every DTO referenced (even transitively) by the source interface. Generated tests use xUnit test framework. Every test is executed against generated test data set which aims to cover the entire range of DTO values using minimum number of test data values.
Generated test code is split into the following classes:
[service-name]ConversionTests.cs: a set of conversion tests for I[service-name] source interface:[method-name]RequestTest: for all convertible method's arguments (if there is any);[method-name]ResponseTest: for method's return value type (if it is convertible).[service-name]Arbitrary.cs: a set of test data generators referenced by tests via [ClassData] attribute;Asserter.cs: a per-project file which contains Assert.Equal implementation used by tests.All generated test files are placed in obj/[Configuration]/[TargetFramework]/Grpc/Tests subfolder and are automatically included into project's build.
Note: GenerateGrpcTests="true" does not generate source Protobuf code (only tests) since normally unit tests are placed in a separate project which in turn references the 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 the relevant ProjectReference.
For the above ITestService source interface the following code is generated in TestServiceConversionTests.cs file:
public partial class TestServiceConversionTests
{
private static Asserter Assert { get; set; } = Asserter.Instance;
[Theory]
[ClassData(typeof(TestServiceArbitrary.PlusRequest))]
public void PlusRequestTest(System.Int32 aBefore, System.Int32 bBefore)
{
var protoBefore = MapperTo<TestService.Messages.Grpc.PlusRequest>.MapFrom(new { A = aBefore, B = bBefore });
var bytes = Serialize(protoBefore);
var protoAfter = TestService.Messages.Grpc.PlusRequest.Parser.ParseFrom(bytes);
var (aAfter, bAfter) = MapperTo<(System.Int32, System.Int32)>.MapFrom(new { Item1 = protoAfter.A, Item2 = protoAfter.B });
Assert.Equal(aBefore, aAfter);
Assert.Equal(bBefore, bAfter);
}
[Theory]
[ClassData(typeof(TestServiceArbitrary.PlusResponse))]
public void PlusResponseTest(System.Int32 resultBefore)
{
// Test code similar to above
}
private byte[] Serialize(IMessage message)
{
// Common Protobuf serialisation code
}
}While the following test data generation code is placed in TestServiceArbitrary.cs:
public static partial class TestServiceArbitrary
{
private static TestServiceArbitraryGens Gens { get; set; } = new();
private static int? MaxTestCasesPerTest { get; set; } = 1000;
// Other settings
public class PlusRequest : IEnumerable<object[]>
{
public IEnumerator<object[]> GetEnumerator()
{
return Gens.GenPlusRequest()
.Select(elem => new object[] { elem.Item1, elem.Item2 })
.Take(MaxTestCasesPerTest ?? int.MaxValue)
.GetEnumerator();
}
// Rest of the implementation
}
public class PlusResponse : IEnumerable<object[]>
{
// Implementation similar to above
}
public class TestServiceArbitraryGens
{
public virtual IEnumerable<(System.Int32, System.Int32)> GenPlusRequest() =>
from @item1 in GenInt32()
from @item2 in GenInt32()
select MapperTo<(System.Int32, System.Int32)>.MapFrom(new
{
@Item1 = @item1,
@Item2 = @item2
});
public virtual IEnumerable<ValueTuple<System.Int32>> GenPlusResponse() =>
// Implementation similar to above
public virtual IEnumerable<Int32> GenInt32() => new[]
{
default,
Int32.MinValue,
Int32.MaxValue,
Int32.MinValue / 2,
Int32.MaxValue / 2,
};
}
}Per-project Asserter.cs:
public partial class Asserter
{
public static Asserter Instance { get; private set; } = new();
public virtual void Equal<T>(T expected, T actual)
{
Assert.Equal(JsonSerializer.Serialize(expected), JsonSerializer.Serialize(actual));
}
}Generated test code should work out of the box in most cases however there is also a way to customise it if, for example, generated test data cannot be handled by some DTO (e.g. DTO throws an exception when a property is set to int.MaxValue) or if a different content of test data is more suitable for testing of a particular DTO.
All generated top-level test classes are partial so they can be customised for example by implementing static constructor for a relevant file from where the following customisation options are available:
Asserter class: derive from this class to customise Assert.Equal logic:
Asserter.Instance property to derived implementation;[service-name]ConversionTests class: by assigning [service-name]ConversionTests.Assert to derived implementation.[service-name]Arbitrary class: customise this class to change generated test data set content:
MaxTestCasesPerTest: limits the number of test data instances generated for each test (default is 1000, set to null to remove the limit). In most cases generated test data set will contains much less than default maximum of 1000 number of items (usually less than 100);MaxCollectionSize: limits the maximum number of items in test data collections (default is 5);MaxNumberOfEnumValues: defines the maximum number of enum values which are used for test data (default is 3).[service-name]Arbitrary.[service-name]ArbitraryGens which defines a set of test data generators via a set of virtual IEnumerable<[DTO]> Gen* methods and replace any of them with a custom implementation by overriding base implementation in the derived class;static constructor of [service-name]Arbitrary class set Gens property to the instance of the derived class.