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

  • Artikel

In diesem Tutorial erfahren Sie, wie Sie einen .NET Core-gRPC-Client und einen ASP.NET Core-gRPC-Server erstellen können. 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

Erstellen eines gRPC-Diensts

  • 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-Dienst und dann Weiter aus.
  • Geben Sie GrpcGreeter im Dialogfeld Neues Projekt konfigurieren für Projektname ein. Es ist wichtig, den Namen GrpcGreeter zu verwenden, damit die Namespaces übereinstimmen, wenn Sie Code kopieren und einfügen.
  • Wählen Sie Weiter aus.
  • Wählen Sie im Dialogfeld Zusätzliche Informationen die Option .NET 8.0 (Langfristiger Support) und dann Erstellen aus.

Ausführen des Diensts

  • 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:

    Dieses Projekt ist für die Verwendung von SSL konfiguriert. Um SSL-Warnungen im Browser zu vermeiden, können Sie dem selbstsignierten Zertifikat vertrauen, das IIS Express generiert hat. Möchten Sie dem SSL-Zertifikat von IIS Express vertrauen?

    Wählen Sie Ja aus, wenn Sie dem IIS Express-SLL-Zertifikat vertrauen möchten.

    Das folgende Dialogfeld wird angezeigt:

    Dialogfeld „Sicherheitswarnung“

    Klicken Sie auf Ja, wenn Sie zustimmen möchten, dass das Entwicklungszertifikat vertrauenswürdig ist.

    Informationen dazu, wie Sie dem Firefox-Browser vertrauen, finden Sie unter Firefox-Zertifikatfehler SEC_ERROR_INADEQUATE_KEY_USAGE.

    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.

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 Localhost-Portnummer des gRPC-Diensts wird nach dem Zufallsprinzip zugewiesen, wenn das Projekt erstellt und in der Datei Properties\launchSettings.json 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 unter Einführung in gRPC in ASP.NET Core.
  • 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 Konfiguration in ASP.NET Core.
  • Program.cs mit folgendem Inhalt:

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

  • Ö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 aus, und klicken Sie auf Weiter.
  • Geben Sie im Textfeld Projektname den Namen GrpcGreeterClient ein, und klicken Sie auf Weiter.
  • Wählen Sie im Dialogfeld Zusätzliche Informationen die Option .NET 8.0 (Langfristiger Support) und dann Erstellen aus.

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 die Protobuf-Nachrichten-APIs für C# enthält.
  • Grpc.Tools, das C#-Toolunterstützung für Protobuf-Dateien enthält. Das Toolpaket ist nicht zur Laufzeit erforderlich, darum ist die Abhängigkeit mit PrivateAssets="All" markiert.

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 Fenster Paket-Manager-Konsole den Befehl cd GrpcGreeterClient aus, um zu dem Verzeichnis zu wechseln, in dem sich die GrpcGreeterClient.csproj-Dateien befinden.

  • 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 unter Projektmappen-Explorer>NuGet-Pakete verwalten auf Ihr Projekt.
  • Wählen Sie die Registerkarte Durchsuchen aus.
  • Geben Sie Grpc.Net.Client in das Suchfeld ein.
  • Wählen Sie das Paket Grpc.Net.Client auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.
  • Führen Sie diese Aktionen auch für Google.Protobuf und Grpc.Tools durch.

Fügen Sie „greet.proto“ hinzu:

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

  • Kopieren Sie die Datei Protos\greet.proto aus dem gRPC-Greeter-Dienst 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:

Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Projektdatei bearbeiten 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 greet.proto Datei:

  • 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 System.Threading.Tasks;
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 Properties/launchSettings.json angegebene Portnummer HTTPS 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"
    }
  }
}
  • Drücken Sie im Greeterdienst Ctrl+F5, um den Server ohne Debugger zu starten.
  • Drücken Sie im GrpcGreeterClient-Projekt Ctrl+F5, um den Client ohne den Debugger zu starten.

Der Client sendet eine Begrüßungsnachricht an den Dienst, die den Namen des Diensts enthält: GreeterClient. 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 in 78.32260000000001ms 200 application/grpc

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. Informationen zum Beheben dieses Problems finden Sie unter Aufrufen eines gRPC-Diensts mit einem nicht vertrauenswürdigen/ungültigen Zertifikat.

