Samouczek: Tworzenie gRPC klienta i serwera w ASP.NET CoreTutorial: Create a gRPC client and server in ASP.NET Core

Przez Jan LuoBy John Luo

W tym samouczku pokazano, jak utworzyć klienta programu .NET Core gRPC oraz serwer gRPC ASP.NET Core.This tutorial shows how to create a .NET Core gRPC client and an ASP.NET Core gRPC Server.

Na koniec będziesz mieć klienta gRPC, który komunikuje się z usługą gRPC Greeter.At the end, you'll have a gRPC client that communicates with the gRPC Greeter service.

Wyświetlanie lub Pobieranie przykładowego kodu (jak pobrać).View or download sample code (how to download).

W tym samouczku zostały wykonane następujące czynności:In this tutorial, you:

  • Utwórz serwer gRPC.Create a gRPC Server.
  • Utwórz klienta gRPC.Create a gRPC client.
  • Przetestuj usługę klienta gRPC za pomocą usługi gRPC Greeter.Test the gRPC client service with the gRPC Greeter service.

Wymagania wstępnePrerequisites

Tworzenie usługi gRPCCreate a gRPC service

  • Uruchom program Visual Studio i wybierz pozycję Utwórz nowy projekt .Start Visual Studio and select Create a new project . Alternatywnie z menu plik programu Visual Studio wybierz pozycję Nowy > projekt .Alternatively, from the Visual Studio File menu, select New > Project .

  • W oknie dialogowym Tworzenie nowego projektu wybierz pozycję Usługa gRPC i wybierz pozycję dalej :In the Create a new project dialog, select gRPC Service and select Next :

    Tworzenie okna dialogowego nowego projektu w programie Visual Studio

  • Nazwij projekt GrpcGreeter .Name the project GrpcGreeter . Ważne jest, aby nazwa projektu GrpcGreeter , tak aby przestrzenie nazw były zgodne podczas kopiowania i wklejania kodu.It's important to name the project GrpcGreeter so the namespaces match when you copy and paste code.

  • Wybierz pozycję Utwórz .Select Create .

  • W oknie dialogowym Tworzenie nowej usługi gRPC :In the Create a new gRPC service dialog:

    • Wybrano szablon usługi gRPC .The gRPC Service template is selected.
    • Wybierz pozycję Utwórz .Select Create .

Uruchamianie usługiRun the service

  • Naciśnij klawisze CTRL + F5, aby uruchomić bez debugera.Press Ctrl+F5 to run without the debugger.

    Program Visual Studio wyświetla następujące okno dialogowe:Visual Studio displays the following dialog:

    Ten projekt jest skonfigurowany do korzystania z protokołu SSL.

    Wybierz opcję tak , jeśli ufasz certyfikatowi IIS Express protokołu SSL.Select Yes if you trust the IIS Express SSL certificate.

    Wyświetlane jest następujące okno dialogowe:The following dialog is displayed:

    Okno dialogowe ostrzeżenia o zabezpieczeniach

    Wybierz opcję tak , jeśli zgadzasz się ufać certyfikatowi Deweloperskiemu.Select Yes if you agree to trust the development certificate.

    Aby uzyskać informacje na temat zaufania do przeglądarki Firefox, zobacz firefox SEC_ERROR_INADEQUATE_KEY_USAGE Certificate Error.For information on trusting the Firefox browser, see Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.

    Program Visual Studio jest uruchamiany IIS Express i uruchomi aplikację.Visual Studio starts IIS Express and runs the app. Na pasku adresu są wyświetlane inne elementy localhost:port# , takie jak example.com .The address bar shows localhost:port# and not something like example.com. Wynika to z tego, że localhost jest standardową nazwą hosta dla komputera lokalnego.That's because localhost is the standard hostname for the local computer. Host lokalny obsługuje tylko żądania sieci Web z komputera lokalnego.Localhost only serves web requests from the local computer. Podczas tworzenia projektu internetowego w programie Visual Studio dla serwera internetowego jest używany losowy port.When Visual Studio creates a web project, a random port is used for the web server.

Dzienniki pokazują, że usługa nasłuchuje https://localhost:5001 .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

Uwaga

Szablon gRPC jest skonfigurowany do korzystania z Transport Layer Security (TLS).The gRPC template is configured to use Transport Layer Security (TLS). Klienci gRPC muszą używać protokołu HTTPS, aby wywołać serwer.gRPC clients need to use HTTPS to call the server.

