Administración de referencias de Protobuf con dotnet-grpc

  • Artículo

dotnet-grpc es una herramienta global de .NET Core para administrar referencias de Protobuf (.proto) dentro de un proyecto gRPC de .NET. La herramienta se puede usar para agregar, actualizar, quitar y enumerar las referencias de Protobuf.

Instalación

Para instalar la dotnet-grpcherramienta global de .NET Core, ejecute el comando siguiente:

dotnet tool install -g dotnet-grpc

Nota:

De manera predeterminada, la arquitectura de los binarios .NET que se van a instalar representa la arquitectura del sistema operativo que se está ejecutando en ese momento. Para especificar una arquitectura de SO diferente, consulte dotnet tool install, --arch option. Para más información, consulte la incidencia de GitHub dotnet/AspNetCore.Docs #29262.

Agregar referencias

dotnet-grpc se puede usar para agregar referencias de Protobuf como elementos <Protobuf /> al archivo .csproj:

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

Las referencias de Protobuf se usan para generar los recursos de cliente o servidor de C#. La herramienta dotnet-grpc puede:

  • Crear una referencia de Protobuf a partir de archivos locales en el disco.
  • Crear una referencia de Protobuf a partir de un archivo remoto especificado por una dirección URL.
  • Asegurarse de que se han agregado al proyecto las dependencias de paquete gRPC correctas.

Por ejemplo, el paquete Grpc.AspNetCore se agrega a una aplicación web. Grpc.AspNetCore contiene bibliotecas de cliente y servidor de gRPC, y compatibilidad con herramientas. Como alternativa, los paquetes Grpc.Net.Client, Grpc.Tools y Google.Protobuf, que contienen solo las bibliotecas de cliente de gRPC y la compatibilidad con herramientas, se agregan a una aplicación de consola.

Agregar archivo

El comando add-file se usa para agregar archivos locales en el disco como referencias de Protobuf. Las rutas de acceso de archivo proporcionadas:

  • Pueden ser relativas al directorio actual o rutas de acceso absolutas.
  • Puede contener caracteres comodín para patrones globales de archivo basados en patrones.

Si algún archivo está fuera del directorio del proyecto, se agrega un elemento Link para mostrar el archivo en la carpeta Protos de Visual Studio.

Uso

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

Argumentos

Argument Descripción
archivos Las referencias de archivo de Protobuf. Pueden ser una ruta de acceso a patrones para los archivos Protobuf locales.

Opciones

Opción corta Opción larga Descripción
-p --project La ruta de acceso al archivo del proyecto sobre el que se va a actuar. Si no se especifica un archivo, el comando busca uno en el directorio actual.
-S --services El tipo de servicios gRPC que se deben generar. Si se especifica Default, se usa Both para los proyectos web y Client para los que no son web. Los valores aceptados son Both, Client, Default, None, Server.
-i --additional-import-dirs Directorios adicionales que se usarán al resolver importaciones para los archivos de Protobuf. Es una lista de rutas de acceso separadas por punto y coma.
--access El modificador de acceso que se va a usar para las clases generadas de C#. El valor predeterminado es Public. Los valores aceptados son: Internal y Public.

Agregar dirección URL

El comando add-url se usa para agregar un archivo remoto especificado por una dirección URL de origen como referencia de Protobuf. Se debe proporcionar una ruta de acceso de archivo para especificar dónde descargar el archivo remoto. La ruta de acceso puede ser relativa al directorio actual o absoluta. Si la ruta de acceso está fuera del directorio del proyecto, se agrega un elemento Link para mostrar el archivo en la carpeta virtual Protos de Visual Studio.

Uso

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

Argumentos

Argument Descripción
url La dirección URL de un archivo protobuf remoto.

Opciones

Opción corta Opción larga Descripción
-o --output Especifica la ruta de descarga para el archivo protobuf remoto. Esta es una opción necesaria.
-p --project La ruta de acceso al archivo del proyecto sobre el que se va a actuar. Si no se especifica un archivo, el comando busca uno en el directorio actual.
-S --services El tipo de servicios gRPC que se deben generar. Si se especifica Default, se usa Both para los proyectos web y Client para los que no son web. Los valores aceptados son Both, Client, Default, None, Server.
-i --additional-import-dirs Directorios adicionales que se usarán al resolver importaciones para los archivos de Protobuf. Es una lista de rutas de acceso separadas por punto y coma.
--access El modificador de acceso que se va a usar para las clases generadas de C#. El valor predeterminado es Public. Los valores aceptados son: Internal y Public.

Quitar

El comando remove se usa para quitar las referencias de Protobuf del archivo .csproj. El comando acepta argumentos de ruta de acceso y direcciones URL de origen como argumentos. La herramienta:

  • Solo quita la referencia de Protobuf.
  • No elimina el archivo .proto, incluso si se ha descargado originalmente desde una dirección URL remota.

Uso

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

Argumentos

Argument Descripción
referencias Las direcciones URL o rutas de acceso de archivo de las referencias de Protobuf que se van a quitar.

Opciones

Opción corta Opción larga Descripción
-p --project La ruta de acceso al archivo del proyecto sobre el que se va a actuar. Si no se especifica un archivo, el comando busca uno en el directorio actual.

Refresh

El comando refresh se usa para actualizar una referencia remota con el contenido más reciente de la dirección URL de origen. Tanto la ruta de acceso del archivo de descarga como la dirección URL de origen se pueden usar para especificar la referencia que se va a actualizar. Nota:

  • Los códigos hash del contenido del archivo se comparan para determinar si se debe actualizar el archivo local.
  • No se compara la información de marca de tiempo.

La herramienta siempre reemplaza el archivo local con el archivo remoto si se necesita una actualización.

Uso

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

Argumentos

Argument Descripción
referencias Las direcciones URL o las rutas de acceso de archivo a referencias de Protobuf remotas que se deben actualizar. Deje este argumento vacío para actualizar todas las referencias remotas.

Opciones

Opción corta Opción larga Descripción
-p --project La ruta de acceso al archivo del proyecto sobre el que se va a actuar. Si no se especifica un archivo, el comando busca uno en el directorio actual.
--dry-run Genera una lista de archivos que se actualizarían sin descargar ningún contenido nuevo.

Lista

El comando list se usa para mostrar todas las referencias de Protobuf en el archivo de proyecto. Si todos los valores de una columna son valores predeterminados, la columna se puede omitir.

Uso

dotnet-grpc list [options]

Opciones

Opción corta Opción larga Descripción
-p --project La ruta de acceso al archivo del proyecto sobre el que se va a actuar. Si no se especifica un archivo, el comando busca uno en el directorio actual.

Recursos adicionales