Nächste Schritte

In diesem Tutorial erfahren Sie, wie Sie einen .NET Core-gRPC-Client und einen ASP.NET Core-gRPC-Server erstellen können. 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

Erstellen eines gRPC-Diensts

  • Starten Sie Visual Studio 2022, und wählen Sie Neues Projekt erstellen aus.
  • Suchen Sie im Dialogfeld Neues Projekt erstellen nach gRPC. Wählen Sie ASP.NET Core gRPC-Dienst und dann Weiter aus.
  • Geben Sie GrpcGreeter im Dialogfeld Neues Projekt konfigurieren für Projektname ein. Es ist wichtig, den Namen GrpcGreeter zu verwenden, damit die Namespaces übereinstimmen, wenn Sie Code kopieren und einfügen.
  • Wählen Sie Weiter aus.
  • Wählen Sie im Dialogfeld Zusätzliche Informationen die Option .NET 6.0 (Langfristiger Support) und dann Erstellen aus.

Ausführen des Diensts

  • 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:

    Dieses Projekt ist für die Verwendung von SSL konfiguriert. Um SSL-Warnungen im Browser zu vermeiden, können Sie dem selbstsignierten Zertifikat vertrauen, das IIS Express generiert hat. Möchten Sie dem SSL-Zertifikat von IIS Express vertrauen?

    Wählen Sie Ja aus, wenn Sie dem IIS Express-SLL-Zertifikat vertrauen möchten.

    Das folgende Dialogfeld wird angezeigt:

    Dialogfeld „Sicherheitswarnung“

    Klicken Sie auf Ja, wenn Sie zustimmen möchten, dass das Entwicklungszertifikat vertrauenswürdig ist.

    Informationen dazu, wie Sie dem Firefox-Browser vertrauen, finden Sie unter Firefox-Zertifikatfehler SEC_ERROR_INADEQUATE_KEY_USAGE.

    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.

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 Localhost-Portnummer des gRPC-Diensts wird nach dem Zufallsprinzip zugewiesen, wenn das Projekt erstellt und in der Datei Properties\launchSettings.json des gRPC-Dienstprojekts festgelegt wird.

macOS unterstützt ASP.NET Core gRPC mit TLS nicht. Zum erfolgreichen Ausführen von gRPC-Diensten unter macOS ist eine zusätzliche Konfiguration erforderlich. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.

Überprüfen der Projektdateien

GrpcGreeter-Projektdateien:

  • Protos/greet.proto: definiert den Greeter-gRPC und generiert die gRPC-Serverobjekte. Weitere Informationen finden Sie unter Einführung in gRPC in ASP.NET Core.
  • 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 Konfiguration in ASP.NET Core.
  • Program.cs mit folgendem Inhalt:

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

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

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 die Protobuf-Nachrichten-APIs für C# enthält.
  • Grpc.Tools, das C#-Toolunterstützung für Protobuf-Dateien enthält. Das Toolpaket ist nicht zur Laufzeit erforderlich, darum ist die Abhängigkeit mit PrivateAssets="All" markiert.

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 Fenster Paket-Manager-Konsole den Befehl cd GrpcGreeterClient aus, um zu dem Verzeichnis zu wechseln, in dem sich die GrpcGreeterClient.csproj-Dateien befinden.

  • 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 unter Projektmappen-Explorer>NuGet-Pakete verwalten auf Ihr Projekt.
  • Wählen Sie die Registerkarte Durchsuchen aus.
  • Geben Sie Grpc.Net.Client in das Suchfeld ein.
  • Wählen Sie das Paket Grpc.Net.Client auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.
  • Führen Sie diese Aktionen auch für Google.Protobuf und Grpc.Tools durch.