Program macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS.macOS doesn't support ASP.NET Core gRPC with TLS. Aby pomyślnie uruchomić usługi gRPC Services w usłudze macOS, wymagana jest dodatkowa konfiguracja.Additional configuration is required to successfully run gRPC services on macOS. Aby uzyskać więcej informacji, zobacz nie można uruchomić aplikacji ASP.NET Core gRPC w witrynie macOS.For more information, see Unable to start ASP.NET Core gRPC app on macOS.

Sprawdzanie plików projektuExamine the project files

GrpcGreeter pliki projektu:GrpcGreeter project files:

  • Greeting. proto : plik Protos/Greeting. proto definiuje Greeter gRPC i służy do generowania zasobów serwera gRPC.greet.proto : The Protos/greet.proto file defines the Greeter gRPC and is used to generate the gRPC server assets. Aby uzyskać więcej informacji, zobacz wprowadzenie do gRPC.For more information, see Introduction to gRPC.
  • Folder usługi : zawiera implementację Greeter usługi.Services folder: Contains the implementation of the Greeter service.
  • appSettings.js : zawiera dane konfiguracyjne, takie jak protokół używany przez Kestrel.appSettings.json : Contains configuration data, such as protocol used by Kestrel. Aby uzyskać więcej informacji, zobacz Konfiguracja w ASP.NET Core.For more information, see Konfiguracja w ASP.NET Core.
  • Program.cs : zawiera punkt wejścia dla usługi gRPC.Program.cs : Contains the entry point for the gRPC service. Aby uzyskać więcej informacji, zobacz Host ogólny .NET w ASP.NET Core.For more information, see Host ogólny .NET w ASP.NET Core.
  • Startup.cs : zawiera kod, który konfiguruje zachowanie aplikacji.Startup.cs : Contains code that configures app behavior. Aby uzyskać więcej informacji, zobacz Uruchamianie aplikacji.For more information, see App startup.

Tworzenie klienta gRPC w aplikacji konsolowej .NETCreate the gRPC client in a .NET console app

  • Otwórz drugie wystąpienie programu Visual Studio i wybierz pozycję Utwórz nowy projekt .Open a second instance of Visual Studio and select Create a new project .
  • W oknie dialogowym Tworzenie nowego projektu wybierz pozycję aplikacja konsoli (.NET Core) , a następnie wybierz pozycję dalej .In the Create a new project dialog, select Console App (.NET Core) and select Next .
  • W polu tekstowym Nazwa projektu wprowadź GrpcGreeterClient i wybierz pozycję Utwórz .In the Project name text box, enter GrpcGreeterClient and select Create .

Dodaj wymagane pakietyAdd required packages

Projekt klienta gRPC wymaga następujących pakietów:The gRPC client project requires the following packages:

  • GRPC .NET. Client, który zawiera klienta .NET Core.Grpc.Net.Client, which contains the .NET Core client.
  • Google. protobuf, który zawiera interfejsy API komunikatów protobuf dla języka C#.Google.Protobuf, which contains protobuf message APIs for C#.
  • GRPC. Tools, która zawiera obsługę narzędzi C# dla plików protobuf.Grpc.Tools, which contains C# tooling support for protobuf files. Pakiet narzędzi nie jest wymagany w czasie wykonywania, dlatego zależność jest oznaczona za pomocą PrivateAssets="All" .The tooling package isn't required at runtime, so the dependency is marked with PrivateAssets="All".

Zainstaluj pakiety przy użyciu konsoli Menedżera pakietów (PMC) lub Zarządzaj pakietami NuGet.Install the packages using either the Package Manager Console (PMC) or Manage NuGet Packages.

Opcja PMC, aby zainstalować pakietyPMC option to install packages

  • W programie Visual Studio wybierz kolejno pozycje Narzędzia Menedżer > pakietów NuGet > konsola Menedżera pakietówFrom Visual Studio, select Tools > NuGet Package Manager > Package Manager Console

  • W oknie konsola Menedżera pakietów Uruchom polecenie, cd GrpcGreeterClient Aby zmienić katalogi na folder zawierający pliki GrpcGreeterClient. csproj .From the Package Manager Console window, run cd GrpcGreeterClient to change directories to the folder containing the GrpcGreeterClient.csproj files.

  • Uruchom następujące polecenia:Run the following commands:

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

Opcja zarządzania pakietami NuGet w celu zainstalowania pakietówManage NuGet Packages option to install packages

  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań > zarządzać pakietami NuGet .Right-click the project in Solution Explorer > Manage NuGet Packages .
  • Wybierz kartę Przeglądaj .Select the Browse tab.
  • W polu wyszukiwania wprowadź GRPC .NET. Client .Enter Grpc.Net.Client in the search box.
  • Wybierz pakiet GRPC .NET. Client z karty Przeglądaj i wybierz pozycję Zainstaluj .Select the Grpc.Net.Client package from the Browse tab and select Install .
  • Powtórz dla Google.Protobuf i Grpc.Tools .Repeat for Google.Protobuf and Grpc.Tools.

