Tutorial: Erstellen eines gRPC-Clients und -Servers in ASP.NET Core

In diesem Lernprogramm wird gezeigt, wie Sie einen .NET Core gRPC-Client und einen ASP.NET Core gRPC Server erstellen. Das Ziel ist ein gRPC-Client, der mit dem gRPC-Greeter-Dienst kommuniziert.

In diesem Tutorial:

• Erstellen Sie einen gRPC-Server.
• Erstellen Sie einen gRPC-Client.
• Testen Sie den gRPC-Client mit dem gRPC-Greeter-Dienst.

Voraussetzungen

Visual Studio

• Visual Studio 2022 mit ASP.NET - und Webentwicklungsworkload .

  

Visual Studio Code

• Visual Studio Code
• C# Dev Kit für Visual Studio Code
• .NET 9 SDK

Sie können den Visual Studio Code-Anweisungen unter macOS, Linux oder Windows folgen. Änderungen können erforderlich sein, wenn Sie eine andere integrierte Entwicklungsumgebung (Integrated Development Environment, IDE) als Visual Studio Code verwenden.

Erstellen eines gRPC-Diensts

Visual Studio

• Starten Sie Visual Studio 2022, und wählen Sie "Neues Projekt" aus.
• Suchen Sie im Dialogfeld " Neues Projekt erstellen" nach gRPC. Wählen Sie ASP.NET Core gRPC Service aus, und wählen Sie "Weiter" aus.
• Geben Sie im Dialogfeld "GrpcGreeter" den Namen des Projekts ein. Es ist wichtig, das Projekt GrpcGreeter zu benennen, damit die Namespaces übereinstimmen, wenn Sie Code kopieren und einfügen.
• Wählen Sie "Weiter" aus.
• Wählen Sie im Dialogfeld "Zusätzliche Informationen " .NET 9.0 (Standard Term Support) und dann "Erstellen" aus.

Visual Studio Code

Das Tutorial setzt voraus, dass Sie mit Visual Studio Code vertraut sind. Weitere Informationen finden Sie unter "Erste Schritte mit VS Code".

• Wählen Sie im Menü"Terminal" die Option "Neues Terminal" aus, um das integrierte Terminal zu öffnen.

• Wechseln Sie zu dem Verzeichnis (cd), in dem Projekt enthalten sein soll.

• Führen Sie die folgenden Befehle aus:

  dotnet new grpc -o GrpcGreeter
  code -r GrpcGreeter
  

  Der dotnet new Befehl erstellt einen neuen gRPC-Dienst im Ordner "GrpcGreeter ".

  Der code Befehl öffnet den Ordner "GrpcGreeter "-Projekt in der aktuellen Instanz von Visual Studio Code.

Visual Studio Code zeigt möglicherweise ein Dialogfeld an, in dem Sie gefragt werden: Vertrauen Sie den Autoren der Dateien in diesem Ordner?

• Wenn Sie allen Dateien im übergeordneten Ordner vertrauen, wählen Sie " Vertrauen" für die Autoren aller Dateien im übergeordneten Ordner aus.
• Wählen Sie "Ja" aus, ich vertraue den Autoren, da der Projektordner Dateien von .NET generiert hat.
• Wenn Visual Studio Code anfordert, Ressourcen zum Erstellen und Debuggen des Projekts hinzuzufügen, wählen Sie "Ja" aus. Wenn Visual Studio Code nicht auffordert, Build- und Debug-Assets hinzuzufügen, wählen Sie Ansicht>Befehlspalette und geben Sie ".NET" in das Suchfeld ein. Wählen Sie in der Liste der Befehle den Befehl .NET: Generate Assets for Build and Debug aus.

Visual Studio Code fügt einen .vscode-Ordner mit den generierten launch.json- und tasks.json-Dateien hinzu.

Ausführen des Diensts

Visual Studio

