Gérer les références Protobuf avec dotnet-GRPC

  • Article

dotnet-grpc est un outil global .NET Core permettant de gérer les références Protobuf (.proto) au sein d’un projet .NET gRPC. L’outil peut être utilisé pour ajouter, actualiser, supprimer et lister les références Protobuf.

Installation

Pour installer l’dotnet-grpcoutil global .NET Core, exécutez la commande suivante :

dotnet tool install -g dotnet-grpc

Remarque

Par défaut, l’architecture des fichiers binaires .NET à installer représente l’architecture du système d’exploitation en cours d’exécution. Pour spécifier une architecture de système d’exploitation différente, consultez dotnet tool install, --arch option. Pour plus d'informations, consultez le problème GitHub dotnet/AspNetCore.Docs n° 29262.

Ajouter des références

dotnet-grpc peut être utilisé pour ajouter des références Protobuf en tant qu’éléments <Protobuf /> dans le fichier .csproj :

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

Les références Protobuf sont utilisées pour générer les ressources client et/ou serveur C#. L’outil dotnet-grpc peut :

  • Créer une référence Protobuf à partir de fichiers locaux sur le disque.
  • Créer une référence Protobuf à partir d’un fichier distant spécifié par une URL.
  • Garantir que les dépendances de package gRPC appropriées sont ajoutées au projet.

Par exemple, le package Grpc.AspNetCore est ajouté à une application web. Grpc.AspNetCore inclut la prise en charge des outils et des bibliothèques serveur et client gRPC. Les packages Grpc.Net.Client, Grpc.Tools et Google.Protobuf, qui incluent uniquement la prise en charge des outils et des bibliothèques client gRPC, sont également ajoutés à une application console.

Ajouter un fichier

La commande add-file est utilisée pour ajouter des fichiers locaux sur le disque en tant que références Protobuf. Chemins d’accès de fichiers fournis :

Si des fichiers se trouvent en dehors du répertoire du projet, un élément Link est ajouté pour afficher le fichier sous le dossier Protos dans Visual Studio.

Utilisation

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

Arguments

Argument Description
files Références des fichiers Protobuf. Il peut s’agir d’un chemin vers glob pour les fichiers Protobuf locaux.

Options

Option courte Option longue Description
-p --project Chemin d’accès au fichier projet à traiter. Si aucun fichier n’est spécifié, la commande effectue une recherche dans le répertoire actif.
-s --services Type des services gRPC qui doivent être générés. Si Default est spécifié, Both est utilisé pour les projets Web et Client est utilisé pour les projets non basés sur le web. Les valeurs acceptées sont Both, Client, Default, None, Server.
-i --additional-import-dirs Répertoires supplémentaires à utiliser lors de la résolution des importations pour les fichiers Protobuf. Il s’agit d’une liste de chemins séparés par des points-virgules.
--access Modificateur d’accès à utiliser pour les classes C# générées. La valeur par défaut est Public. Les valeurs acceptées sont Internal et Public.

Ajouter une URL

La commande add-url est utilisée pour ajouter un fichier distant spécifié par une URL source en tant que référence Protobuf. Un chemin de fichier doit être fourni pour spécifier où télécharger le fichier distant. Le chemin de fichier peut être un chemin relatif au répertoire actuel ou un chemin absolu. Si le chemin de fichier est en dehors du répertoire du projet, un élément Link est ajouté pour afficher le fichier sous le dossier virtuel Protos dans Visual Studio.

Utilisation

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

Arguments

Argument Description
url URL d’un fichier Protobuf distant.

Options

Option courte Option longue Description
-o --output Spécifie le chemin de téléchargement du fichier Protobuf distant. C'est une option obligatoire.
-p --project Chemin d’accès au fichier projet à traiter. Si aucun fichier n’est spécifié, la commande effectue une recherche dans le répertoire actif.
-s --services Type des services gRPC qui doivent être générés. Si Default est spécifié, Both est utilisé pour les projets Web et Client est utilisé pour les projets non basés sur le web. Les valeurs acceptées sont Both, Client, Default, None, Server.
-i --additional-import-dirs Répertoires supplémentaires à utiliser lors de la résolution des importations pour les fichiers Protobuf. Il s’agit d’une liste de chemins séparés par des points-virgules.
--access Modificateur d’accès à utiliser pour les classes C# générées. La valeur par défaut est Public. Les valeurs acceptées sont Internal et Public.

Remove

La commande remove est utilisée pour supprimer les références Protobuf du fichier .csproj. La commande accepte les arguments de chemin d’accès et les URL sources en tant qu’arguments. L’outil  :

  • Supprime uniquement la référence Protobuf.
  • Ne supprime pas le fichier .proto, même s’il a été téléchargé à l’origine à partir d’une URL distante.

Utilisation

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

Arguments

Argument Description
références URL ou chemins de fichier des références Protobuf à supprimer.

Options

Option courte Option longue Description
-p --project Chemin d’accès au fichier projet à traiter. Si aucun fichier n’est spécifié, la commande effectue une recherche dans le répertoire actif.

Actualiser

La commande refresh est utilisée pour mettre à jour une référence distante avec le contenu le plus récent de l’URL source. Le chemin de fichier de téléchargement et l’URL source peuvent être utilisés pour spécifier la référence à mettre à jour. Remarque :

  • Les hachages du contenu du fichier sont comparés pour déterminer si le fichier local doit être mis à jour.
  • Aucune information d’horodatage n’est comparée.

L’outil remplace toujours le fichier local par le fichier distant si une mise à jour est nécessaire.

Utilisation

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

Arguments

Argument Description
références URL ou chemins de fichier vers des références Protobuf distantes qui doivent être mises à jour. Laissez cet argument vide pour actualiser toutes les références distantes.

Options

Option courte Option longue Description
-p --project Chemin d’accès au fichier projet à traiter. Si aucun fichier n’est spécifié, la commande effectue une recherche dans le répertoire actif.
--dry-run Génère la liste des fichiers qui seraient mis à jour sans télécharger de nouveau contenu.

Liste

La commande list est utilisée pour afficher toutes les références Protobuf dans le fichier projet. Si toutes les valeurs d’une colonne sont des valeurs par défaut, la colonne peut être omise.

Utilisation

dotnet-grpc list [options]

Options

Option courte Option longue Description
-p --project Chemin d’accès au fichier projet à traiter. Si aucun fichier n’est spécifié, la commande effectue une recherche dans le répertoire actif.

Ressources supplémentaires