Tworzenie usługi gRPC w języku C#

1. Przegląd

gRPC to niezależna od języka i platformy struktura zdalnych wywołań procedur (RPC) oraz zestaw narzędzi opracowany w Google. Umożliwia zdefiniowanie usługi za pomocą buforów protokołu, czyli szczególnie zaawansowanego zestawu narzędzi i języka do serializacji binarnej. Umożliwia to generowanie idiomatycznych stubów klienta i serwera z definicji usługi w różnych językach.

Z tego ćwiczenia dowiesz się, jak utworzyć usługę w C#, która udostępnia interfejs API za pomocą platformy gRPC. Korzystasz z tej usługi za pomocą klienta konsoli napisanego w języku C#, który używa tego samego opisu usługi co sama usługa.

Czego się nauczysz

Język bufora protokołu.
Jak wdrożyć usługę gRPC za pomocą języka C#.
Jak wdrożyć klienta gRPC za pomocą języka C#.
Jak zaktualizować usługę gRPC.

Czego potrzebujesz

przeglądarka, np. Chrome lub Firefox;
Zainstalowany program Visual Studio 2013 lub nowszy.
znajomość platformy .NET Framework i języka C#,

Jak zamierzasz korzystać z tego samouczka?

Tylko przeczytaj

Przeczytaj i wykonaj ćwiczenia

Jak oceniasz korzystanie z Google Cloud Platform?

Początkujący

Średnio zaawansowany

Zaawansowany

2. Pobieranie i kompilowanie przykładowych programów gRPC w C#

Pobieranie próbek

Pobierz repozytorium z przykładowym kodem gRPC w C# jako plik ZIP i wyodrębnij go.

Możesz też sklonować jego repozytorium Git.

git clone https://github.com/meteatamel/grpc-samples-dotnet.git

W każdym przypadku powinien być widoczny folder grpc-samples-dotnet z tą zawartością:

Budowanie rozwiązania

Folder aplikacji przykładowej zawiera rozwiązanie Visual Studio GrpcSamples.sln. Kliknij dwukrotnie, aby otworzyć rozwiązanie w Visual Studio. Powinno się wyświetlić rozwiązanie z liczbą projektów.

Projekty omówimy szczegółowo w następnej sekcji, ale najpierw je utwórzmy. Aby utworzyć rozwiązanie, kliknij Build > Build Solution lub Ctrl + Shift + B. Spowoduje to pobranie wszystkich zależności z NuGet, a następnie skompilowanie aplikacji.

Na koniec w danych wyjściowych konsoli Visual Studio powinien pojawić się komunikat Build succeeded.

3. Zapoznaj się z przykładowym programem Greeter

Greeter to prosty przykład gRPC, w którym klient wysyła żądanie z nazwą, a serwer odpowiada wiadomością z tą nazwą. Istnieje projekt Greeter, który zawiera wspólną definicję usługi (plik proto), na której opierają się klient i serwer.

Greeter Project

Jest to wspólny projekt udostępniony klientowi i serwerowi. Zawiera greeter.proto, czyli definicję usługi gRPC, z której korzystają klient i serwer. Definicja usługi określa usługę gRPC o nazwie GreetingService, która ma metodę greeting przyjmującą dane wejściowe HelloRequest i dane wyjściowe HelloResponse.

service GreetingService {
    rpc greeting(HelloRequest) returns (HelloResponse);
}

Jest to metoda binarna (bez przesyłania strumieniowego), w której klient wysyła jedno żądanie i otrzymuje jedną odpowiedź z serwera. Możesz zapoznać się z pozostałą zawartością greeter.proto.. Ten projekt zawiera też skrypt o nazwie generate_protos.bat, który może służyć do generowania stubów klienta i serwera z pliku proto. Projekt zawiera już wygenerowane szablony klienta i serwera, więc nie musisz ich generować samodzielnie. Jeśli jednak zmienisz coś w pliku definicji usługi, musisz uruchomić ten skrypt, aby ponownie wygenerować szablony.

Greeter Server

Jest to projekt serwera gRPC. Program.cs to główny punkt wejścia, w którym skonfigurowano port i implementację serwera. Ważna klasa to GreeterServiceImpl.cs. Ma metodę greeting, w której zaimplementowana jest rzeczywista funkcjonalność.