• Drücken Sie STRG+F5, um die Ausführung ohne den Debugger zu starten.

  Visual Studio zeigt das folgende Dialogfeld an, wenn ein Projekt noch nicht für die Verwendung von SSL konfiguriert ist:

  

  Wählen Sie "Ja " aus, wenn Sie dem IIS Express-SSL-Zertifikat vertrauen.

  Das folgende Dialogfeld wird angezeigt:

  

  Wählen Sie "Ja " aus, wenn Sie dem Entwicklungszertifikat vertrauen möchten.

  Informationen zum Vertrauen in den Firefox-Browser finden Sie unter Firefox SEC_ERROR_INADEQUATE_KEY_USAGE Zertifikatfehler.

  Visual Studio:

  • Startet den Kestrel-Server.
  • Startet einen Browser.
  • Navigiert zu http://localhost:port, z. B. http://localhost:7042.
    • Port: Eine zufällig zugewiesene Portnummer für die App.
    • localhost: Der Standardhostname für den lokalen Computer. „Localhost“ dient nur Webanforderungen vom lokalen Computer.

Visual Studio Code

• Vertrauen Sie dem HTTPS-Entwicklungszertifikat, indem Sie den folgenden Befehl ausführen:

  dotnet dev-certs https --trust
  

  Der vorherige Befehl zeigt das folgende Dialogfeld an, sofern das Zertifikat nicht zuvor schon als vertrauenswürdig eingestuft wurde:

  

• Wählen Sie "Ja " aus, wenn Sie dem Entwicklungszertifikat vertrauen möchten.

  Weitere Informationen finden Sie im Abschnitt „Das Entwicklungssicherheitszertifikat von ASP.NET Core vertrauen“ des Artikels „SSL erzwingen“.

Informationen zum Vertrauen in den Firefox-Browser finden Sie unter Firefox SEC_ERROR_INADEQUATE_KEY_USAGE Zertifikatfehler.

• Drücken Sie STRG-F5 , um ohne den Debugger auszuführen.

  Visual Studio Code:

  • Startet den Kestrel-Server.
  • Startet einen Browser.
  • Navigiert zu http://localhost:port, z. B. http://localhost:7042.
    • Port: Eine zufällig zugewiesene Portnummer für die App.
    • localhost: Der Standardhostname für den lokalen Computer. „Localhost“ dient nur Webanforderungen vom lokalen Computer.

Die Protokolle zeigen den Dienst an, der an https://localhost:<port> lauscht, wobei <port> die Portnummer von localhost ist, die bei der Erstellung des Projekts zufällig zugewiesen und in Properties/launchSettings.json festgelegt wurde.

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:<port>
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Hinweis

Die gRPC-Vorlage ist für die Verwendung von Transport Layer Security (TLS) konfiguriert. gRPC-Clients müssen zum Aufrufen des Servers HTTPS verwenden. Die gRPC-Dienst-Localhost-Portnummer wird zufällig zugewiesen, wenn das Projekt erstellt und im Eigenschaften-\launchSettings.jsfür die Datei des gRPC-Dienstprojekts festgelegt wird.

Überprüfen der Projektdateien

GrpcGreeter-Projektdateien :

• Protos/greet.proto: definiert den Greeter-gRPC und generiert die gRPC-Serverobjekte. Weitere Informationen finden Sie in der Einführung in gRPC.
• Ordner Services: enthält die Implementierung des Diensts Greeter.
• appSettings.json: enthält Konfigurationsdaten, z. B. das von Kestrel verwendete Protokoll. Weitere Informationen finden Sie unter Configuration in ASP.NET Core.
• Program.cs mit folgendem Inhalt:
  • Der Einstiegspunkt für den gRPC-Dienst. Weitere Informationen finden Sie unter .NET Generic Host in ASP.NET Core.
  • Der Code, mit dem das App-Verhalten konfiguriert wird. Weitere Informationen finden Sie im App-Start.

Erstellen des gRPC-Clients in einer .NET-Konsolen-App

Visual Studio

• Öffnen Sie eine zweite Instanz von Visual Studio, und wählen Sie "Neues Projekt" aus.
• Wählen Sie im Dialogfeld " Neues Projekt erstellen " die Option "Konsolen-App" und dann "Weiter" aus.
• Geben Sie im Textfeld "Projektname " "GrpcGreeterClient " ein, und wählen Sie "Weiter" aus.
• Wählen Sie im Dialogfeld "Zusätzliche Informationen " .NET 9.0 (Standard Term Support) und dann "Erstellen" aus.

Visual Studio Code

• Öffnen Sie das integrierte Terminal.

• Ändern Sie die Verzeichnisse (mit cd) in einen Ordner für das Projekt.

