Tutorial: Erstellen eines gRPC-Clients und -Servers in ASP.NET CoreTutorial: Create a gRPC client and server in ASP.NET Core

Von John LuoBy John Luo

In diesem Tutorial erfahren Sie, wie Sie einen .NET Core-gRPC-Client und einen ASP.NET Core-gRPC-Server erstellen können.This tutorial shows how to create a .NET Core gRPC client and an ASP.NET Core gRPC Server.

Das Ziel ist ein gRPC-Client, der mit dem gRPC-Greeter-Dienst kommuniziert.At the end, you'll have a gRPC client that communicates with the gRPC Greeter service.

Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).View or download sample code (how to download).

In diesem Tutorial:In this tutorial, you:

  • Erstellen Sie einen gRPC-Server.Create a gRPC Server.
  • Erstellen Sie einen gRPC-Client.Create a gRPC client.
  • Testen Sie den gRPC-Clientdienst mit dem gRPC-Greeterdienst (Begrüßungsdienst).Test the gRPC client service with the gRPC Greeter service.

VoraussetzungenPrerequisites

Erstellen eines gRPC-DienstsCreate a gRPC service

  • Starten Sie Visual Studio, und wählen Sie Neues Projekt erstellen aus.Start Visual Studio and select Create a new project. Alternativ dazu können Sie auch im Visual Studio-Menü Datei auf Neu > Projekt klicken.Alternatively, from the Visual Studio File menu, select New > Project.

  • Wählen Sie im Dialogfeld Neues Projekt erstellen die Option gRPC-Dienst aus, und klicken Sie auf Weiter:In the Create a new project dialog, select gRPC Service and select Next:

    Dialogfeld „Neues Projekt erstellen“ in Visual Studio

  • Nennen Sie das Projekt GrpcGreeter.Name the project GrpcGreeter. Es ist wichtig, den Namen GrpcGreeter zu verwenden, damit die Namespaces übereinstimmen, wenn Sie Code kopieren und einfügen.It's important to name the project GrpcGreeter so the namespaces match when you copy and paste code.

  • Wählen Sie Erstellen aus.Select Create.

  • Im Dialogfeld Neuen gRPC-Dienst erstellen:In the Create a new gRPC service dialog:

    • Die gRPC-Dienst ist ausgewählt.The gRPC Service template is selected.
    • Wählen Sie Erstellen aus.Select Create.

Ausführen des DienstsRun the service

  • Drücken Sie STRG+F5, um die Ausführung ohne den Debugger zu starten.Press Ctrl+F5 to run without the debugger.

    In Visual Studio wird das folgende Dialogfeld angezeigt:Visual Studio displays the following dialog:

    Dieses Projekt ist für die Verwendung von SSL konfiguriert.

    Wählen Sie Ja aus, wenn Sie dem IIS Express-SLL-Zertifikat vertrauen möchten.Select Yes if you trust the IIS Express SSL certificate.

    Das folgende Dialogfeld wird angezeigt:The following dialog is displayed:

    Dialogfeld „Sicherheitswarnung“

    Klicken Sie auf Ja, wenn Sie zustimmen möchten, dass das Entwicklungszertifikat vertrauenswürdig ist.Select Yes if you agree to trust the development certificate.

    Informationen dazu, wie Sie dem Firefox-Browser vertrauen, finden Sie unter Firefox-Zertifikatfehler SEC_ERROR_INADEQUATE_KEY_USAGE.For information on trusting the Firefox browser, see Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.

    Visual Studio startet IIS Express und führt die App aus.Visual Studio starts IIS Express and runs the app. Die Adressleiste zeigt localhost:port# an, nicht example.com.The address bar shows localhost:port# and not something like example.com. Das liegt daran, dass es sich bei localhost um den Standardhostnamen für den lokalen Computer handelt.That's because localhost is the standard hostname for the local computer. „Localhost“ dient nur Webanforderungen vom lokalen Computer.Localhost only serves web requests from the local computer. Wenn in Visual Studio ein Webprojekt erstellt wird, wird für den Webserver ein zufälliger Port verwendet.When Visual Studio creates a web project, a random port is used for the web server.

In den Protokollen wird vermerkt, dass der Dienst auf https://localhost:5001 lauscht.The logs show the service listening on https://localhost:5001.

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.The gRPC template is configured to use Transport Layer Security (TLS). gRPC-Clients müssen zum Aufrufen des Servers HTTPS verwenden.gRPC clients need to use HTTPS to call the server.

