פיתוח שירות gRPC עם C#

1. סקירה כללית

‫gRPC הוא framework וערכת כלים לקריאה לשירות מרוחק (RPC) שפותחו ב-Google, והם לא תלויים בשפה או בפלטפורמה. הוא מאפשר להגדיר שירות באמצעות Protocol Buffers, שהם ערכת כלים ושפה בינאריים חזקים במיוחד לסריאליזציה. אחר כך, הוא מאפשר לכם ליצור קובצי stub של לקוח ושרת בשפות שונות מתוך הגדרת השירות.

ב-codelab הזה תלמדו איך ליצור שירות C# שחושף API באמצעות מסגרת gRPC. האינטראקציה עם השירות הזה מתבצעת באמצעות לקוח קונסולה שנכתב ב-C# ‎ ומשתמש באותו תיאור שירות כמו השירות.

מה תלמדו

השפה של מאגר האחסון לפרוטוקולים.
איך מטמיעים שירות gRPC באמצעות C#.
איך מטמיעים לקוח gRPC באמצעות C#.
איך מעדכנים שירות gRPC.

הדרישות

דפדפן, כמו Chrome או Firefox.
‫Visual Studio 2013 או גרסה מתקדמת יותר מותקנת.
היכרות עם ‎ .NET Framework ועם שפת C# ‎.

איך תשתמשו במדריך הזה?

רק לקרוא

לקרוא ולבצע את התרגילים

איזה דירוג מגיע לדעתך לחוויה שלך עם Google Cloud Platform?

מתחילים

ביניים

מומחים

2. הורדה ובנייה של דוגמאות ל-gRPC C# ‎

הורדת דוגמאות

מורידים את מאגר הדוגמאות של gRPC C# ‎ כקובץ ZIP ומחלצים אותו.

אפשר גם לשכפל את מאגר ה-Git שלו.

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

בכל מקרה, צריכה להיות לכם תיקייה בשם grpc-samples-dotnet עם התוכן הבא:

בניית הפתרון

תיקיית האפליקציה לדוגמה מכילה את GrpcSamples.sln, פתרון של Visual Studio. לוחצים לחיצה כפולה כדי לפתוח את הפתרון ב-Visual Studio. אמור להופיע פתרון עם מספר פרויקטים.

בקטע הבא נפרט יותר על פרויקטים, אבל קודם נבנה את הפרויקט. כדי ליצור את הפתרון, עוברים אל Build > Build Solution או אל Ctrl + Shift + B. כל התלויות יורדו מ-NuGet והאפליקציה תעבור קומפילציה.

בסיום, אמורה להופיע ההודעה Build succeeded בפלט של מסוף Visual Studio.

3. היכרות עם דוגמת ה-Greeter

‫Greeter הוא דוגמה פשוטה ל-gRPC שבה לקוח שולח בקשה עם שם והשרת מגיב עם הודעה ואחריה השם. יש פרויקט Greeter שכולל את הגדרת השירות המשותפת (קובץ proto) שעליה מבוססים הלקוח והשרת.

Greeter Project

זהו הפרויקט המשותף בין הלקוח לשרת. יש לו greeter.proto, שהוא הגדרת שירות gRPC שבה משתמשים הלקוח והשרת. הגדרת השירות מגדירה שירות gRPC בשם GreetingService, ויש לו שיטה greeting שמקבלת את HelloRequest כקלט ואת HelloResponse כפלט.

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

זו שיטה אונרית (כלומר, ללא סטרימינג) שבה הלקוח שולח בקשה יחידה ומקבל מהשרת תגובה יחידה. אפשר לעיין בשאר התוכן של greeter.proto. בפרויקט הזה יש גם סקריפט בשם generate_protos.bat שאפשר להשתמש בו כדי ליצור קובצי stub של לקוח ושרת מקובץ ה-proto. הפרויקט כבר מכיל קובצי stub של לקוח ושרת שנוצרו, כך שלא צריך ליצור אותם בעצמכם. עם זאת, אם משנים משהו בקובץ הגדרת השירות, צריך להריץ את הסקריפט הזה כדי ליצור מחדש את ה-stub.

Greeter Server

זהו הפרויקט של שרת gRPC. ‫Program.cs היא נקודת הכניסה העיקרית שבה מוגדרים היציאה והטמעת השרת. הכיתה החשובה היא GreeterServiceImpl.cs. יש לה method greeting שבה מיושמת הפונקציונליות בפועל.

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

Greeter Client

זהו הצד של הלקוח בשירות gRPC. נקודת הכניסה היא גם Program.cs. הוא יוצר ערוץ לתקשורת עם השרת ואז יוצר לקוח עם הערוץ מה-stub שנוצר. לאחר מכן היא יוצרת בקשה ושולחת אותה לשרת באמצעות ה-stub של הלקוח.

4. הרצת הדוגמה של הצ'אט בוט שמברך לקוחות

קודם מפעילים את שרת Greeter. פותחים שורת פקודה, עוברים לתיקייה bin > Debug של Greeter Server ומריצים את קובץ ההפעלה. השרת אמור להופיע ברשימת השרתים הפעילים.

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

לאחר מכן, מריצים את Greeter Client. בשורת פקודה נפרדת, עוברים לתיקייה bin > Debug של Greeter 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. עדכון הדוגמה Greeter

כדאי לראות איך נראה עדכון של השירות שלנו. מוסיפים שיטה חדשה לשירות gRPC שנקראת goodbye ומחזירה goodbye במקום hello ללקוח.

השלב הראשון הוא לעדכן את קובץ הגדרת השירות greeter.proto.

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

לאחר מכן, צריך ליצור מחדש את קטעי הקוד החלופי (stub) של הלקוח והשרת. בשורת הפקודה, מריצים את הפקודה generate_protos.bat. אחרי שנוצרים קובצי stub, יכול להיות שתצטרכו לרענן את הפרויקטים שלכם ב-Visual Studio כדי לקבל את הקוד המעודכן.

לבסוף, מעדכנים את הקוד של הלקוח והשרת כדי להשתמש בשיטה החדשה. בשירות, מעדכנים את GreeterServiceImpl.cs ומוסיפים שיטה חדשה של goodbye.

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

בלקוח, מבצעים קריאה ל-method‏ goodbye ב-Program.cs.

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

בונים מחדש את הפרויקט ומריצים שוב את השרת והלקוח. עכשיו הלקוח אמור לקבל הודעת סיום.

> 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. עיון בדוגמה של Chat

בפתרון יש גם פרויקטים של ChatServer ושל ChatWindowsClient. כפי שהשם מרמז, מדובר בצמד של לקוח ושרת לאפליקציית צ'אט פשוטה. פרויקט Chat מכיל את קובץ הגדרת השירות שנקרא chat.proto. הוא מגדיר ChatService עם שיטת chat.

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

הדבר החשוב כאן הוא שגם הודעות צ'אט נכנסות וגם הודעות צ'אט יוצאות מסומנות במילת המפתח stream. החיבור הופך לזרם דו-כיווני שבו הלקוח והשרת יכולים לשלוח הודעות זה לזה בכל שלב. זה פתרון מושלם לאפליקציית צ'אט.

כדי לתרגל, אפשר לעיין בדוגמה, לבנות אותה ולהפעיל אותה כדי לראות איך היא פועלת.

7. מעולה!

מה נכלל

שפת מאגרי האחסון לפרוטוקולים.
איך מטמיעים שירות gRPC באמצעות C#.
איך מטמיעים לקוח gRPC באמצעות C#.
איך מעדכנים שירות gRPC.