Fügen Sie „greet.proto“ hinzu:

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

  • Kopieren Sie die Datei Protos\greet.proto aus dem gRPC-Greeter-Dienst 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:

Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Projektdatei bearbeiten 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 greet.proto Datei:

  • 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 System.Threading.Tasks;
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 Properties/launchSettings.json angegebene Portnummer HTTPS 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"
    }
  }
}
  • Drücken Sie im Greeterdienst Ctrl+F5, um den Server ohne Debugger zu starten.
  • Drücken Sie im GrpcGreeterClient-Projekt Ctrl+F5, um den Client ohne den Debugger zu starten.

Der Client sendet eine Begrüßungsnachricht an den Dienst, die den Namen des Diensts enthält: GreeterClient. 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 in 78.32260000000001ms 200 application/grpc

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. Informationen zum Beheben dieses Problems finden Sie unter Aufrufen eines gRPC-Diensts mit einem nicht vertrauenswürdigen/ungültigen Zertifikat.

Nächste Schritte

In diesem Tutorial erfahren Sie, wie Sie einen .NET Core-gRPC-Client und einen ASP.NET Core-gRPC-Server erstellen können. 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

Erstellen eines gRPC-Diensts

  • Starten Sie Visual Studio 2022, und wählen Sie Neues Projekt erstellen aus.
  • Suchen Sie im Dialogfeld Neues Projekt erstellen nach gRPC. Wählen Sie ASP.NET Core gRPC-Dienst und dann Weiter aus.
  • Geben Sie GrpcGreeter im Dialogfeld Neues Projekt konfigurieren für Projektname ein. Es ist wichtig, den Namen GrpcGreeter zu verwenden, damit die Namespaces übereinstimmen, wenn Sie Code kopieren und einfügen.
  • Wählen Sie Weiter aus.
  • Wählen Sie im Dialogfeld Zusätzliche Informationen die Option .NET 6.0 (Langfristiger Support) und dann Erstellen aus.

Ausführen des Diensts

  • 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:

    Dieses Projekt ist für die Verwendung von SSL konfiguriert. Um SSL-Warnungen im Browser zu vermeiden, können Sie dem selbstsignierten Zertifikat vertrauen, das IIS Express generiert hat. Möchten Sie dem SSL-Zertifikat von IIS Express vertrauen?

    Wählen Sie Ja aus, wenn Sie dem IIS Express-SLL-Zertifikat vertrauen möchten.

    Das folgende Dialogfeld wird angezeigt:

    Dialogfeld „Sicherheitswarnung“

    Klicken Sie auf Ja, wenn Sie zustimmen möchten, dass das Entwicklungszertifikat vertrauenswürdig ist.

    Informationen dazu, wie Sie dem Firefox-Browser vertrauen, finden Sie unter Firefox-Zertifikatfehler SEC_ERROR_INADEQUATE_KEY_USAGE.

    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.

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 Localhost-Portnummer des gRPC-Diensts wird nach dem Zufallsprinzip zugewiesen, wenn das Projekt erstellt und in der Datei Properties\launchSettings.json des gRPC-Dienstprojekts festgelegt wird.

macOS unterstützt ASP.NET Core gRPC mit TLS nicht. Zum erfolgreichen Ausführen von gRPC-Diensten unter macOS ist eine zusätzliche Konfiguration erforderlich. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.

Überprüfen der Projektdateien

GrpcGreeter-Projektdateien:

  • Protos/greet.proto: definiert den Greeter-gRPC und generiert die gRPC-Serverobjekte. Weitere Informationen finden Sie unter Einführung in gRPC in ASP.NET Core.
  • 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 Konfiguration in ASP.NET Core.
  • Program.cs mit folgendem Inhalt:

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

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

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 die Protobuf-Nachrichten-APIs für C# enthält.
  • Grpc.Tools, das C#-Toolunterstützung für Protobuf-Dateien enthält. Das Toolpaket ist nicht zur Laufzeit erforderlich, darum ist die Abhängigkeit mit PrivateAssets="All" markiert.

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 Fenster Paket-Manager-Konsole den Befehl cd GrpcGreeterClient aus, um zu dem Verzeichnis zu wechseln, in dem sich die GrpcGreeterClient.csproj-Dateien befinden.

  • 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 unter Projektmappen-Explorer>NuGet-Pakete verwalten auf Ihr Projekt.
  • Wählen Sie die Registerkarte Durchsuchen aus.
  • Geben Sie Grpc.Net.Client in das Suchfeld ein.
  • Wählen Sie das Paket Grpc.Net.Client auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.
  • Führen Sie diese Aktionen auch für Google.Protobuf und Grpc.Tools durch.