Dodaj Greeting. protoAdd greet.proto

  • Utwórz folder Protos w projekcie klienta gRPC.Create a Protos folder in the gRPC client project.

  • Skopiuj plik Protos\greet.proto z usługi gRPC Greeter do projektu klienta gRPC.Copy the Protos\greet.proto file from the gRPC Greeter service to the gRPC client project.

  • Zaktualizuj przestrzeń nazw wewnątrz greet.proto pliku do przestrzeni nazw projektu:Update the namespace inside the greet.proto file to the project's namespace:

    option csharp_namespace = "GrpcGreeterClient";
    
  • Edytuj plik projektu GrpcGreeterClient. csproj :Edit the GrpcGreeterClient.csproj project file:

    Kliknij prawym przyciskiem myszy projekt i wybierz polecenie Edytuj plik projektu .Right-click the project and select Edit Project File .


  • Dodaj grupę elementów z <Protobuf> elementem, który odwołuje się do pliku Greeting. proto :Add an item group with a <Protobuf> element that refers to the greet.proto file:

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

Tworzenie klienta GreeterCreate the Greeter client

Skompiluj projekt klienta, aby utworzyć typy w GrpcGreeter przestrzeni nazw.Build the client project to create the types in the GrpcGreeter namespace. GrpcGreeterTypy są generowane automatycznie przez proces kompilacji.The GrpcGreeter types are generated automatically by the build process.

Zaktualizuj plik program.cs klienta gRPC za pomocą następującego kodu: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 zawiera punkt wejścia i logikę dla klienta gRPC.Program.cs contains the entry point and logic for the gRPC client.

Klient Greeter jest tworzony przez:The Greeter client is created by:

  • Utworzenie wystąpienia GrpcChannel zawierającego informacje dotyczące tworzenia połączenia z usługą gRPC.Instantiating a GrpcChannel containing the information for creating the connection to the gRPC service.
  • Korzystanie z programu GrpcChannel do konstruowania klienta Greeter: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();
}

Klient Greeter wywołuje metodę asynchroniczną SayHello .The Greeter client calls the asynchronous SayHello method. SayHelloZostanie wyświetlony wynik wywołania: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();
}

Testowanie klienta gRPC za pomocą usługi gRPC GreeterTest the gRPC client with the gRPC Greeter service

  • W usłudze Greeter naciśnij klawisz, Ctrl+F5 Aby uruchomić serwer bez debugera.In the Greeter service, press Ctrl+F5 to start the server without the debugger.
  • W GrpcGreeterClient projekcie naciśnij klawisz, Ctrl+F5 Aby uruchomić klienta bez debugera.In the GrpcGreeterClient project, press Ctrl+F5 to start the client without the debugger.

Klient wysyła do usługi powitanie z komunikatem zawierającym nazwę GreeterClient .The client sends a greeting to the service with a message containing its name, GreeterClient . Usługa wysyła komunikat "Hello GreeterClient" jako odpowiedź.The service sends the message "Hello GreeterClient" as a response. Odpowiedź "Hello GreeterClient" jest wyświetlana w wierszu polecenia:The "Hello GreeterClient" response is displayed in the command prompt:

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

Usługa gRPC rejestruje szczegóły pomyślnego wywołania w dziennikach, które zostały zapisane w wierszu polecenia: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

Uwaga

Kod w tym artykule wymaga certyfikatu programistycznego HTTPS ASP.NET Core do zabezpieczenia usługi gRPC.The code in this article requires the ASP.NET Core HTTPS development certificate to secure the gRPC service. Jeśli klient .NET gRPC kończy się niepowodzeniem z komunikatem The remote certificate is invalid according to the validation procedure. lub The SSL connection could not be established. , certyfikat programistyczny nie jest zaufany.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. Aby rozwiązać ten problem, zobacz Wywoływanie usługi gRPC z niezaufanym/nieprawidłowym certyfikatem.To fix this issue, see Call a gRPC service with an untrusted/invalid certificate.

Ostrzeżenie

ASP.NET Core gRPC nie jest obecnie obsługiwana w Azure App Service lub IIS.ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. Implementacja protokołu HTTP/2 Http.Sys nie obsługuje nagłówków końcowych odpowiedzi HTTP, na których opiera się gRPC.The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. Aby uzyskać więcej informacji, zobacz ten problemw serwisie GitHub.For more information, see this GitHub issue.

Następne krokiNext steps