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

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-Clientdienst mit dem gRPC-Greeterdienst (Begrüßungsdienst).

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 (Vorschau) aus, und klicken Sie dann auf Erstellen.

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. Sie können sich dazu entscheiden, dem selbstsignierten Zertifikat zu vertrauen, das von IIS Express erstellt wurde, um SSL-Warnungen im Browser zu umgehen. Möchten Sie dem IIS Express-SLL-Zertifikat 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.

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

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:7042
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-Dienst und generiert die gRPC-Serverobjekte. 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 wie das von Kestrel verwendete Protokoll. Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.
  • Program.cs, die Folgendes enthält:

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 (Vorschau) aus, und klicken Sie dann auf Erstellen.

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 Extras > 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 GrpcGreeter-Namespace zu erstellen. Die GrpcGreeter-Typen werden vom Buildprozess automatisch erstellt.

  • 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();
    

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:7042
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:7042/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.

Warnung

AsP.NET Core gRPC hat zusätzliche Anforderungen für die Verwendung mit Azure App Service oder IIS. Weitere Informationen dazu, wo gRPC verwendet werden kann, finden Sie unter gRPC auf .NET-unterstützten Plattformen.

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-Clientdienst mit dem gRPC-Greeterdienst (Begrüßungsdienst).

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. Sie können sich dazu entscheiden, dem selbstsignierten Zertifikat zu vertrauen, das von IIS Express erstellt wurde, um SSL-Warnungen im Browser zu umgehen. Möchten Sie dem IIS Express-SLL-Zertifikat 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 wie das von Kestrel verwendete Protokoll. Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.
  • Program.cs: Diese Datei enthält den Einstiegspunkt für den gRPC-Dienst. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core.
  • Startup.cs: Diese Datei 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 Extras > 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 GrpcGreeter-Namespace zu erstellen. Die GrpcGreeter-Typen werden vom Buildprozess automatisch erstellt.

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.

Warnung

AsP.NET Core gRPC hat zusätzliche Anforderungen für die Verwendung mit Azure App Service oder IIS. Weitere Informationen dazu, wo gRPC verwendet werden kann, finden Sie unter gRPC auf .NET-unterstützten Plattformen.

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-Clientdienst mit dem gRPC-Greeterdienst (Begrüßungsdienst).

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. Sie können sich dazu entscheiden, dem selbstsignierten Zertifikat zu vertrauen, das von IIS Express erstellt wurde, um SSL-Warnungen im Browser zu umgehen. Möchten Sie dem IIS Express-SLL-Zertifikat 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 wie das von Kestrel verwendete Protokoll. Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.
  • Program.cs: Diese Datei enthält den Einstiegspunkt für den gRPC-Dienst. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core.
  • Startup.cs: Diese Datei 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 Extras > 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 GrpcGreeter-Namespace zu erstellen. Die GrpcGreeter-Typen werden vom Buildprozess automatisch erstellt.

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.

Warnung

AsP.NET Core gRPC hat zusätzliche Anforderungen für die Verwendung mit Azure App Service oder IIS. Weitere Informationen dazu, wo gRPC verwendet werden kann, finden Sie unter gRPC auf .NET-unterstützten Plattformen.

Nächste Schritte