gRPC Meets .NET SDK And Visual Studio: Automatic Codegen On Build

As part of Microsoft’s move towards its cross-platform .NET offering, they have greatly simplified the project file format, and allowed a tight integration of third-party code generators with .NET projects. We are listening, and now proud to introduce integrated compilation of Protocol Buffer and gRPC service .proto files in .NET C# projects starting with the version 1.17 of the Grpc.Tools NuGet package, now available from Nuget.org.

You no longer need to use hand-written scripts to generate code from .proto files: The .NET build magic handles this for you. The integrated tools locate the proto compiler and gRPC plugin, standard Protocol Buffer imports, and track dependencies before invoking the code generators, so that the generated C# source files are never out of date, at the same time keeping regeneration to the minimum required. In essence, .proto files are treated as first-class sources in a .NET C# project.

A Walkthrough

In this blog post, we’ll walk through the simplest and probably the most common scenario of creating a library from .proto files using the cross-platform dotnet command. We will implement essentially a clone of the Greeter library, shared by client and server projects in the C# Helloworld example directory .

Create a new project

Let’s start by creating a new library project.

~/work$ dotnet new classlib -o MyGreeter
The template "Class library" was created successfully.

~/work$ cd MyGreeter
~/work/MyGreeter$ ls -lF
total 12
-rw-rw-r-- 1 kkm kkm   86 Nov  9 16:10 Class1.cs
-rw-rw-r-- 1 kkm kkm  145 Nov  9 16:10 MyGreeter.csproj
drwxrwxr-x 2 kkm kkm 4096 Nov  9 16:10 obj/

Observe that the dotnet new command has created the file Class1.cs that we won’t need, so remove it. Also, we need some .proto files to compile. For this exercise, we’ll copy an example file examples/protos/helloworld.proto from the gRPC distribution.

~/work/MyGreeter$ rm Class1.cs
~/work/MyGreeter$ wget -q https://raw.githubusercontent.com/grpc/grpc/master/examples/protos/helloworld.proto

(on Windows, use del Class1.cs, and, if you do not have the wget command, just open the above URL and use a Save As… command from your Web browser).

Next, add required NuGet packages to the project:

~/work/MyGreeter$ dotnet add package Grpc
info : PackageReference for package 'Grpc' version '1.17.0' added to file '/home/kkm/work/MyGreeter/MyGreeter.csproj'.
~/work/MyGreeter$ dotnet add package Grpc.Tools
info : PackageReference for package 'Grpc.Tools' version '1.17.0' added to file '/home/kkm/work/MyGreeter/MyGreeter.csproj'.
~/work/MyGreeter$ dotnet add package Google.Protobuf
info : PackageReference for package 'Google.Protobuf' version '3.6.1' added to file '/home/kkm/work/MyGreeter/MyGreeter.csproj'.

Add .proto files to the project

Next comes an important part. First of all, by default, a .csproj project file automatically finds all .cs files in its directory, although Microsoft now recommends suppressing this globbing behavior, so we too decided against globbing .proto files. Thus the .proto files must be added to the project explicitly.

Second of all, it is important to add a property PrivateAssets="All" to the Grpc.Tools package reference, so that it will not be needlessly fetched by the consumers of your new library. This makes sense, as the package only contains compilers, code generators and import files, which are not needed outside of the project where the .proto files have been compiled. While not strictly required in this simple walkthrough, it must be your standard practice to do that always.

So edit the file MyGreeter.csproj to add the helloworld.proto so that it will be compiled, and the PrivateAssets property to the Grpc.Tools package reference. Your resulting project file should now look like this:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Google.Protobuf" Version="3.6.1" />
    <PackageReference Include="Grpc" Version="1.17.0" />

    <!-- The Grpc.Tools package generates C# sources from .proto files during
         project build, but is not needed by projects using the built library.
         It's IMPORTANT to add the 'PrivateAssets="All"' to this reference: -->
    <PackageReference Include="Grpc.Tools" Version="1.17.0" PrivateAssets="All" />

    <!-- Explicitly include our helloworld.proto file by adding this line: -->
    <Protobuf Include="helloworld.proto" />
  </ItemGroup>

</Project>

Build it!

At this point you can build the project with the dotnet build command to compile the .proto file and the library assembly. For this walkthrough, we’ll add a logging switch -v:n to the command, so we can see that the command to compile the helloworld.proto file was in fact run. You may find it a good idea to always do that the very first time you compile a project!

Note that many output lines are omitted below, as the build output is quite verbose.

~/work/MyGreeter$ dotnet build -v:n

Build started 11/9/18 5:33:44 PM.
  1:7>Project "/home/kkm/work/MyGreeter/MyGreeter.csproj" on node 1 (Build target(s)).
   1>_Protobuf_CoreCompile:
      /home/kkm/.nuget/packages/grpc.tools/1.17.0/tools/linux_x64/protoc
        --csharp_out=obj/Debug/netstandard2.0
        --plugin=protoc-gen-grpc=/home/kkm/.nuget/packages/grpc.tools/1.17.0/tools/linux_x64/grpc_csharp_plugin
        --grpc_out=obj/Debug/netstandard2.0 --proto_path=/home/kkm/.nuget/packages/grpc.tools/1.17.0/build/native/include
        --proto_path=. --dependency_out=obj/Debug/netstandard2.0/da39a3ee5e6b4b0d_helloworld.protodep helloworld.proto
     CoreCompile:

        [ ... skipping long output ... ]

       MyGreeter -> /home/kkm/work/MyGreeter/bin/Debug/netstandard2.0/MyGreeter.dll

Build succeeded.

If at this point you invoke the dotnet build -v:n command again, protoc would not be invoked, and no C# sources would be compiled. But if you change the helloworld.proto source, then its outputs will be regenerated and then recompiled by the C# compiler during the build. This is a regular dependency tracking behavior that you expect from modifying any source file.

Of course, you can also add .cs files to the same project: It is a regular C# project building a .NET library, after all. This is done in our RouteGuide example.

Where are the generated files?

You may wonder where the proto compiler and gRPC plugin output C# files are. By default, they are placed in the same directory as other generated files, such as objects (termed the “intermediate output” directory in the .NET build parlance), under the obj/ directory. This is a regular practice of .NET builds, so that autogenerated files do not clutter the working directory or accidentally placed under source control. Otherwise, they are accessible to the tools like the debugger. You can see other autogenerated sources in that directory, too:

~/work/MyGreeter$ find obj -name '*.cs'
obj/Debug/netstandard2.0/MyGreeter.AssemblyInfo.cs
obj/Debug/netstandard2.0/Helloworld.cs
obj/Debug/netstandard2.0/HelloworldGrpc.cs

(use dir /s obj\*.cs if you are following this walkthrough from a Windows command prompt).

There Is More To It

While the simplest default behavior is adequate in many cases, there are many ways to fine-tune your .proto compilation process in a large project. We encourage you to read the documentation file BUILD-INTEGRATION.md for available options if you find that the default arrangement does not suit your workflow. The package also extends the Visual Studio’s Properties window, so you may set some options per file in the Visual Studio interface.

“Classic” .csproj projects and Mono are also supported.

Share Your Experience

As with any initial release of a complex feature, we are thrilled to receive your feedback. Did something not work as expected? Do you have a scenario that is not easy to cover with the new tools? Do you have an idea how to improve the workflow in general? Please read the documentation carefully, and then open an issue in the gRPC code repository on GitHub. Your feedback is important to determine the future direction for our build integration work!