Manage Protobuf references with dotnet-grpc

  • Article

Note

This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.

Warning

This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.

Important

This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

For the current release, see the .NET 8 version of this article.

dotnet-grpc is a .NET Core Global Tool for managing Protobuf (.proto) references within a .NET gRPC project. The tool can be used to add, refresh, remove, and list Protobuf references.

Installation

To install the dotnet-grpc .NET Core Global Tool, run the following command:

dotnet tool install -g dotnet-grpc

Note

By default the architecture of the .NET binaries to install represents the currently running OS architecture. To specify a different OS architecture, see dotnet tool install, --arch option. For more information, see GitHub issue dotnet/AspNetCore.Docs #29262.

Add references

dotnet-grpc can be used to add Protobuf references as <Protobuf /> items to the .csproj file:

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

The Protobuf references are used to generate the C# client and/or server assets. The dotnet-grpc tool can:

  • Create a Protobuf reference from local files on disk.
  • Create a Protobuf reference from a remote file specified by a URL.
  • Ensure the correct gRPC package dependencies are added to the project.

For example, the Grpc.AspNetCore package is added to a web app. Grpc.AspNetCore contains gRPC server and client libraries and tooling support. Alternatively, the Grpc.Net.Client, Grpc.Tools and Google.Protobuf packages, which contain only the gRPC client libraries and tooling support, are added to a Console app.

Add file

The add-file command is used to add local files on disk as Protobuf references. The file paths provided:

  • Can be relative to the current directory or absolute paths.
  • May contain wild cards for pattern-based file globbing.

If any files are outside the project directory, a Link element is added to display the file under the folder Protos in Visual Studio.

Usage

dotnet-grpc add-file [options] <files>...

Arguments

Argument Description
files The protobuf file references. These can be a path to glob for local protobuf files.

Options

Short option Long option Description
-p --project The path to the project file to operate on. If a file is not specified, the command searches the current directory for one.
-s --services The type of gRPC services that should be generated. If Default is specified, Both is used for Web projects and Client is used for non-Web projects. Accepted values are Both, Client, Default, None, Server.
-i --additional-import-dirs Additional directories to be used when resolving imports for the protobuf files. This is a semicolon separated list of paths.
--access The access modifier to use for the generated C# classes. The default value is Public. Accepted values are Internal and Public.

Add URL

The add-url command is used to add a remote file specified by an source URL as Protobuf reference. A file path must be provided to specify where to download the remote file. The file path can be relative to the current directory or an absolute path. If the file path is outside the project directory, a Link element is added to display the file under the virtual folder Protos in Visual Studio.

Usage

dotnet-grpc add-url [options] <url>

Arguments

Argument Description
url The URL to a remote protobuf file.

Options

Short option Long option Description
-o --output Specifies the download path for the remote protobuf file. This is a required option.
-p --project The path to the project file to operate on. If a file is not specified, the command searches the current directory for one.
-s --services The type of gRPC services that should be generated. If Default is specified, Both is used for Web projects and Client is used for non-Web projects. Accepted values are Both, Client, Default, None, Server.
-i --additional-import-dirs Additional directories to be used when resolving imports for the protobuf files. This is a semicolon separated list of paths.
--access The access modifier to use for the generated C# classes. Default value is Public. Accepted values are Internal and Public.

Remove

The remove command is used to remove Protobuf references from the .csproj file. The command accepts path arguments and source URLs as arguments. The tool:

  • Only removes the Protobuf reference.
  • Does not delete the .proto file, even if it was originally downloaded from a remote URL.

Usage

dotnet-grpc remove [options] <references>...

Arguments

Argument Description
references The URLs or file paths of the protobuf references to remove.

Options

Short option Long option Description
-p --project The path to the project file to operate on. If a file is not specified, the command searches the current directory for one.

Refresh

The refresh command is used to update a remote reference with the latest content from the source URL. Both the download file path and the source URL can be used to specify the reference to be updated. Note:

  • The hashes of the file contents are compared to determine whether the local file should be updated.
  • No timestamp information is compared.

The tool always replaces the local file with the remote file if an update is needed.

Usage

dotnet-grpc refresh [options] [<references>...]

Arguments

Argument Description
references The URLs or file paths to remote protobuf references that should be updated. Leave this argument empty to refresh all remote references.

Options

Short option Long option Description
-p --project The path to the project file to operate on. If a file is not specified, the command searches the current directory for one.
--dry-run Outputs a list of files that would be updated without downloading any new content.

List

The list command is used to display all the Protobuf references in the project file. If all values of a column are default values, the column may be omitted.

Usage

dotnet-grpc list [options]

Options

Short option Long option Description
-p --project The path to the project file to operate on. If a file is not specified, the command searches the current directory for one.

Additional resources