Fügen Sie „greet.proto“ hinzu:

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

  • Kopieren Sie die Datei Protos\greet.proto aus dem gRPC-Greeter-Dienst 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:

Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Projektdatei bearbeiten 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 greet.proto Datei:

  • 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 System.Threading.Tasks;
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 Properties/launchSettings.json angegebene Portnummer HTTPS 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

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

Der Client sendet eine Begrüßungsnachricht an den Dienst, die den Namen des Diensts enthält: GreeterClient. 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 in 78.32260000000001ms 200 application/grpc

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

"Microsoft.AspNetCore.Hosting": "Information",
"Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"

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. Informationen zum Beheben dieses Problems finden Sie unter Aufrufen eines gRPC-Diensts mit einem nicht vertrauenswürdigen/ungültigen Zertifikat.

Nächste Schritte

In diesem Tutorial erfahren Sie, wie Sie einen .NET Core-gRPC-Client und einen ASP.NET Core-gRPC-Server erstellen können.

Das Ziel ist ein gRPC-Client, der mit dem gRPC-Greeter-Dienst kommuniziert.

Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).

In diesem Tutorial:

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

Voraussetzungen

Erstellen eines gRPC-Diensts

  • Starten Sie Visual Studio, und wählen Sie Neues Projekt erstellen aus.
  • Wählen Sie im Dialogfeld Neues Projekt erstellen die Option gRPC-Dienst aus, und klicken Sie auf Weiter.
  • Geben Sie GrpcGreeter im Dialogfeld Neues Projekt konfigurieren für Projektname ein. Es ist wichtig, den Namen GrpcGreeter zu verwenden, damit die Namespaces übereinstimmen, wenn Sie Code kopieren und einfügen.
  • Wählen Sie Weiter aus.
  • Wählen Sie im Dialogfeld Zusätzliche Informationen die Option .NET 5.0 aus der Dropdownliste Zielframework aus.
  • Wählen Sie Erstellen aus.

Ausführen des Diensts

  • 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:

    Dieses Projekt ist für die Verwendung von SSL konfiguriert. Um SSL-Warnungen im Browser zu vermeiden, können Sie dem selbstsignierten Zertifikat vertrauen, das IIS Express generiert hat. Möchten Sie dem SSL-Zertifikat von IIS Express vertrauen?

    Wählen Sie Ja aus, wenn Sie dem IIS Express-SLL-Zertifikat vertrauen möchten.

    Das folgende Dialogfeld wird angezeigt:

    Dialogfeld „Sicherheitswarnung“

    Klicken Sie auf Ja, wenn Sie zustimmen möchten, dass das Entwicklungszertifikat vertrauenswürdig ist.

    Informationen dazu, wie Sie dem Firefox-Browser vertrauen, finden Sie unter Firefox-Zertifikatfehler SEC_ERROR_INADEQUATE_KEY_USAGE.

    Visual Studio startet IIS Express und führt die App aus. Die Adressleiste zeigt localhost:port# an, nicht example.com. Das liegt daran, dass es sich bei localhost um den Standardhostnamen für den lokalen Computer handelt. „Localhost“ dient nur Webanforderungen vom lokalen Computer. Wenn in Visual Studio ein Webprojekt erstellt wird, wird für den Webserver ein zufälliger Port verwendet.

In den Protokollen wird vermerkt, dass der Dienst auf https://localhost:5001 lauscht.

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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.

macOS unterstützt ASP.NET Core gRPC mit TLS nicht. Zum erfolgreichen Ausführen von gRPC-Diensten unter macOS ist eine zusätzliche Konfiguration erforderlich. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.

Überprüfen der Projektdateien