public override Task<HelloResponse> greeting(HelloRequest request,
       ServerCallContext context)
{
    return Task.FromResult(new HelloResponse { 
          Greeting = "Hello " + request.Name });
}

Klient Greeter

Jest to strona klienta usługi gRPC. Punktem wejścia jest też Program.cs. Tworzy kanał do komunikacji z serwerem, a następnie tworzy klienta z kanałem na podstawie wygenerowanego stuba. Następnie tworzy żądanie i wysyła je na serwer za pomocą klienta pośredniczącego.

4. Uruchamianie przykładowej aplikacji Greeter

Najpierw uruchom serwer Greeter. Otwórz wiersz polecenia i przejdź do folderu bin > Debug serwera Greeter, a następnie uruchom plik wykonywalny. Powinien pojawić się komunikat o tym, że serwer nasłuchuje.

> C:\grpc-samples-dotnet\GreeterServer\bin\Debug>GreeterServer.exe
GreeterServer listening on port 50051
Press any key to stop the server...

Następnie uruchom klienta Greeter. W osobnym wierszu polecenia otwórz folder bin > Debug serwera Greeter i uruchom plik wykonywalny. Powinien pojawić się klient wysyłający żądanie i otrzymujący odpowiedź z serwera.

> C:\grpc-samples-dotnet\GreeterClient\bin\Debug>GreeterClient.exe
GreeterClient sending request
GreeterClient received response: Hello Mete - on C#
Press any key to exit...

5. Aktualizowanie przykładu Greeter

Zobaczmy, jak wygląda aktualizacja usługi. Dodaj do naszej usługi gRPC nową metodę o nazwie goodbye, która zamiast hello zwraca klientowi goodbye.

Pierwszym krokiem jest zaktualizowanie pliku definicji usługi greeter.proto..

service GreetingService {
    rpc greeting(HelloRequest) returns (HelloResponse);
    
    rpc goodbye(HelloRequest) returns (HelloResponse);
}

Następnie musisz ponownie wygenerować namiary klienta i serwera. W wierszu poleceń uruchom generate_protos.bat. Po wygenerowaniu stubów może być konieczne odświeżenie projektów Visual Studio, aby uzyskać zaktualizowany kod.

Na koniec zaktualizuj kod klienta i serwera, aby korzystać z nowej metody. W usłudze zaktualizuj GreeterServiceImpl.cs i dodaj nową metodę goodbye.

public override Task<HelloResponse> goodbye(HelloRequest request,
       ServerCallContext context)
{
    return Task.FromResult(new HelloResponse { 
          Greeting = "Goodbye " + request.Name });
}

W kliencie wywołaj metodę goodbye w Program.cs..

response = client.goodbye(request);
Console.WriteLine("GreeterClient received response: " 
                       + response.Greeting);

Ponownie skompiluj projekt i uruchom serwer oraz klienta. Klient powinien teraz otrzymać wiadomość pożegnalną.

> C:\grpc-samples-dotnet\GreeterClient\bin\Debug>GreeterClient.exe
GreeterClient sending request
GreeterClient received response: Hello Mete - on C#
GreeterClient received response: Goodbye Mete - on C#
Press any key to exit...

6. Zapoznaj się z przykładem dotyczącym Google Chat

Rozwiązanie zawiera też projekty ChatServer i ChatWindowsClient. Jak sama nazwa wskazuje, jest to para klient-serwer dla prostej aplikacji do czatowania. Projekt Chat zawiera plik definicji usługi o nazwie chat.proto. Określa ChatService z metodą chat.

service ChatService {
 rpc chat(stream ChatMessage) returns (stream ChatMessageFromServer);
}

Ważne jest, że zarówno przychodzące, jak i wychodzące wiadomości na czacie są oznaczone słowem kluczowym stream. W ten sposób połączenie staje się dwukierunkowym strumieniem, w którym klient i serwer mogą w dowolnym momencie wysyłać do siebie wiadomości. Jest to idealne rozwiązanie dla aplikacji do czatowania.

Możesz dokładniej zapoznać się z przykładowym kodem, skompilować go i uruchomić, aby sprawdzić, jak działa.