• Führen Sie die folgenden Befehle aus:

  dotnet new console -o GrpcGreeterClient
  code -r GrpcGreeterClient
  

Visual Studio Code zeigt möglicherweise ein Dialogfeld an, in dem Sie gefragt werden: Vertrauen Sie den Autoren der Dateien in diesem Ordner?

• Wenn Sie allen Dateien im übergeordneten Ordner vertrauen, wählen Sie " Vertrauen" für die Autoren aller Dateien im übergeordneten Ordner aus.
• Wählen Sie "Ja" aus, ich vertraue den Autoren, da der Projektordner Dateien von .NET generiert hat.
• Wenn Visual Studio Code anfordert, Ressourcen zum Erstellen und Debuggen des Projekts hinzuzufügen, wählen Sie "Ja" aus. Wenn Visual Studio Code nicht auffordert, Build- und Debug-Assets hinzuzufügen, wählen Sie Ansicht>Befehlspalette und geben Sie ".NET" in das Suchfeld ein. Wählen Sie in der Liste der Befehle den Befehl .NET: Generate Assets for Build and Debug aus.

Visual Studio Code fügt einen .vscode-Ordner mit den generierten launch.json- und tasks.json-Dateien hinzu.

Hinzufügen der erforderlichen NuGet-Pakete

Das gRPC-Clientprojekt erfordert die folgenden NuGet-Pakete:

• Grpc.Net.Client, das den .NET Core-Client enthält.
• Google.Protobuf, das protobuf-Nachrichten-APIs für C# enthält.
• Grpc.Tools, die C#-Toolunterstützung für Protobuf-Dateien enthalten. Das Toolpaket ist nicht zur Laufzeit erforderlich, darum ist die Abhängigkeit mit PrivateAssets="All" markiert.

Visual Studio

Installieren Sie die Pakete über die Paket-Manager-Konsole oder über „NuGet-Pakete verwalten“.

PMC-Option zum Installieren von Paketen

• Wählen Sie in Visual Studio Tools>NuGet-Paket-Manager>Paket-Manager-Konsole aus.

• Führen Sie im Paket-Manager-Konsolenfenster den Befehl cd GrpcGreeterClient aus, um zum Ordner mit den GrpcGreeterClient.csproj Dateien zu wechseln.

• Führen Sie die folgenden Befehle aus:

  Install-Package Grpc.Net.Client
  Install-Package Google.Protobuf
  Install-Package Grpc.Tools
  

Option „NuGet-Pakete verwalten“ zum Installieren von Paketen

• Klicken Sie mit der rechten Maustaste auf das Projekt im Projektmappen-Explorer>"NuGet-Pakete verwalten".
• Wählen Sie die Registerkarte " Durchsuchen" aus .
• Geben Sie Grpc.Net.Client in das Suchfeld ein.
• Wählen Sie das Grpc.Net.Client-Paket auf der Registerkarte " Durchsuchen " und dann "Installieren" aus.
• Führen Sie diese Aktionen auch für Google.Protobuf und Grpc.Tools durch.

Visual Studio Code

Führen Sie die folgenden Befehle aus dem integrierten Terminal aus:

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

Fügen Sie „greet.proto“ hinzu:

• Erstellen Sie einen Protos-Ordner im gRPC-Clientprojekt.

• Kopieren Sie die Datei "Protos\greet.proto " aus dem gRPC-Begrüßungsdienst in den Ordner "Protos " im gRPC-Clientprojekt.

• Ändern Sie den Namespace in der Datei greet.proto in den Namespace des Projekts:

  option csharp_namespace = "GrpcGreeterClient";
  

• Bearbeiten Sie die Projektdatei GrpcGreeterClient.csproj:

Visual Studio

Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie "Projektdatei bearbeiten" aus.

Visual Studio Code

Wählen Sie die Datei GrpcGreeterClient.csproj aus.

• Fügen Sie eine Elementgruppe mit einem <Protobuf> Element hinzu, das auf die Datei "greet.proto " verweist:

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

Erstellen des Greeter-Clients

• Erstellen Sie das Clientprojekt, um die Typen im GrpcGreeterClient-Namespace zu erstellen.

Hinweis

Die GrpcGreeterClient-Typen werden vom Buildprozess automatisch erstellt. Das Toolpaket Grpc.Tools generiert die folgenden Dateien basierend auf der Datei "greet.proto ":

• GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs: Der Protokollpuffercode, der die Anforderungs- und Antwortnachrichtentypen auffüllt, serialisiert und abruft.
• GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs: Enthält die erzeugten Clientklassen

Weitere Informationen zu den von Grpc.Tools automatisch generierten C#-Ressourcen finden Sie unter gRPC-Dienste mit C#: Generierte C#-Ressourcen.

• Aktualisieren Sie die Datei Program.cs des gRPC-Clients mit dem folgenden Code.

  using Grpc.Net.Client;
  using GrpcGreeterClient;
  
  // The port number must match the port of the gRPC server.
  using var channel = GrpcChannel.ForAddress("https://localhost:7042");
  var client = new Greeter.GreeterClient(channel);
  var reply = await client.SayHelloAsync(
      new HelloRequest { Name = "GreeterClient" });
  Console.WriteLine("Greeting: " + reply.Message);
  Console.WriteLine("Press any key to exit...");
  Console.ReadKey();
  

• Ersetzen Sie im oben hervorgehobenen Code die Portnummer 7042 von localhost durch die in HTTPS angegebene Portnummer Properties/launchSettings.json innerhalb des Dienstprojekts GrpcGreeter.

Program.cs enthält den Einstiegspunkt und die Logik für den gRPC-Client.

Der Greeter-Client wird folgendermaßen erstellt:

• Instanziieren eines GrpcChannel-Objekts, das Informationen zum Herstellen einer Verbindung mit dem gRPC-Dienst enthält
• Verwenden von GrpcChannel zum Erstellen des Greeter-Clients:

// The port number must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:7042");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
    new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();

Der Greeter-Client ruft die asynchrone Methode SayHello auf. Das Ergebnis des Aufrufs von SayHello wird angezeigt:

// The port number must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:7042");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
    new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();

Testen des gRPC-Clients mit dem gRPC-Greeter-Dienst

Aktualisieren Sie die Datei appsettings.Development.json, indem Sie die folgenden hervorgehobenen Zeilen hinzufügen:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.AspNetCore.Hosting": "Information",
      "Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"
    }
  }
}

Visual Studio

• Drücken Sie im GrpcGreeter-Dienstprojekt Ctrl+F5, um den Server ohne den Debugger zu starten.
• Drücken Sie im GrpcGreeterClient Konsolenprojekt Ctrl+F5, um den Client ohne den Debugger zu starten.

Visual Studio Code

• Starten Sie den Greeterdienst.
• Starten Sie den Client.

Der Client sendet eine Begrüßung an den Dienst mit einer Nachricht, die den Namen GreeterClient enthält. Der Dienst gibt als Antwort die Meldung „Hello GreeterClient“ aus. Die Antwort „Hello GreeterClient“ wird in der Eingabeaufforderung angezeigt:

Greeting: Hello GreeterClient
Press any key to exit...

Der gRPC-Dienst zeichnet die Details des erfolgreichen Aufrufs in den Protokollen auf, die an die Eingabeaufforderung ausgegeben werden:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:<port>
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\GH\aspnet\docs\4\Docs\aspnetcore\tutorials\grpc\grpc-start\sample\GrpcGreeter
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 POST https://localhost:<port>/greet.Greeter/SayHello application/grpc
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished HTTP/2 POST https://localhost:7042/greet.Greeter/SayHello - 200 - application/grpc 40.4615ms

Hinweis

Der Code in diesem Artikel erfordert das ASP.NET Core-HTTPS-Entwicklungszertifikat, um den gRPC-Dienst zu sichern. Wenn auf dem .NET gRPC-Client ein Fehler mit der Meldung The remote certificate is invalid according to the validation procedure. oder The SSL connection could not be established. auftritt, wird das Entwicklungszertifikat als nicht vertrauenswürdig eingestuft. Um dieses Problem zu beheben, lesen Sie Aufrufen eines gRPC-Dienstes mit einem nicht vertrauenswürdigen/ungültigen Zertifikat.

Nächste Schritte

• Anzeigen oder Herunterladen des vollständigen Beispielcodes für dieses Lernprogramm (herunterladen).
• Übersicht für gRPC unter .NET
• gRPC-Dienste mit C#
• Migrieren von gRPC von C-Core zu gRPC für .NET