GrpcGreeter-Projektdateien:

  • greet.proto: Mit der Datei Protos/greet.proto werden der Greeter-gRPC-Dienst definiert und die gRPC-Serverobjekte generiert. Weitere Informationen finden Sie unter Einführung in gRPC in ASP.NET Core.
  • Services-Ordner: Dieser enthält die Implementierung des Greeter-Diensts.
  • appsettings.json: Enthält Konfigurationsdaten, etwa das von Kestrel verwendete Protokoll. Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.
  • Program.cs: enthält den Einstiegspunkt für den gRPC-Dienst. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core.
  • Startup.cs: Enthält Code, mit dem das App-Verhalten konfiguriert wird. Weitere Informationen finden Sie unter App-Start.

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

  • Öffnen Sie eine zweite Instanz von Visual Studio, und wählen Sie Neues Projekt erstellen aus.
  • Wählen Sie im Dialogfeld Neues Projekt erstellen die Option Konsolen-App (.NET Core) aus, und klicken Sie auf Weiter.
  • Geben Sie im Textfeld Projektname den Namen GrpcGreeterClient ein, und klicken Sie auf Erstellen.

Hinzufügen von erforderlichen Paketen

Das gRPC-Clientprojekt erfordert die folgenden Pakete:

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

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 Fenster Paket-Manager-Konsole den Befehl cd GrpcGreeterClient aus, um zu dem Verzeichnis zu wechseln, in dem sich die GrpcGreeterClient.csproj-Dateien befinden.

  • 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 unter Projektmappen-Explorer>NuGet-Pakete verwalten auf Ihr Projekt.
  • Wählen Sie die Registerkarte Durchsuchen aus.
  • Geben Sie Grpc.Net.Client in das Suchfeld ein.
  • Wählen Sie das Paket Grpc.Net.Client auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.
  • Führen Sie diese Aktionen auch für Google.Protobuf und Grpc.Tools durch.

Fügen Sie „greet.proto“ hinzu:

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

  • Kopieren Sie die Datei Protos\greet.proto aus dem gRPC-Greeter-Dienst 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:

    Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Projektdatei bearbeiten 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 greet.proto Datei:

  • 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 System;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // The port number(5001) must match the port of the gRPC server.
            using var channel = GrpcChannel.ForAddress("https://localhost:5001");
            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();
        }
    }
}

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:
static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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

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

Der Client sendet eine Begrüßungsnachricht an den Dienst, die den Namen des Diensts enthält: GreeterClient. 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:5001
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:5001/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 in 78.32260000000001ms 200 application/grpc

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. Informationen zum Beheben dieses Problems finden Sie unter Aufrufen eines gRPC-Diensts mit einem nicht vertrauenswürdigen/ungültigen Zertifikat.

Nächste Schritte

In diesem Tutorial erfahren Sie, wie Sie einen .NET Core-gRPC-Client und einen ASP.NET Core-gRPC-Server erstellen können.

Das Ziel ist ein gRPC-Client, der mit dem gRPC-Greeter-Dienst kommuniziert.

Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).

In diesem Tutorial:

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

Voraussetzungen

Erstellen eines gRPC-Diensts

  • Starten Sie Visual Studio, und wählen Sie Neues Projekt erstellen aus. Alternativ dazu können Sie auch im Visual Studio-Menü Datei auf Neu>Projekt klicken.

  • Wählen Sie im Dialogfeld Neues Projekt erstellen die Option gRPC-Dienst aus, und klicken Sie auf Weiter:

    Dialogfeld „Neues Projekt erstellen“ in Visual Studio

  • Nennen Sie das Projekt GrpcGreeter. Es ist wichtig, den Namen GrpcGreeter zu verwenden, damit die Namespaces übereinstimmen, wenn Sie Code kopieren und einfügen.

  • Wählen Sie Erstellen aus.

  • Im Dialogfeld Neuen gRPC-Dienst erstellen:

    • Die gRPC-Dienst ist ausgewählt.
    • Wählen Sie Erstellen aus.

