تمرين - إنشاء مشروع واجهة برمجة تطبيقات ويب

8 دقائق

تستخدم هذه الوحدة النمطية .NET 8.0 SDK. تأكد من تثبيت .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. إذا لم يتم سرد أي منها أو لم يتم العثور على الأمر، فقم بتثبيت أحدث .NET 8.0 SDK.

إنشاء مشروع واجهة برمجة تطبيقات ويب واستكشافه

لإعداد مشروع .NET للعمل مع واجهة برمجة تطبيقات الويب، نستخدم Visual Studio Code. يتضمن Visual Studio Code terminal متكاملة، مما يجعل إنشاء مشروع جديد أمرًا سهلاً. إن لم ترغب باستخدام محرر تعليمات برمجية، يمكنك تشغيل الأوامر في هذه الوحدة في أي terminal.

في Visual Studio Code، حدد "File">"Open "Folder.
أنشئ مجلدا جديدا باسم ContosoPizza في الموقع الذي تختاره، ثم اختر تحديد مجلد.
افتح نافذة الـ terminal المُتضمنة في Visual Studio Code باختيار View>Terminal من القائمة الرئيسية.
في نافذة المحطة الطرفية، انسخ والصق الأمر التالي:
```
dotnet new webapi -controllers -f net8.0
```
ينشئ هذا الأمر الملفات لمشروع واجهة برمجة تطبيقات الويب الأساسي الذي يستخدم وحدات التحكم، إلى جانب ملف مشروع C# المسمى ContosoPizza.csproj الذي يقوم بإرجاع قائمة بتوقعات الطقس. إذا تلقيت خطأ، فتأكد من تثبيت .NET 8 SDK .

هام

يتم تأمين مشاريع واجهة برمجة تطبيقات الويب باستخدام https بشكل افتراضي. إذا كان لديك مشاكل، كوِّن شهادة تطوير ASP.NET Core HTTPS.

قد تتلقى مطالبة من Visual Studio Code لإضافة أصول لتصحيح المشروع. في مربع الحوار، حدد Yes.

يستخدم الأمر قالب مشروع ASP.NET Core باسم مستعار لدعم webapi مشروع واجهة برمجة تطبيقات ويب يستند إلى C#. يتم إنشاء دليل ContosoPizza. يحتوي هذا الدليل على مشروع ASP.NET Core قيد التشغيل على .NET. يتطابق اسم المشروع مع ContosoPizza اسم الدليل.

يجب أن يكون لديك الآن حق الوصول إلى هذه الملفات والدلائل:
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

فحص الملفات والدلائل التالية:

Name	‏‏الوصف
Controllers/	يحتوي على فئات مع الأساليب العامة التي يتم عرضها كنقاط نهاية HTTP.
Program.cs	تكوين الخدمات ومسار طلب HTTP للتطبيق، ويحتوي على نقطة الإدخال المدارة للتطبيق.
ContosoPizza.csproj	يحتوي على بيانات تعريف التكوين للمشروع.
ContosoPizza.http	يحتوي على تكوين لاختبار واجهات برمجة تطبيقات REST مباشرة من Visual Studio Code.

إنشاء واجهة برمجة تطبيقات الويب واختبارها

تشغيل الأمر .NET Core CLI التالي في أمر shell:
```
dotnet run
```
يعمل الأمر السابق على:
- تحديد موقع ملف المشروع في الدليل الحالي.
- استرداد وتثبيت أي تبعيات مشروع مطلوبة لهذا المشروع.
- تجميع التعليمات البرمجية للمشروع.
- يستضيف واجهة برمجة تطبيقات الويب مع خادم الويب 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} يتم استخدامها.

هام

تحقق من إخراج terminal إذا واجهت أي سلوك غير متوقع. في حال فشل الإنشاء أو حدوث أخطاء أخرى، تساعدك معلومات ملف السجل على استكشاف الأخطاء وإصلاحها. أثناء إجراء تغييرات على التعليمات البرمجية، ستحتاج إلى إيقاف واجهة برمجة تطبيقات الويب عن طريق تحديد CTRL+C على لوحة المفاتيح وإعادة تشغيل الأمر dotnet run.

افتح متصفحاً ثم انتقل إلى:

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، وهو ملف يستخدم لاختبار نقاط نهاية واجهة برمجة التطبيقات من خلال تنسيق قياسي. .http يتم دعم الملفات في العديد من بيئات التطوير المتكاملة (IDEs) بما في ذلك Visual Studio وداخل Visual Studio Code مع تثبيت ملحق عميل REST.

افتح ملف ContosoPizza.http.

في بعض IDEs، تم تكوين هذا الملف مسبقا باستخدام متغيرات @ContosoPizza_HostAddress و استدعاء أمر GET /weatherforecast/ الذي يقبل التطبيق/json.

إذا كان موجودا في ملفك، فحدد الأمر طلب المرسل أعلى 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"
    },
    // ..
]

اختياري: استكشاف واجهات برمجة التطبيقات باستخدام سطر الأوامر HTTP REPL

افتح محطة طرفية متكاملة جديدة من Visual Studio Code عن طريق تحديد Terminal>New Terminal من القائمة الرئيسية، ثم قم بتشغيل الأمر التالي:
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
يقوم الأمر السابق بتثبيت أداة سطر الأوامر .NET HTTP Read-Eval-Print Loop (REPL) التي تستخدمها لإجراء طلبات HTTP إلى واجهة برمجة تطبيقات الويب.
اتصل بواجهة برمجة تطبيقات الويب عن طريق تشغيل الأمر التالي:
```
httprepl https://localhost:{PORT}
```
بدلًا من ذلك، شغَّل الأمر التالي في أي وقت أثناء تشغيل HttpRepl:
```
connect https://localhost:{PORT}
```
تلميح

إذا حذرت الأداة HttpRepl من تعذر العثور على وصف OpenAPI، فإن السبب الأرجح هو شهادة تطوير غير موثوق بها. يتطلب HttpRepl اتصالاً موثوقاً به. قبل أن تتمكن من المتابعة، يجبتكوين النظام الخاص بك للثقة في شهادة التطوير باستخدام dotnet dev-certs https --trust
استكشف نقاط النهاية المتاحة عن طريق تشغيل الأمر التالي:
```
ls
```
يكشف الأمر السابق عن جميع واجهات برمجة التطبيقات المتوفرة على نقطة النهاية المتصلة ويسردها، كما هو الحال في الإخراج التالي:
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
انتقل إلى نقطة النهاية WeatherForecast عن طريق تشغيل الأمر التالي:
```
cd WeatherForecast
```
يظهر الأمر السابق إخراج واجهات برمجة التطبيقات المتوفرة لنقطة النهاية WeatherForecast:
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

قدم طلب 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"
    },
    // ..
]

بادر بإنهاء جلسة عمل HttpRepl الحالية باستخدام الأمر التالي:
```
exit
```
ارجع إلى terminal dotnet في القائمة المنسدلة في Visual Studio Code. أغلِق واجهة برمجة تطبيقات الويب عن طريق تحديد CTRL+C على لوحة المفاتيح لديك.

الآن بعد أن قمت بإنشاء واجهة برمجة تطبيقات الويب، يمكننا تعديلها لتلبية احتياجات واجهة برمجة تطبيقات ويب البيتزا.

الملاحظات

هل كانت هذه الصفحة مفيدة؟