תרגיל - יצירת פרוייקט API באינטרנט

  • 8 דקות

מודול זה משתמש ב- SDK של .NET 8.0. ודא ש- .NET 8.0 מותקן על-ידי הפעלת הפקודה הבאה במסוף הפקודות המועדף עליך:

dotnet --list-sdks

הפלט דומה לדוגמה הבאה מופיע:

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

ודא שגירסה המתחילה 8 רשומה. אם לא מופיעה פקודה או שהפקודה לא נמצאה, את ערכת ה- SDK העדכנית ביותר של .NET 8.0.

יצירה ועיון בפרוייקט API של אינטרנט

כדי להגדיר פרוייקט .NET לעבודה עם ה- API של האינטרנט, אנו משתמשים ב- Visual Studio Code. Visual Studio Code כולל מסוף משולב המקל על יצירת פרוייקט חדש. אם אינך מעוניין להשתמש בעורך קוד, באפשרותך להפעיל את הפקודות במודול זה במסוף.

  1. ב- Visual Studio Code, בחר קובץ>פתיחת תיקיה.

  2. צור תיקיה חדשה בשם ContosoPizza במיקום שתבחר ולאחר מכן בחר בחר תיקיה.

  3. פתח את המסוף המשולב מ- Visual Studio Code על-ידי בחירה באפשרות הצג>מסוף מהתפריט הראשי.

  4. בחלון המסוף, העתק והדבק את הפקודה הבאה:

    dotnet new webapi -controllers -f net8.0

    פקודה זו יוצרת את הקבצים עבור פרוייקט API בסיסי של אינטרנט המשתמש בבקרים, יחד עם קובץ פרוייקט C# בשם ContosoPizza.csproj שמחזיר רשימה של תחזיות מזג אוויר. אם אתה מקבל שגיאה, ודא ש- SDK של .NET 8 מותקן.

    חשוב

    פרוייקטי API של אינטרנט מאובטחים עם https כברירת מחדל. אם אתה נתקל בבעיות, קבע את התצורה ASP.NET אישור פיתוח של HTTPS ליבה.

    ייתכן שתקבל בקשה מ- Visual Studio Code כדי להוסיף נכסים כדי לאתר באגים בפרוייקט. בחר כן בתיבת הדו-שיח.

    הפקודה משתמשת בתבנית ASP.NET Core עם כינוי webapi כדי למחוק פרוייקט API מבוסס C#. ספריה ContosoPizza נוצרה. ספריה זו מכילה ASP.NET Core שפועל ב- .NET. שם הפרוייקט תואם לשם ContosoPizza הספריה.

    כעת אמורה להיות לך גישה לקבצים ולספריות אלה:

    -| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs

  5. בדוק את הקבצים והספריות הבאים:

    שם תיאור
    Controllers/ מכיל כיתות עם שיטות ציבוריות החשופות כנקודות קצה של HTTP.
    Program.cs קביעת תצורה של שירותים וצינור בקשת HTTP של היישום, והוא מכיל את נקודת הכניסה המנוהלת של היישום.
    ContosoPizza.csproj מכילה מטה-נתונים של תצורה עבור הפרוייקט.
    ContosoPizza.http מכיל תצורה לבדיקת ממשקי REST API ישירות מ- Visual Studio Code.