Ausführen des Diensts

  • 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:

    Dieses Projekt ist für die Verwendung von SSL konfiguriert. Um SSL-Warnungen im Browser zu vermeiden, können Sie dem selbstsignierten Zertifikat vertrauen, das IIS Express generiert hat. Möchten Sie dem SSL-Zertifikat von IIS Express vertrauen?

    Wählen Sie Ja aus, wenn Sie dem IIS Express-SLL-Zertifikat vertrauen möchten.

    Das folgende Dialogfeld wird angezeigt:

    Dialogfeld „Sicherheitswarnung“

    Klicken Sie auf Ja, wenn Sie zustimmen möchten, dass das Entwicklungszertifikat vertrauenswürdig ist.

    Informationen dazu, wie Sie dem Firefox-Browser vertrauen, finden Sie unter Firefox-Zertifikatfehler SEC_ERROR_INADEQUATE_KEY_USAGE.

    Visual Studio startet IIS Express und führt die App aus. Die Adressleiste zeigt localhost:port# an, nicht example.com. Das liegt daran, dass es sich bei localhost um den Standardhostnamen für den lokalen Computer handelt. „Localhost“ dient nur Webanforderungen vom lokalen Computer. Wenn in Visual Studio ein Webprojekt erstellt wird, wird für den Webserver ein zufälliger Port verwendet.

In den Protokollen wird vermerkt, dass der Dienst auf https://localhost:5001 lauscht.

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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.

macOS unterstützt ASP.NET Core gRPC mit TLS nicht. Zum erfolgreichen Ausführen von gRPC-Diensten unter macOS ist eine zusätzliche Konfiguration erforderlich. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.

Überprüfen der Projektdateien

GrpcGreeter-Projektdateien:

  • greet.proto: Mit der Datei Protos/greet.proto werden der Greeter-gRPC-Dienst definiert und die gRPC-Serverobjekte generiert. Weitere Informationen finden Sie unter Einführung in gRPC in ASP.NET Core.
  • Services-Ordner: Dieser enthält die Implementierung des Greeter-Diensts.
  • appsettings.json: Enthält Konfigurationsdaten, etwa das von Kestrel verwendete Protokoll. Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.
  • Program.cs: enthält den Einstiegspunkt für den gRPC-Dienst. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core.
  • Startup.cs: Enthält Code, mit dem das App-Verhalten konfiguriert wird. Weitere Informationen finden Sie unter App-Start.

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

  • Öffnen Sie eine zweite Instanz von Visual Studio, und wählen Sie Neues Projekt erstellen aus.
  • Wählen Sie im Dialogfeld Neues Projekt erstellen die Option Konsolen-App (.NET Core) aus, und klicken Sie auf Weiter.
  • Geben Sie im Textfeld Projektname den Namen GrpcGreeterClient ein, und klicken Sie auf Erstellen.

Hinzufügen von erforderlichen Paketen

Das gRPC-Clientprojekt erfordert die folgenden Pakete:

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

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 Fenster Paket-Manager-Konsole den Befehl cd GrpcGreeterClient aus, um zu dem Verzeichnis zu wechseln, in dem sich die GrpcGreeterClient.csproj-Dateien befinden.

  • 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 unter Projektmappen-Explorer>NuGet-Pakete verwalten auf Ihr Projekt.
  • Wählen Sie die Registerkarte Durchsuchen aus.
  • Geben Sie Grpc.Net.Client in das Suchfeld ein.
  • Wählen Sie das Paket Grpc.Net.Client auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.
  • Führen Sie diese Aktionen auch für Google.Protobuf und Grpc.Tools durch.

Fügen Sie „greet.proto“ hinzu:

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

  • Kopieren Sie die Datei Protos\greet.proto aus dem gRPC-Greeter-Dienst 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:

    Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Projektdatei bearbeiten 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 greet.proto Datei:

  • 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 System;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // The port number(5001) must match the port of the gRPC server.
            using var channel = GrpcChannel.ForAddress("https://localhost:5001");
            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();
        }
    }
}

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:
static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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

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

Der Client sendet eine Begrüßungsnachricht an den Dienst, die den Namen des Diensts enthält: GreeterClient. 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:5001
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:5001/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 in 78.32260000000001ms 200 application/grpc

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. Informationen zum Beheben dieses Problems finden Sie unter Aufrufen eines gRPC-Diensts mit einem nicht vertrauenswürdigen/ungültigen Zertifikat.

Nächste Schritte