Lines Matching +full:plugin +full:- +full:syntax +full:- +full:class +full:- +full:properties
4 * It contains protocol buffers compiler and gRPC plugin to generate C# code.
5 * It can be used in building both grpc-dotnet projects and legacy c-core C# projects.
13 * are generated on an as-needed basis each time the project is built.
21 the server and client projects, and by both c-core C# projects and grpc-dotnet projects:
25 `Grpc.Tools` is only used at build-time and has no runtime components.
40 See [Using Grpc.Tools with unsupported architectures](#unsupported-arch) below.
60 By default, a `<Protobuf>` reference generates gRPC client and a service base class from the `servi…
80 For more examples see the example project files in GitHub: https://github.com/grpc/grpc-dotnet/tree…
91 * Generating code in a class library and sharing the library.
96 …LinkBase` settings](https://learn.microsoft.com/visualstudio/msbuild/common-msbuild-item-metadata).
107 ### Generating code in a class library
109 Create a class library that references `.proto` files and contains generated code. The other
110 projects in the solution can then reference this shared class library instead of each project
114 - The `.proto` only need to be compiled once.
115 - It prevents some projects getting multiple definitions of the same generated code, which can in t…
118 - The [Liber example](https://github.com/grpc/grpc-dotnet/tree/master/examples#liber)
120 …- The *Common* project creates a class library that includes the generates messages contained in `…
121 - The *Client* and *Server* projects reference the *Common* project.
122 - They do not need to recompile `common.proto` as those .NET types are already in
123 the *Common* class library.
124 - They do however each generate their own gRPC client or server code as both have a
125 …t.proto` is OK since they don't reference each other - they only reference the shared *Common* cla…
127 - The [RouteGuide example](https://github.com/grpc/grpc/tree/v1.46.x/examples/csharp/RouteGuide)
130 - **Note:** this example uses the *legacy c-core C#* packages, but the principles are the same
132 - The *RouteGuide* project has a `<Protobuf>` reference to `route_guide.proto` and
134 - The *RouteGuideClient* and *RouteGuideServer* projects reference the *RouteGuide* project.
135 - They do not need any `<Protobuf>` references since the code has already been
146 |----------------|-----------|----------------------|----------------------------------|
147 | Access | `public` | `public`, `internal` | Generated class access …
148 …ine flags passed to `protoc` command. To specify multiple arguments use semi-colons (;) to separat…
153 | OutputOptions | | arbitrary options | Extra options passed to C# codegen as `--…
155 …bitrary options | Extra options passed to gRPC codegen as `--grpc_opt=opt1,opt2` |
183 Sets generated class access on _both_ generated message and gRPC stub classes.
191 …ns to `protoc` in the form `--csharp_opt=opt1,opt2`. See [C#-specific options](https://protobuf.de…
194 Pass additional options to the `grpc_csharp_plugin` in form of the `--grpc_opt` flag.
202 project directory. The directories are passed to the `protoc` code generator via the `-I/--proto_pa…
207 Some properties allow you to specify multiple values in a list. The items in a list need to
208 be separated by semi-colons (;). This is the syntax that MsBuild uses for lists.
210 The properties that can have lists of items are: `OutputOptions`, `AdditionalProtocArguments`,
213 Example: to specify two additional arguments: `--plugin=protoc-gen-myplugin=D:\myplugin.exe --myplu…
219 … AdditionalProtocArguments="--plugin=protoc-gen-myplugin=D:\myplugin.exe;--myplugin_out=." />
229 |---------------- |-----------|----------------------------------------------------------|
231 | no_server | off | Don't generate the server-side stub |
234 …*Experimental - may change or be removed.* Same as `base_namespace` for `protoc` [C# options](http…
240 - `file_suffix` and `base_namespace` should not be used with `Grpc.Tools`. Using them will break th…
242 - using `base_namespace` changes the algorithm for the generated file names to align it with the al…
246 To use these options on the command line specify them with the `--grpc_opt`
249 …nerated by `protoc` is independent of the plugin and you may also need to specify C# options for t…
250 These are [documented here](https://protobuf.dev/reference/csharp/csharp-generated/#compiler_option…
255 protoc --plugin=protoc-gen-grpc=grpc_csharp_plugin \
256 --csharp_out=OUT_DIR \
257 --csharp_opt=base_namespace=Example \
258 --grpc_out=OUT_DIR \
259 --grpc_opt=no_server,base_namespace=Example \
260 -I INCLUDE_DIR foo.proto
264 …or of `Grpc.Tools` - setting the CPU architecture or operating system, or using custom built proto…
267 |---------------------|----------------------------------------------------------------------------…
280 ## MSBuild Properties
282 You can set some Properties in your project file or on the MSBuild command line. The
283 following properties change the behavior of `Grpc.Tools`:
286 |---------------------|----------------------------------------------------------------------------…
292 | `Protobuf_OutputPath`| Default: `IntermediateOutputPath` - ususally the `obj` directory. Sets the…
294 …d in the NuGet package. It is automcatically passed to `protoc` via the `-I/--proto_path` option.…
299 * [grpc-dotnet examples](https://github.com/grpc/grpc-dotnet/tree/master/examples)
304 * [ProtoRoot - Common root for one or more `.proto` files](#ProtoRoot)
305 * [AdditionalImportDirs - Setting location of imported `.proto` files](#AdditionalImportDirs)
306 * [GrpcServices - Generating gRPC services and protocol buffers messages](#grpcservices)
309 * [Visual Studio: setting per-file `.proto` file options](#visualstudio)
311 * [Using Grpc.Tools with unsupported architectures](#unsupported-arch)
312 * [Including `.proto` files in NuGet packages](#proto-only-nuget)
314 ---
315 ## <a name="ProtoRoot"></a>ProtoRoot - Common root for one or more `.proto` files
373 * the import search paths passed to `protoc` via `-I/--proto_path` option will include
375 ---
376 ## <a name="AdditionalImportDirs"></a>AdditionalImportDirs - Setting location of imported `.proto` …
396 ---
397 ## <a name="grpcservices"></a>GrpcServices - Generating gRPC services and protocol buffers messages
403 * `Myfile.cs` - contains the generated code for protocol buffers messages
404 * `MyfileGrpc.cs` - contains the generated code for gRPC client and/or server
407 the gRPC plugin to generate gRPC client and/or server stub code. Whether or not the `*Grpc.cs` file
411 * `GrpcServices="Both"` (the default) - `Myfile.cs` and `MyfileGrpc.cs` generated
412 * `GrpcServices="None"` - just `Myfile.cs` generated
413 * `GrpcServices="Client"` - `Myfile.cs` and `MyfileGrpc.cs` (just client code)
414 * `GrpcServices="Server"` - `Myfile.cs` and `MyfileGrpc.cs` (just server code)
436 `GrpcServices="Both"`. Note the use of the `Update` attribute instead of `Include` - otherwise
450 …d files is configured to a directory outside of the project, e.g. `OutputDir="..\outside-project\"`
457 outside of the project directory so as not to pollute non-project directories.
469 ---
473 directory or sub-directories, without having to specify them with a `<Protobuf>` item.
483 ---
508 rm *.cs # remove .cs files - for Windows the command is: del *.cs /y
512 ---
513 ## <a name="visualstudio"></a>Visual Studio: setting per-file `.proto` file options
515 In Visual Studio it is possible to set some frequently used per-file options on `.proto` files
523 properties window after adding a reference to `Grpc.Tools` package:
525 
534 change file type of the `.proto` files to "Protobuf" in the Properties window
535 drop-down. This menu item will appear after you import the `Grpc.Tools` package:
537 
539 ---
546 You can use the following Properties:
550 * `gRPC_PluginFullPath` points to the full path and filename of gRPC plugin, e.g.
563 …<ProtoCCommand>$(Protobuf_ProtocFullPath) --plugin=protoc-gen-grpc=$(gRPC_PluginFullPath) -I $(Pr…
571 ---
573 ## <a name="unsupported-arch"></a>Using Grpc.Tools with unsupported architectures
579 find pre-built binaries provided by the community, then you can define a couple of
582 * `PROTOBUF_PROTOC` - Full path to the protocol buffers compiler
583 * `GRPC_PROTOC_PLUGIN` - Full path to the `grpc_csharp_plugin`
604 …https://pkgs.alpinelinux.org/packages?name=grpc-plugins](https://pkgs.alpinelinux.org/packages?nam…
610 # e.g. for Alpine Linux the grpc-plugins package can be used
611 # See https://pkgs.alpinelinux.org/package/edge/community/x86_64/grpc-plugins
612 apk add grpc-plugins # Alpine Linux specific package installer
624 ---
626 ## <a name="proto-only-nuget"></a>Including `.proto` files in NuGet packages
644 - provide the `.proto` files in a `content\protos` subdirectory in the package
645 - provide a `packagename.targets` file in the `build` subdirectory in the package that:
646 - defines an MSBuild property giving the path to the `.proto` files in the
648 - conditionally updates the `Protobuf_StandardImportsPath` property with the
650 - it should be made optional forcing users to *opt in* to including
674 <!-- copy the My.Example.Protos.targets file for MSBuild integration -->
676 <!-- copy the .proto files into the package -->
686 <!-- This targets file allows .proto files bundled in package,
687 to be included in Grpc.Tools compilation. -->
690 <!-- Define a property containing the path of the proto files.
691 Content from the nupkg. -->
695 <!-- Run immediately before the Protobuf_BeforeCompile extension point. -->
696 <!-- Only include protos if project has set <IncludeMyExampleProtosProtos>
697 property to true. -->
702 <!-- Add proto files by including path in Protobuf_StandardImportsPath.
703 This path is passed to protoc via the -I option -->
707 <!-- These message are not required but included here for diagnostics -->
739 <!-- Update the Protobuf_StandardImportsPath -->
744 <!-- my_services.proto imports common_message.proto from the package
745 My.Example.Protos -->
750 ---
755 * [gRPC for .NET](https://github.com/grpc/grpc-dotnet)
757 * [Grpc.Tools internals](Grpc.Tools/implementation_notes.md) - implementation notes for how `Grpc.T…
760 * [Microsoft: Overview for gRPC on .NET](https://learn.microsoft.com/en-us/aspnet/core/grpc/)
761 …for .proto files](https://learn.microsoft.com/en-us/aspnet/core/grpc/basics#c-tooling-support-for-…