[csharp] Grpc.Tools documentation for sharing proto files between projects and nuget packages (#34521)

Added documented for Grpc.Tools for sharing proto files - between projects in a solution - in NuGet packages to be used by other projects This addresses the questions raised in: - https://github.com/grpc/grpc-dotnet/issues/1458 - https://github.com/grpc/grpc-dotnet/issues/183 @jtattermusch @JamesNK --------- Co-authored-by: James Newton-King <james@newtonking.com>
1 year ago · 301636dae0
parent a935d7c190
commit 301636dae0
1 changed files with 184 additions and 0 deletions
--- a/src/csharp/BUILD-INTEGRATION.md
+++ b/src/csharp/BUILD-INTEGRATION.md
@ -79,6 +79,63 @@ For `.proto` files that are outside of the project directory a link can be added

 For more examples see the example project files in GitHub: https://github.com/grpc/grpc-dotnet/tree/master/examples

+## Sharing `.proto` files between multiple projects (in the same VS solution)
+
+It's common to want to share `.proto` files between projects. For example, a gRPC client
+and gRPC server share the same contract. It is preferable to share contracts without
+copying `.proto` files because copies can go out of sync over time.
+
+There are a couple of ways to use `.proto` files in multiple projects without duplication:
+
+* Sharing `.proto` files between projects with MSBuild links.
+* Generating code in a class library and sharing the library.
+
+### Sharing `.proto` with MSBuild links
+
+`.proto` files can be placed in a shared location and referenced by multiple projects
+using MSBuild's [`Link` or `LinkBase` settings](https://learn.microsoft.com/visualstudio/msbuild/common-msbuild-item-metadata).
+
+```xml
+<ItemGroup>
+   <Protobuf Include="..\Protos\greet.proto" GrpcServices="None" Link="Protos\greet.proto"/>
+</ItemGroup>
+```
+
+In the example above, `greet.proto` is in a shared `Protos` directory outside 
+the project directory. Multiple projects can reference the proto file.
+
+### Generating code in a class library
+
+Create a class library that references `.proto` files and contains generated code. The other
+projects in the solution can then reference this shared class library instead of each project
+having to compile the same `.proto` files.
+
+The advantages of this are:
+- The `.proto` only need to be compiled once.
+- It prevents some projects getting multiple definitions of the same generated code, which can in turn break the build.
+
+There are a couple of examples in GitHub:
+- The [Liber example](https://github.com/grpc/grpc-dotnet/tree/master/examples#liber)
+  demonstrates how common protocol buffers messages can be compiled once and used in other projects:
+  - The *Common* project creates a class library that includes the generates messages contained in `common.proto`
+  - The *Client* and *Server* projects reference the *Common* project.
+  - They do not need to recompile `common.proto` as those .NET types are already in
+    the *Common* class library.
+  - They do however each generate their own gRPC client or server code as both have a 
+    `<Protobuf>` reference for `greet.proto`.  The *Client* and *Server* projects each having their own version of `greet.proto` is OK since they don't reference each other - they only reference the shared *Common* class library.
+
+- The [RouteGuide example](https://github.com/grpc/grpc/tree/v1.46.x/examples/csharp/RouteGuide)
+  demonstrates how the gRPC client and server code can be generated once and used in other
+  projects:
+  - **Note:** this example uses the *legacy c-core C#* packages, but the principles are the same
+    for *gRPC for .NET* projects.
+  - The *RouteGuide* project has a `<Protobuf>` reference to `route_guide.proto` and 
+    generates both the gRPC client and server code.
+  - The *RouteGuideClient* and *RouteGuideServer* projects reference the *RouteGuide* project.
+  - They do not need any `<Protobuf>` references since the code has already been
+    generated in the *RouteGuide* project.
+
+
 # Reference

 ## Protobuf item metadata reference
@ -252,6 +309,7 @@ Quick links to the examples below:
 * [Visual Studio: setting per-file `.proto` file options](#visualstudio)
 * [Bypassing Grpc.Tools to run the protocol buffers compiler explicitly](#compiler)
 * [Using Grpc.Tools with unsupported architectures](#unsupported-arch)
+* [Including `.proto` files in NuGet packages](#proto-only-nuget)

 ---
 ## <a name="ProtoRoot"></a>ProtoRoot - Common root for one or more `.proto` files
@ -565,6 +623,132 @@ dotnet build

 ---

+## <a name="proto-only-nuget"></a>Including `.proto` files in NuGet packages
+
+There might be occassions when you are given a NuGet package that contains
+`.proto` files that you wish to use in your own project, or you may wish to 
+package your own `.proto` files in a NuGet package for others to use.
+
+There is no automatic way for `Grpc.Tools` to locate and include `.proto`
+files from other NuGet packages. Below is a suggested convention to use
+when creating NuGet packages that contain `.proto` files.
+
+__Note:__ This is not the same as a NuGet package providing a library built from
+the code generated from the `.proto` files. Below just describes how to provide
+the uncompiled `.proto` files in a NuGet package and have `Grpc.Tools` automatically
+use them.
+
+### Creating the NuGet package
+
+The NuGet package should:
+- provide the `.proto` files in a `content\protos` subdirectory in the package
+- provide a `packagename.targets` file in the `build` subdirectory in the package that:
+  - defines an MSBuild property giving the path to the `.proto` files in the
+    installed package
+  - conditionally updates the `Protobuf_StandardImportsPath` property with the
+    above path so that the files can be found by the protocol buffers compiler
+    - it should be made optional forcing users to *opt in* to including
+      the `.proto` files
+
+For example, for the package `My.Example.Protos`:
+
+My.Example.Protos.nuspec:
+```xml
+<?xml version="1.0"?>
+<package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd">
+  <metadata>
+    <id>My.Example.Protos</id>
+    <version>1.0.0</version>
+    <title>Example package containing proto files</title>
+    <authors>author</authors>
+    <owners>owner</owners>
+    <licenseUrl>license url</licenseUrl>
+    <projectUrl>project url</projectUrl>
+    <description>See project site for more info.</description>
+    <summary>Example package containing proto files.</summary>
+    <releaseNotes>Example package containing proto files</releaseNotes>
+    <copyright>Copyright 2023, My Company.</copyright>
+  </metadata>
+  
+  <files>
+    <!-- copy the My.Example.Protos.targets file for MSBuild integration -->
+    <file src="build\**" target="build" />
+    <!-- copy the .proto files into the package -->
+    <file src="proto\**" target="content\protos" />
+  </files>
+</package>
+```
+
+My.Example.Protos.targets:
+```xml
+<?xml version="1.0"?>
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <!-- This targets file allows .proto files bundled in package, 
+  to be included in Grpc.Tools compilation. -->
+  
+  <PropertyGroup>
+    <!-- Define a property containing the path of the proto files.
+         Content from the nupkg. -->
+    <MyExampleProtos_ProtosPath>$( [System.IO.Path]::GetFullPath($(MSBuildThisFileDirectory)../content/protos) )</MyExampleProtos_ProtosPath>
+  </PropertyGroup>
+
+  <!-- Run immediately before the Protobuf_BeforeCompile extension point. -->
+  <!-- Only include protos if project has set <IncludeMyExampleProtosProtos> 
+       property to true. -->
+  <Target Name="MyExampleProtos_BeforeCompile"
+          BeforeTargets="Protobuf_BeforeCompile"
+          Condition=" '$(IncludeMyExampleProtosProtos)' == 'true' ">
+    <PropertyGroup>
+      <!-- Add proto files by including path in Protobuf_StandardImportsPath.
+           This path is passed to protoc via the -I option -->
+      <Protobuf_StandardImportsPath>$(Protobuf_StandardImportsPath);$(MyPackage_ProtosPath)</Protobuf_StandardImportsPath>
+    </PropertyGroup>
+
+    <!-- These message are not required but included here for diagnostics -->
+    <Message Text="Included proto files at $(MyExampleProtos_ProtosPath) in import path." Importance="high" />
+    <Message Text="Updated proto imports path: $(Protobuf_StandardImportsPath)" Importance="high" />
+  </Target>
+</Project>
+```
+
+### Using the NuGet package
+
+The project needs to add the package containing the `.proto` files:
+```xml
+<PackageReference Include="My.Example.Protos" Version="1.0.0" />
+```
+
+If the project only wants to compile the `.proto` files included in the package
+then all it needs to do is add the `<Protobuf>` items using the property defined
+in the package for the path to the files. For example, if the NuGet package contained
+the file `greet.proto`, then the project should add:
+
+```xml
+<Protobuf Include="$(MyExampleProtos_ProtosPath)/greet.proto" />
+```
+
+However if the provided `.proto` files are to be *imported* by the projects own `.proto`
+files then the `Protobuf_StandardImportsPath` needs updated to add the directory
+containing the package's files.  This is done by setting to `true` the property
+used in the package. For example, if the project has the local `.proto` file
+`my_services.proto` and it imported a file from the package `common_message.proto`,
+then:
+
+```xml
+<PropertyGroup>
+  <!-- Update the Protobuf_StandardImportsPath -->
+  <IncludeMyExampleProtosProtos>true</IncludeMyExampleProtosProtos>
+</PropertyGroup>
+
+<ItemGroup>
+  <!-- my_services.proto imports common_message.proto from the package
+   My.Example.Protos -->
+  <Protobuf Include="my_services.proto" />
+</ItemGroup>
+```
+
+---
+
 ## See also

 gRPC project documentation: