Creazione di un servizio gRPC con C#

1. Panoramica

gRPC è un framework e un insieme di strumenti per chiamate di procedura remota (RPC) indipendenti dal linguaggio e dalla piattaforma, sviluppati da Google. Consente di definire un servizio utilizzando Protocol Buffers, un linguaggio e un insieme di strumenti di serializzazione binaria particolarmente potenti. Ti consente poi di generare stub client e server idiomatici dalla definizione del servizio in una serie di lingue.

In questo codelab, imparerai a creare un servizio C# che espone un'API utilizzando il framework gRPC. Interagisci con questo servizio utilizzando un client della console scritto in C# che utilizza la stessa descrizione del servizio.

Cosa imparerai a fare

  • Il linguaggio del buffer di protocollo.
  • Come implementare un servizio gRPC utilizzando C#.
  • Come implementare un client gRPC utilizzando C#.
  • Come aggiornare un servizio gRPC.

Che cosa ti serve

Come utilizzerai questo tutorial?

Leggilo e basta Leggilo e completa gli esercizi

Come valuteresti la tua esperienza con Google Cloud Platform?

Principiante Intermedio Avanzato

2. Scaricare e compilare gli esempi gRPC C#

Scarica i campioni

Scarica il repository di esempio gRPC C# come file ZIP ed estrailo.

In alternativa, puoi clonare il suo repository Git.

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

In entrambi i casi, dovresti avere una cartella grpc-samples-dotnet con i seguenti contenuti:

d056832ff4ce0c8f.png

Crea la soluzione

La cartella dell'applicazione di esempio contiene GrpcSamples.sln, una soluzione Visual Studio. Fai doppio clic per aprire la soluzione in Visual Studio. Dovresti vedere una soluzione con un numero di progetti.

61da9ddc86c08019.png

Esamineremo i progetti più nel dettaglio nella sezione successiva, ma prima creiamo il progetto. Vai a Build > Build Solution o Ctrl + Shift + B per creare la soluzione. Verranno scaricate tutte le dipendenze da NuGet e poi verrà compilata l'applicazione.

Alla fine, dovresti visualizzare un messaggio Build succeeded nell'output della console di Visual Studio.

3. Esplora l'esempio Greeter

Greeter è un semplice esempio gRPC in cui un client invia una richiesta con un nome e il server risponde con un messaggio seguito dal nome. Esiste un progetto Greeter che include la definizione di servizio comune (file proto) su cui si basano il client e il server.

Greeter Project

Questo è il progetto comune condiviso tra il client e il server. Ha un greeter.proto, ovvero la definizione del servizio gRPC utilizzata da client e server. La definizione del servizio definisce un servizio gRPC denominato GreetingService e ha un metodo greeting che accetta HelloRequest come input e HelloResponse come output.

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

Si tratta di un metodo unario (ovvero senza streaming) in cui il client invia una singola richiesta e riceve una singola risposta dal server. Puoi esplorare il resto dei contenuti di greeter.proto.. Questo progetto ha anche uno script chiamato generate_protos.bat che può essere utilizzato per generare stub client e server dal file proto. Il progetto contiene già stub client e server generati, quindi non devi generarli autonomamente. Tuttavia, se modifichi un aspetto del file di definizione del servizio, dovrai eseguire questo script per rigenerare gli stub.

Greeter Server

Questo è il progetto per il server gRPC. Program.cs è l'entry point principale in cui sono configurati l'implementazione della porta e del server. La classe importante è GreeterServiceImpl.cs. Ha un metodo greeting in cui viene implementata la funzionalità effettiva.

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

Client Greeter

Questo è il lato client del servizio gRPC. Inoltre, ha Program.cs come punto di ingresso. Crea un canale per comunicare con il server e poi crea un client con il canale dallo stub generato. Quindi, crea una richiesta e la invia al server utilizzando lo stub del client.

4. Esegui l'esempio Greeter

Per prima cosa, avvia il server Greeter. Apri un prompt dei comandi, vai alla cartella bin > Debug di Greeter Server ed esegui il file eseguibile. Dovresti vedere il server in ascolto.

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

Successivamente, esegui il client Greeter. In un prompt dei comandi separato, vai alla cartella bin > Debug di Greeter Server ed esegui il file eseguibile. Dovresti vedere il client che invia la richiesta e riceve una risposta dal server.

> 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. Aggiorna l'esempio Greeter

Vediamo come appare l'aggiornamento del nostro servizio. Aggiungi un nuovo metodo al nostro servizio gRPC chiamato goodbye che restituisce goodbye anziché hello al client.

Il primo passaggio consiste nell'aggiornare il file di definizione del servizio greeter.proto.

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

Successivamente, devi rigenerare gli stub client e server. In un prompt dei comandi, esegui generate_protos.bat. Una volta generati gli stub, potrebbe essere necessario aggiornare i progetti Visual Studio per ottenere il codice aggiornato.

Infine, aggiorna il codice client e server per sfruttare il nuovo metodo. Nel servizio, aggiorna GreeterServiceImpl.cs e aggiungi un nuovo metodo goodbye.

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

Nel client, effettua una chiamata al metodo goodbye in Program.cs.

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

Ricompila il progetto ed esegui di nuovo il server e il client. Ora il client dovrebbe ricevere un messaggio di addio.

> 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. Esplorare il campione di Chat

Nella soluzione sono presenti anche un progetto ChatServer e un progetto ChatWindowsClient. Come suggerito dal nome, si tratta di una coppia client-server per una semplice applicazione di chat. Il progetto Chat ha il file di definizione del servizio denominato chat.proto. Definisce un ChatService con un metodo chat.

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

La cosa importante qui è che sia i messaggi di chat in entrata che in uscita sono contrassegnati dalla parola chiave stream. In questo modo, la connessione si trasforma in un flusso bidirezionale in cui il client e il server possono inviarsi messaggi a vicenda in qualsiasi momento, la soluzione perfetta per un'applicazione di chat.

Puoi esplorare ulteriormente l'esempio, crearlo ed eseguirlo per vedere come funziona come esercizio.

7. Complimenti!

Argomenti trattati

  • Il linguaggio del buffer di protocollo.
  • Come implementare un servizio gRPC utilizzando C#.
  • Come implementare un client gRPC utilizzando C#.
  • Come aggiornare un servizio gRPC.

Passaggi successivi