macOS unterstützt ASP.NET Core gRPC mit TLS nicht.macOS doesn't support ASP.NET Core gRPC with TLS. Zum erfolgreichen Ausführen von gRPC-Diensten unter macOS ist eine zusätzliche Konfiguration erforderlich.Additional configuration is required to successfully run gRPC services on macOS. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.For more information, see Unable to start ASP.NET Core gRPC app on macOS.

Überprüfen der ProjektdateienExamine the project files

GrpcGreeter-Projektdateien:GrpcGreeter project files:

  • greet.proto: Mit der Datei Protos/greet.proto werden der Greeter-gRPC-Dienst definiert und die gRPC-Serverobjekte generiert.greet.proto: The Protos/greet.proto file defines the Greeter gRPC and is used to generate the gRPC server assets. Weitere Informationen finden Sie unter Einführung in gRPC in ASP.NET Core.For more information, see Introduction to gRPC.
  • Services-Ordner: Dieser enthält die Implementierung des Greeter-Diensts.Services folder: Contains the implementation of the Greeter service.
  • appSettings.json: Diese Datei enthält Konfigurationsdaten wie z. B. das von Kestrel verwendete Protokoll.appSettings.json: Contains configuration data, such as protocol used by Kestrel. Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.For more information, see Konfiguration in ASP.NET Core.
  • Program.cs: Diese Datei enthält den Einstiegspunkt für den gRPC-Dienst.Program.cs: Contains the entry point for the gRPC service. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core.For more information, see Generischer .NET-Host in ASP.NET Core.
  • Startup.cs: Diese Datei enthält Code, mit dem das App-Verhalten konfiguriert wird.Startup.cs: Contains code that configures app behavior. Weitere Informationen finden Sie unter App-Start.For more information, see App startup.

Erstellen des gRPC-Clients in einer .NET-Konsolen-AppCreate the gRPC client in a .NET console app

  • Öffnen Sie eine zweite Instanz von Visual Studio, und wählen Sie Neues Projekt erstellen aus.Open a second instance of Visual Studio and select Create a new project.
  • Wählen Sie im Dialogfeld Neues Projekt erstellen die Option Konsolen-App (.NET Core) aus, und klicken Sie auf Weiter.In the Create a new project dialog, select Console App (.NET Core) and select Next.
  • Geben Sie im Textfeld Projektname den Namen GrpcGreeterClient ein, und klicken Sie auf Erstellen.In the Project name text box, enter GrpcGreeterClient and select Create.

Hinzufügen von erforderlichen PaketenAdd required packages

Das gRPC-Clientprojekt erfordert die folgenden Pakete:The gRPC client project requires the following packages:

  • Grpc.Net.Client, das den .NET Core-Client enthält.Grpc.Net.Client, which contains the .NET Core client.
  • Google.Protobuf, das die Protobuf-Nachrichten-APIs für C# enthält.Google.Protobuf, which contains protobuf message APIs for C#.
  • Grpc.Tools, das C#-Toolunterstützung für Protobuf-Dateien enthält.Grpc.Tools, which contains C# tooling support for protobuf files. Das Toolpaket ist nicht zur Laufzeit erforderlich, darum ist die Abhängigkeit mit PrivateAssets="All" markiert.The tooling package isn't required at runtime, so the dependency is marked with PrivateAssets="All".

Installieren Sie die Pakete über die Paket-Manager-Konsole oder über „NuGet-Pakete verwalten“.Install the packages using either the Package Manager Console (PMC) or Manage NuGet Packages.

PMC-Option zum Installieren von PaketenPMC option to install packages

  • Wählen Sie in Visual Studio Tools > NuGet-Paket-Manager > Paket-Manager-Konsole aus.From Visual Studio, select Tools > NuGet Package Manager > Package Manager Console

  • 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.From the Package Manager Console window, run cd GrpcGreeterClient to change directories to the folder containing the GrpcGreeterClient.csproj files.

  • Führen Sie die folgenden Befehle aus:Run the following commands:

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

Option „NuGet-Pakete verwalten“ zum Installieren von PaketenManage NuGet Packages option to install packages

  • Klicken Sie mit der rechten Maustaste unter Projektmappen-Explorer > NuGet-Pakete verwalten auf Ihr Projekt.Right-click the project in Solution Explorer > Manage NuGet Packages.
  • Wählen Sie die Registerkarte Durchsuchen aus.Select the Browse tab.
  • Geben Sie Grpc.Net.Client in das Suchfeld ein.Enter Grpc.Net.Client in the search box.
  • Wählen Sie das Paket Grpc.Net.Client auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.Select the Grpc.Net.Client package from the Browse tab and select Install.
  • Führen Sie diese Aktionen auch für Google.Protobuf und Grpc.Tools durch.Repeat for Google.Protobuf and Grpc.Tools.

