Testen von gRPC-Diensten mit gRPCurl und gRPCui in ASP.NET Core

Von James Newton-King

Für gRPC sind Tools verfügbar, mit deren Hilfe Entwickler Dienste testen können, ohne Client-Apps zu erstellen:

• gRPCurl ist ein Open-Source-Befehlszeilentool, das Interaktionen mit gRPC-Diensten ermöglicht.
• gRPCui baut auf gRPCurl auf und verfügt zusätzlich über eine interaktive Open-Source-Webbenutzeroberfläche für gRPC.

In diesem Artikel wird Folgendes erläutert:

• Einrichten der gRPC-Serverreflexion mit einer gRPC-ASP.NET Core-App
• Interagieren mit gRPC mithilfe von Testtools:
  • Ermitteln und Testen von gRPC-Diensten mit grpcurl
  • Interagieren mit gRPC-Diensten über einen Browser mithilfe von grpcui

Hinweis

Informationen zum Komponententest von gRPC-Diensten finden Sie unter Testen von gRPC-Diensten in ASP.NET Core.

Einrichten von gRPC-Reflexion

Tools müssen den Protobuf-Vertrag für Dienste kennen, bevor diese aufgerufen werden können. Hierfür gibt es zwei Möglichkeiten:

• Richten Sie gRPC-Reflexion auf dem Server ein. Tools wie gRPCurl nutzen die Reflexion zum automatischen Ermitteln von Dienstverträgen.
• Fügen Sie dem Tool manuell .proto-Dateien hinzu.

Es ist einfacher, die gRPC-Reflexion zu verwenden. gRPC-Reflexion fügt der App einen neuen gRPC-Dienst hinzu, der von Clients zum Ermitteln von Diensten aufgerufen werden kann.

gRPC ASP.NET Core bietet mit dem Grpc.AspNetCore.Server.Reflection-Pakte integrierte Unterstützung für gRPC-Reflexion. So konfigurieren Sie die Reflexion in einer App:

• Fügen Sie einen Grpc.AspNetCore.Server.Reflection-Paketverweis hinzu.
• Registrieren Sie die Reflexion in Program.cs:
  • AddGrpcReflection zum Registrieren von Diensten, die die Reflexion ermöglichen
  • MapGrpcReflectionService zum Hinzufügen eines Dienstendpunkts der Reflexion.

builder.Services.AddGrpc();
builder.Services.AddGrpcReflection();

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

Wenn gRPC-Reflexion eingerichtet ist:

• Der Server-App wird ein gRPC-Reflexionsdienst hinzugefügt.
• Client-Apps, die gRPC-Reflexion unterstützen, können den Reflexionsdienst zum Ermitteln von vom Server gehosteten Diensten aufrufen.
• gRPC-Dienste werden weiterhin vom Client aufgerufen. Reflexion ermöglicht nur Dienstermittlung und umgeht nicht die serverseitige Sicherheit. Endpunkte, die durch Authentifizierung und Autorisierung geschützt sind, erfordern für einen erfolgreichen Aufruf, dass der Aufrufer Anmeldeinformationen für den Endpunkt übergibt.

Spiegelungsdienstsicherheit

gRPC-Spiegelung gibt eine Liste der verfügbaren APIs zurück, die vertrauliche Informationen enthalten können. Achten Sie darauf, den Zugang zum gRPC-Spiegelungsdienst zu beschränken.

gRPC-Spiegelung ist in der Regel nur in einer lokalen Entwicklungsumgebung erforderlich. Für die lokale Entwicklung sollte der Spiegelungsdienst nur zugeordnet werden, wenn IsDevelopment „WAHR“ zurückgibt:

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

Der Zugriff auf den Dienst kann über standardmäßige ASP.NET Core-Autorisierungserweiterungsmethoden wie z. B. AllowAnonymous und RequireAuthorization kontrolliert werden.

Wenn eine App beispielsweise standardmäßig so konfiguriert wurde, dass eine Autorisierung erforderlich ist, konfigurieren Sie den gRPC-Spiegelungsendpunkt mit AllowAnonymous, um die Authentifizierung und Autorisierung zu überspringen.

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService().AllowAnonymous();
}

gRPCurl

gRPCurl ist ein von der gRPC-Community erstelltes Befehlszeilentool. Es bietet folgende Features:

• Aufrufen von gRPC-Diensten wie Streamingdienste
• Dienstermittlung mithilfe der gRPC-Reflexion
• Auflisten und Beschreiben von gRPC-Diensten
• Kann mit sicheren Servern (TLS-Servern) und unsicheren (unverschlüsselten) Servern verwendet werden.

Informationen zum Herunterladen und Installieren von grpcurl finden Sie auf der gRPCurl-GitHub-Startseite.

Verwenden Sie grpcurl

Das Argument -help erläutert grpcurl-Befehlszeilenoptionen:

$ grpcurl -help

Ermitteln von Diensten

Verwenden Sie das Verb describe, um die vom Server definierten Dienste anzuzeigen. Geben Sie <port> als localhost-Portnummer des gRPC-Servers an. Die Portnummer wird nach dem Zufallsprinzip zugewiesen, wenn das Projekt erstellt wird, und ist in Properties/launchSettings.json festgelegt:

$ grpcurl localhost:<port> describe
greet.Greeter is a service:
service Greeter {
  rpc SayHello ( .greet.HelloRequest ) returns ( .greet.HelloReply );
  rpc SayHellos ( .greet.HelloRequest ) returns ( stream .greet.HelloReply );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
  rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}

Für das vorherige Beispiel gilt Folgendes:

• Führt das Verb describe auf Server localhost:<port> aus. Dabei wird <port> bei der Erstellung des gRPC-Serverprojekts nach dem Zufallsprinzip zugewiesen und ist in Properties/launchSettings.json festgelegt.
• Druckt von der gRPC-Reflexion zurückgegebene Dienste und Methoden.
  • Greeter ist ein von der App implementierter Dienst.
  • ServerReflection ist der vom Grpc.AspNetCore.Server.Reflection-Paket hinzugefügter Dienst.

Kombinieren Sie describe mit einem Dienst-, Methoden- oder Meldungsnamen, um die entsprechenden Details anzuzeigen:

$ grpcurl localhost:<port> describe greet.HelloRequest
greet.HelloRequest is a message:
message HelloRequest {
  string name = 1;
}

Aufrufen von gRPC-Diensten

Rufen Sie einen gRPC-Dienst auf, indem Sie einen Dienst- oder Methodennamen zusammen mit einem JSON-Argument angeben, das die Anforderungsnachricht darstellt. Der JSON-Code wird in Protobuf konvertiert und an den Dienst gesendet.

$ grpcurl -d '{ \"name\": \"World\" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

Im vorherigen Beispiel:

• Das Argument -d gibt eine Anforderungsnachricht mit JSON an. Dieses Argument muss vor der Serveradresse und dem Methodennamen angegeben werden.
• Ruft die SayHello-Methode für den greeter.Greeter-Dienst auf.
• Druckt die Antwortnachricht als JSON-Code.
• Dabei wird <port> bei der Erstellung des gRPC-Serverprojekts nach dem Zufallsprinzip zugewiesen und ist in Properties/launchSettings.json festgelegt.

Im vorherigen Beispiel wird \ verwendet, um das Zeichen " mit Escapezeichen zu versehen. Das Escapezeichen " ist in einer PowerShell-Konsole erforderlich, darf aber in einigen Konsolen nicht verwendet werden. Beispiel: Der vorherige Befehl für eine macOS-Konsole:

$ grpcurl -d '{ "name": "World" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

gRPCui

gRPCui ist eine interaktive Webbenutzeroberfläche für gRPC. gRPCui baut auf gRPCurl auf. gRPCui stellt eine grafische Benutzeroberfläche zum Ermitteln und Testen von gRPC-Diensten bereit – vergleichbar mit HTTP-Tools wie die Swagger-Benutzeroberfläche.

Informationen zum Herunterladen und Installieren von grpcui finden Sie auf der gRPCui-GitHub-Startseite.

Verwenden von grpcui

Führen Sie grpcui mit der Serveradresse aus, mit der als Argument interagiert wird:

$ grpcui localhost:<port>
gRPC Web UI available at http://127.0.0.1:55038/

Geben Sie im vorherigen Beispiel <port> als die Localhost-Portnummer des gRPC-Servers an. Die Portnummer wird nach dem Zufallsprinzip zugewiesen, wenn das Projekt erstellt wird, und ist in Properties/launchSettings.json festgelegt.

Das Tool startet ein Browserfenster mit der interaktiven Weboberfläche. gRPC-Dienste werden mithilfe der gRPC-Reflexion automatisch ermittelt.

Zusätzliche Ressourcen

• gRPCurl-GitHub-Startseite
• gRPCui-GitHub-Startseite
• Grpc.AspNetCore.Server.Reflection
• Testen von gRPC-Diensten in ASP.NET Core
• Simulieren des gRPC-Clients in Tests