בנה ובדוק את ה- API של האינטרנט

  1. הפעל את הפקודה הבאה של .NET Core CLI במעטפת הפקודה:

    dotnet run

    הפקודה הקודמת:

    • מאתר את קובץ הפרוייקט בספריה הנוכחית.
    • מאחזר ומתקין יחסי תלות נדרשים בפרוייקט עבור פרוייקט זה.
    • מבצע קומפילציה של קוד הפרוייקט.
    • מארח את ה- API של האינטרנט עם ASP.NET האינטרנט Core Kestrel הן בנקודות קצה של HTTP והן ב- HTTPS.

    יציאה מ- 5000 עד 5300 נבחרת עבור HTTP, ומ- 7000 עד 7300 עבור HTTPS, כאשר הפרוייקט נוצר. באפשרותך לשנות בקלות את היציאות שאתה משתמש בהן במהלך הפיתוח על-ידי עריכת קובץ ה -launchSettings.json של הפרוייקט. מודול זה משתמש בכתובת ה- localhost URL המאובטחת המתחילה ב- https.

    אתה אמור לקבל פלט דומה לזה, המציין כי האפליקציה שלך פועלת:

    Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7294
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5118 
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

    אם אתה מפעיל יישום זה במחשב שלך, באפשרותך להפנות דפדפן לקישור HTTPS המוצג בפלט (במקרה הקודם, https://localhost:7294) כדי להציג את הדף המתוצא. זכור יציאה זו, מכיוון שאתה משתמש בה לאורך כל המודול שבו {PORT} נעשה שימוש.

    חשוב

    בדוק את פלט המסוף אם אתה נתקל באופן פעולה בלתי צפוי. אם גירסת ה- Build נכשלת או אם מתרחשות שגיאות אחרות, המידע של קובץ יומן הרישום עוזר לך לפתור בעיות. בעת ביצוע שינויים בקוד, יהיה עליך להפסיק את ה- API של האינטרנט על-ידי בחירת CTRL+C בלוח המקשים והפעלה מחדש של dotnet run הפקודה.

  2. פתח דפדפן אינטרנט ועבור אל:

    https://localhost:{PORT}/weatherforecast

    אתה אמור לראות פלט JSON דומה לדוגמה זו:

    [
    {
    "date": "2021-11-09T20:36:01.4678814+00:00",
    "temperatureC": 33,
    "temperatureF": 91,
    "summary": "Scorching"
    },
    {
    "date": "2021-11-09T20:36:01.4682337+00:00",
    "temperatureC": -8,
    "temperatureF": 18,
    "summary": "Cool"
    },
    // ...
]

אופציונלי: סיור עם .http קבצים

הפרוייקט הכלול הוא ContosoPizza.http, קובץ המשמש לבדיקת נקודות קצה של API באמצעות תבנית סטנדרטית. .http יש תמיכה בכמה בסביבות פיתוח משולבות (IDEs), כולל Visual Studio ובתוך Visual Studio Code, כשהרחבת לקוח REST מותקנת.

  1. פתח את הקובץ ContosoPizza.http.

    במזהים מסוימים, קובץ זה מוגדר מראש עם משתני @ContosoPizza_HostAddress ו- GET command calling /weatherforecast/ שמקבל יישום/json.

  2. אם היא קיימת בקובץ שלך, בחר בפקודה בקשה שנשלחה מעל GET ששולחת בקשה לשירות הפועל.

    קריאה לפקודה זו פותחת חלון תגובה עם פלט דומה למה שראינו בדפדפן:

    HTTP/1.1 200 OK
Connection: close
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Jan 2024 16:46:40 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
    {
        "date": "2024-01-18",
        "temperatureC": -2,
        "temperatureF": 29,
        "summary": "Warm"
    },
    {
        "date": "2024-01-19",
        "temperatureC": 24,
        "temperatureF": 75,
        "summary": "Chilly"
    },
    // ..
]

אופציונלי: סיור בממשקי API עם REPL של שורת הפקודה HTTP

  1. פתח מסוף משולב חדש מ- Visual Studio Code על-ידי בחירת Terminal>New Terminal מהתפריט הראשי ולאחר מכן הפעל את הפקודה הבאה:

    dotnet tool install -g Microsoft.dotnet-httprepl

    הפקודה הקודמת מתקינת את כלי שורת הפקודה .NET HTTP Read-Eval-Print Loop (REPL) שבו אתה משתמש כדי לבצע בקשות HTTP ל- API של האינטרנט.

  2. התחבר ל- API של האינטרנט על-ידי הפעלת הפקודה הבאה:

    httprepl https://localhost:{PORT}

    לחלופין, הפעל את הפקודה הבאה בכל עת HttpRepl פועל:

    connect https://localhost:{PORT}

    עצה

    אם הכלי HttpRepl מזהיר לא ניתן למצוא תיאור OpenAPI, סביר להניח שהגורם לכך הוא אישור פיתוח לא מהימן. HttpRepl דורש חיבור מהימן. לפני שתוכל להמשיך, עליך לקבוע את תצורת המערכת שלך כדי לתת אמון באישור devdotnet dev-certs https --trust

  3. גלה את נקודות הקצה הזמינות על-ידי הפעלת הפקודה הבאה:

    ls

    הפקודה הקודמת מזהה את כל ממשקי ה- API הזמינים בנקודות הקצה המחוברות ומפרטת אותם, כמו בפלט הבא:

    https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET]

  4. עבור אל נקודת WeatherForecast על-ידי הפעלת הפקודה הבאה:

    cd WeatherForecast

    הפקודה הקודמת מציגה פלט של ממשקי API זמינים עבור WeatherForecast הקצה:

    https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]

  5. בצע בקשה GET ב- HttpRepl באמצעות הפקודה הבאה:

    get

    הפקודה הקודמת הופכת בקשה GET לדומה מעבר אל נקודת הקצה בדפדפן:

    HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Apr 2021 17:31:43 GMT
Server: Kestrel
Transfer-Encoding: chunked
[
    {
    "date": 4/3/2021 10:31:44 AM,
    "temperatureC": 13,
    "temperatureF": 55,
    "summary": "Sweltering"
    },
    {
    "date": 4/4/2021 10:31:44 AM,
    "temperatureC": -13,
    "temperatureF": 9,
    "summary": "Warm"
    },
    // ..
]

  6. סיים את ההפעלה HttpRepl הנוכחית באמצעות הפקודה הבאה:

    exit

  7. חזור למסוף dotnet ברשימה הנפתחת ב- Visual Studio Code. כבה את ה- API של האינטרנט על-ידי בחירת CTRL+C בלוח המקשים.

כעת, לאחר שיצרת את ה- API של האינטרנט, נוכל לשנות אותו כך שיקנה את הצרכים של API של האינטרנט.