Fügen Sie „greet.proto“ hinzu:Add greet.proto

  • Erstellen Sie einen Protos-Ordner im gRPC-Clientprojekt.Create a Protos folder in the gRPC client project.

  • Kopieren Sie die Datei Protos\greet.proto aus dem gRPC-Greeter-Dienst in das gRPC-Clientprojekt.Copy the Protos\greet.proto file from the gRPC Greeter service to the gRPC client project.

  • Ändern Sie den Namespace in der Datei greet.proto in den Namespace des Projekts:Update the namespace inside the greet.proto file to the project's namespace:

    option csharp_namespace = "GrpcGreeterClient";
    
  • Bearbeiten Sie die Projektdatei GrpcGreeterClient.csproj:Edit the GrpcGreeterClient.csproj project file:

    Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Projektdatei bearbeiten aus.Right-click the project and select Edit Project File.


  • Fügen Sie eine Elementgruppe mit einem <Protobuf>-Element hinzu, das auf die Datei greet.proto verweist:Add an item group with a <Protobuf> element that refers to the greet.proto file:

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

Erstellen des Greeter-ClientsCreate the Greeter client

Erstellen Sie das Clientprojekt, um die Typen im GrpcGreeter-Namespace zu erstellen.Build the client project to create the types in the GrpcGreeter namespace. Die GrpcGreeter-Typen werden vom Buildprozess automatisch erstellt.The GrpcGreeter types are generated automatically by the build process.

Aktualisieren Sie die Datei Program.cs des gRPC-Clients mit dem folgenden Code:Update the gRPC client Program.cs file with the following 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.Program.cs contains the entry point and logic for the gRPC client.

Der Greeter-Client wird folgendermaßen erstellt:The Greeter client is created by:

  • Instanziieren eines GrpcChannel-Objekts, das Informationen zum Herstellen einer Verbindung mit dem gRPC-Dienst enthältInstantiating a GrpcChannel containing the information for creating the connection to the gRPC service.
  • Verwenden von GrpcChannel zum Erstellen des Greeter-Clients:Using the GrpcChannel to construct the Greeter client:
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.The Greeter client calls the asynchronous SayHello method. Das Ergebnis des Aufrufs von SayHello wird angezeigt:The result of the SayHello call is displayed:

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-DienstTest the gRPC client with the gRPC Greeter service

  • Drücken Sie im Greeterdienst Ctrl+F5, um den Server ohne Debugger zu starten.In the Greeter service, press Ctrl+F5 to start the server without the debugger.
  • Drücken Sie im GrpcGreeterClient-Projekt Ctrl+F5, um den Client ohne den Debugger zu starten.In the GrpcGreeterClient project, press Ctrl+F5 to start the client without the debugger.

Der Client sendet eine Begrüßungsnachricht an den Dienst, die den Namen des Diensts enthält: GreeterClient.The client sends a greeting to the service with a message containing its name, GreeterClient. Der Dienst gibt als Antwort die Meldung „Hello GreeterClient“ aus.The service sends the message "Hello GreeterClient" as a response. Die Antwort „Hello GreeterClient“ wird in der Eingabeaufforderung angezeigt:The "Hello GreeterClient" response is displayed in the command prompt:

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:The gRPC service records the details of the successful call in the logs written to the command prompt:

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.The code in this article requires the ASP.NET Core HTTPS development certificate to secure the gRPC service. 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.If the .NET gRPC client fails with the message The remote certificate is invalid according to the validation procedure. or The SSL connection could not be established., the development certificate isn't trusted. Informationen zum Beheben dieses Problems finden Sie unter Aufrufen eines gRPC-Diensts mit einem nicht vertrauenswürdigen/ungültigen Zertifikat.To fix this issue, see Call a gRPC service with an untrusted/invalid certificate.

Warnung

ASP.NET Core gRPC wird derzeit nicht in Azure App Service oder IIS unterstützt.ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. Die HTTP/2-Implementierung von „Http.Sys“ unterstützt keine nachstehenden HTTP-Antwortheader, auf die gRPC sich stützt.The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. Weitere Informationen finden Sie in diesem GitHub-Issue.For more information, see this GitHub issue.

Nächste SchritteNext steps