gRPC: Document strategies for sharing proto files between apps

[StingyJack]

Copy the Protos\greet.proto file from the gRPC Greeter service to the gRPC client project.

No, really, please just say how the client can utilize the same service definition or its like representation - without requiring that we maintain two or more copies of the definition. Every other web service has had this kind of ability (wsdl, wcfmex/service contract, swagger/openapispec, etc). This tutorial should be showing us noobs the correct and practical (without having to rely on object remappers?) way.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 1d298a6c-8ddc-dbc8-d219-0fa7138442c2
• Version Independent ID: b96be346-958a-cfcd-d80a-c352d64223e8
• Content: Create a .NET Core gRPC client and server in ASP.NET Core
• Content Source: aspnetcore/tutorials/grpc/grpc-start.md
• Product: aspnet-core
• Technology: aspnetcore-tutorials
• GitHub Login: @JunTaoLuo
• Microsoft Alias: johluo

[JamesNK]

A doc page that discusses strategies for sharing proto files would be useful. It is a common topic.

[wadepickett]

@JamesNK, do we have anything internally or externally that would help me follow the best practice we would recommend? Maybe a rough outline of what we would recommend?

Move the proto in its own repository? Exposing the proto in some sort of restricted endpoint?

Would this be a pri 1 topic? Seems like it would.

[StingyJack]

FWIW, I chose to expose the proto files on the service with a static file handler in a browsable "directory". Consumers still need to auth to get to any of the services they represent.

Sticking it in a separate repo still means file copies when we need to use it.

[JamesNK]

I don't have any content for this at the moment. It's quite complex, but not something I have needed to deal with when implementing gRPC. I'd need to go off and research.

[KSRandom]

I just made a Data project, that has my proto in it, and told it to provide both GrpcServices with:

  <ItemGroup>
    <Protobuf Include="Protos\greet.proto" GrpcServices="Client,Server" />
  </ItemGroup>

Then you can make the Server and Client project depend on your Data project, and avoid duplicating the proto.

[StingyJack]

@KSRandom that may work if callers are also .net and are within your scope/org/control/etc.

[wadepickett]

Moving to next doc sprint and will kick off once we have an outline.

Notes: A very common scenario to address as a priority: "Splitting message and services across files and then import files into each other, for sharing files in their app. Docs to help this would be what the right path is when importing and where proto tooling looks for these files."

Cross-app proto file sharing solutions that the community is using (random order and just rough ideas to think about for the outline):

• Share the protocol buffers in into a centrally used repository.
• Host as static content files in a browsable directory from the running service.
• Packaging generated code from protocol buffers into libraries.
• Exposing protocol buffers through a REST endpoint
• grpc/server-reflection.md at master · grpc/grpc (github.com)

Next step: @JamesNK approves an outline to work on for this.

[StingyJack]

@wadepickett - add one to your outline for "host as static content files in a browsable directory from the running service"

[SmRiley]

Using Connected Services can easily configure the proto reference of other projects, and you can delete the link in the project file. However, this can only refer to the proto of the local file, not the proto of the project. Of course, there is nothing for the relative path of the same solution. the difference

[armintodev]

if you wanna use Client and Server classes, should use Both keywork in GrpcServices argument

[StingyJack]

@arminatwork - The point is that we dont want to use them in the same code. My team (that is skilled with .net) may be asked to build a gRPC service that serves Widgets. We do this and deploy it and test it and its working. Other teams in the same org (or externally) that could be skilled with another language like Python may need to consume our Widget service.

The simplest thing to do is to share the definition - the proto file - so the clients can be sure to meet it in whatever way is easiest for them. What's the best way to share this definition? Email is cumbersome at best. Referring to the one in the repository could be problematic if its different from what is deployed.

This isn't a unique problem but it is kind of odd that its one that doesnt already have a solution considering prior and current web service technologies have this defined as part of them (WSDL for SOAP, OAS for REST Api)