Administración de referencias de Protobuf con dotnet-grpc
Nota:
Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión de .NET 9 de este artículo.
Advertencia
Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta la versión .NET 8 de este artículo.
Importante
Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.
Para la versión actual, consulte la versión de .NET 9 de este 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 herramienta global de .NET Core dotnet-grpc, 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, consulta 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. |
