webapiclientgen

تعمل مولدات واجهة برمجة تطبيقات الويب الخاصة بالعميل بقوة على إنشاء رموز واجهة برمجة تطبيقات العميل في C# وTypeScript من واجهة برمجة تطبيقات الويب ASP.NET (الأساسية) مباشرةً دون استخدام Swagger/OpenAPI أو Swashbuckle، وبالتالي زيادة الدعم لأنواع البيانات الخاصة بنهج Code First الخاص بـ ASP.NET Web API. .

منتجات

يقدم هذا المشروع هذه المنتجات:

1. منشئ الأكواد البرمجية لواجهة برمجة تطبيقات العميل المكتوبة بقوة في لغة C# التي تدعم .NET وXamarin.Forms.
2. مولدات الأكواد البرمجية لواجهة برمجة تطبيقات العميل المكتوبة بقوة في TypeScript لـ jQuery وAngular 2+ وAurelia وAxios وFetch API.
3. TypeScript CodeDOM، أحد مكونات .NET CodeDOM لـ TypeScript لتطوير مولدات أكواد TypeScript.
4. POCO2TS.exe، وهو برنامج سطر أوامر يقوم بإنشاء واجهات TypeScript من فئات POCO.
5. Fonlow.Poco2Ts، وهو مكون يقوم بإنشاء واجهات TypeScript من فئات POCO.
6. المكونات الإضافية لـ jQuery وAXIOS وFetch API وAurelia وAngular 2+ بالإضافة إلى النماذج التفاعلية المكتوبة بواسطة Angular.
7. Fonlow.DataOnlyExtensions مع محولات JSON لمعالجة سيناريوهات التاريخ فقط بين العملاء والخادم الموجودة في مناطق زمنية مختلفة. تتوفر أيضًا حزمة .NET Framework.

استخدام الحالات والتنزيلات

يتم إصدار المنتجات في الغالب من خلال NuGet.

1. أنشئ واجهة برمجة تطبيقات عميل C#، ثم استخدم الحزمة Fonlow.WebApiClientGenCore
2. قم بإنشاء واجهة برمجة تطبيقات عميل TypeScript، ثم استخدم أحد المكونات الإضافية لـ Fonlow.WebApiClientGenCore:
   1. مكتبة المساعدة jQuery وHttpClient
   2. الزاوي 6+
   3. Angular 6+، بالإضافة إلى إنشاء FormGroup للنماذج التفاعلية مع الوصف
   4. أكسيوس
   5. أوريليا
   6. جلب واجهة برمجة التطبيقات
3. قم بتطوير منشئ كود TypeScript من خلال نهج CodeDOM، ثم استخدم الحزمة Fonlow.TypeScriptCodeDOMCore.
4. قم بتطوير منشئ أكواد TypeScript من خلال نهج CodeDOM لـ POCO والمزيد، ثم استخدم الحزمة Fonlow.Poco2TSCore، أو استخدم البرامج النصية PowerShell 7.
5. أنشئ واجهات من نوع TypeScript، ثم استخدم Poco2TSCore.exe، وهو تطبيق وحدة تحكم.
6. قم بتطوير ميزة تقرأ مستند XML الخاص بتجميع .NET، ثم استخدم الحزمة Fonlow.DocCommentCore.

تلميحات:

• يعد OpenApiClientGen المستند إلى المكونات الرئيسية لـ WebApiClientGen عرضًا فرعيًا لإنشاء رموز واجهة برمجة تطبيقات العميل في C# وTypeScript وفقًا لملف تعريف Swagger/Open API Specification.
• لا يستخدم WebApiClientGen تعريفات Swagger / OpenAPI، ولكنه ينشئ رموزًا من معلومات نوع وقت التشغيل لواجهة برمجة تطبيقات الويب قيد التشغيل لبناء تصحيح الأخطاء، والتخلص من القيود المتأصلة في OpenAPI مقابل أنواع .NET وWeb API لإعطاء تجربة مطور أفضل لـ ASP. NET (الأساسية) Web API.

ملاحظات:

• بدأ التطوير في عام 2015 لدعم .NET Framework، ثم .NET Core 2. والعلامة "LastCore31" هي علامة على اللقطة الأخيرة التي تدعم .NET Framework 4.6.2 و.NET Core 3.1.
• بدءًا من 2021-02-10، سيدعم التطوير فقط .NET 5 وما بعده.
• سيتم الاحتفاظ بمحتويات Wiki الخاصة بـ .NET Framework في المستقبل المنظور.

الميزات الرئيسية

1. يتم تعيين رموز واجهة برمجة تطبيقات العميل التي تم إنشاؤها مباشرةً من أساليب وحدة تحكم Web API وأنواع .NET البدائية وفئات POCO. وهذا مشابه لما عرضه svcutil.exe في WCF.
2. يتم نسخ تعليقات المستند الخاصة بأساليب التحكم وفئات POCO.
3. يتم استخدام بعض سمات التحقق من الصحة لإنشاء تعليقات مستندية لأكواد TypeScript.

الفوائد الرئيسية لتجربة المطور

1. تم دمج WebApiClientGen بسلاسة مع ASP.NET Core Web API مع خطوات/تكاليف بسيطة جدًا للإعداد والصيانة والمزامنة بين Web API وواجهات برمجة تطبيقات العميل، أثناء RAD أو Agile Software Development.
2. دعم كافة أنواع .NET البدائية بما في ذلك العلامة العشرية.
3. دعم DataTime وDataTimeOffset وDateOnly وArray وTuple والكائن الديناميكي والقاموس وKeyValuePair
4. تخضع الرموز التي تم إنشاؤها بقوة لفحص نوع وقت التصميم وتجميع فحص نوع الوقت.
5. توفير مستوى عالٍ من التجريد، وحماية مطوري التطبيقات من التفاصيل الفنية المتكررة لممارسات RESTful والأكواد التقليدية لاستدعاءات AJAX.
6. المعلومات التعريفية الغنية بما في ذلك تعليقات المستندات تجعل IDE intellisense أكثر فائدة، لذلك لا يحتاج مطورو التطبيقات إلى قراءة مستندات API المنفصلة.
7. تعليقات المستند التي تم إنشاؤها بناءً على سمات التحقق من صحة .NET.
8. تم إنشاء تعليقات المستند استنادًا إلى الأنواع الرقمية والتاريخ فقط والمعرف الفريد العمومي (GUID) لأكواد TypeScript.
9. تتوافق رموز TypeScript التي تم إنشاؤها مع الوضع الصارم لـ TypeScript، وتتوافق رموز Angular 2+ التي تم إنشاؤها مع الوضع الصارم Angular.

أمثلة

1. فئات بوكو
2. واجهة برمجة تطبيقات الويب
3. تم إنشاء رموز API C# للعميل
4. رموز العميل باستخدام المكتبة التي تم إنشاؤها في C#
5. نماذج بيانات العميل التي تم إنشاؤها وواجهة برمجة التطبيقات (API) في TypeScript لـ jQuery وAngular 2 وAurelia وAxios
6. رموز العميل باستخدام المكتبة التي تم إنشاؤها في TypeScript
7. عرض توضيحي عبر الإنترنت مع Angular Heroes المستضاف في GitHub.IO ويتحدث إلى واجهة خلفية حقيقية

ملاحظات:

1. يمكن استخدام أكواد JavaScript التي تم تجميعها من أكواد TypeScript التي تم إنشاؤها في تطبيقات JS، ومع ذلك، من الواضح أنه لن تتوفر معلومات عن النوع، في حين قد يظل مبرمجو التطبيقات يتمتعون بالذكاء والتجريد من تفاصيل AJAX.
   1. تستخدم تطبيقات React وVue.js عادةً Axios أو Fetch API لطلبات HTTP. منذ يونيو 2019، يدعم babel مساحات الأسماء بفضل طلب السحب هذا، لذا من المفترض أن تكون قادرًا على تنفيذ برمجة React TSX باستخدام أكواد TypeScript التي تم إنشاؤها.

المفاهيم

1. يجب على بائعي / مطوري Web API توفير مكتبات API للعميل لمطوري برامج العملاء، كما ستفعل Google وAmazon وما إلى ذلك من أجل جعل RESTful Web API تصل إلى مستهلكين أوسع (داخليين وخارجيين) بكفاءة.
2. بالنسبة لمطوري العملاء، فإن النماذج الأولية للوظائف الكلاسيكية مثل ReturnType DoSomething(Type1 t1, Type2 t2 ...) هي وظيفة API، والباقي هو تفاصيل التنفيذ الفني للنقل: TCP/IP، HTTP، SOAP، الموجهة نحو الموارد، CRUD- URIs و RESTful و XML و JSON وما إلى ذلك. يجب أن يكون النموذج الأولي للوظيفة وجزء من مستند API جيدًا بما يكفي لاستدعاء وظيفة API.
3. كلما كان الفصل بين الاهتمامات في تصميم Web API الخاص بك أفضل، كلما استفدت أكثر من مكونات هذا المشروع من أجل تقديم قيم الأعمال في وقت أقرب، مع عدد أقل من الرموز المصنوعة يدويًا، ومهام أقل تكرارًا وفرص أقل للأخطاء البشرية.

ممارسات البرمجة المتوقعة

النموذج الأولي للوظيفة المكتوبة بقوة

ReturnType DoSomething(Type1 t1, Type2 t2 ...)

		[ HttpGet ]
		[ Route ( "getPerson/{id}" ) ]
		public Person GetPerson ( long id )

التحقق من صحة النموذج من خلال البرامج الوسيطة

بدلاً من كتابة أكواد صريحة للتحقق من صحة حمولة الطلب، من المتوقع أن تستخدم برامج وسيطة للتحقق من الصحة. على سبيل المثال:

 public void ConfigureServices ( IServiceCollection services )
{
	services . AddControllers (
		options =>
		{
			options . Filters . Add ( new ValidateModelAttribute ( ) ) ; // wholesale style to check model binding for all API calls.

مراجع:

• التحقق من صحة النموذج في ASP.NET Web API
• التحقق من صحة النموذج في ASP.NET Core MVC وصفحات Razor

التحقق من صحة النموذج من خلال ApiControllerAttribute

على سبيل المثال:

	[ ApiController ]
	[ Route ( "api/[controller]" ) ]
	public class HeroesController : ControllerBase
	{

رموز حالة HTTP غير 2xx التي تتم معالجتها بواسطة البرامج الوسيطة، اختيارية

حتى إذا قمت بكتابة الأكواد بشكل صريح في وظيفة واجهة برمجة التطبيقات (API) للتعامل مع الاستثناءات وإرجاع رمز حالة HTTP بخلاف 2xx، فيجب أن يكون لديك شبكة آمنة لالتقاط الاستثناءات غير المكتشفة وإرجاع رموز حالة HTTP.

مراجع:

• البرمجيات الوسيطة الأساسية لـ ASP.NET

المتطلبات الأساسية

جانب الخادم:

1. صافي 7/8
2. إضافة CodeGenController.
3. في رموز بدء تشغيل الخدمة، أضف ما يلي:

 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

ملاحظات:

• تقوم Microsoft بإصدار ترقية رئيسية لـ .NET (Core) كل عام منذ عام 2016، وستتبع المكتبات الموجودة في هذا المستودع بشكل عام آخر تحديث بعد حوالي نصف عام.
• المكتبات العامة مزودة بإصدار .NET واحد خلف الإصدار الأحدث، في حين أن تطبيق ASP.NET Demo ومجموعات اختبار التكامل مع واجهة برمجة تطبيقات عميل .NET التي تم إنشاؤها هي مع الإصدار الحالي من .NET.

جانب عميل .NET:

1. .NET Framework 4.5.2، أو Universal Windows، أو Mono.Android، أو Xamarin.iOS، أو .NET Core 2.0/2.1/3 و.NET 5
2. مكتبات عميل ASP.NET Web API 2.2
3. Json.NET من Newtonsoft لتطبيق Content-Type/json
4. أدوات بناء مايكروسوفت 2015

NewtonSoft.Json أو System.Text.Json

اعتبارًا من .NET 7، لإجراء التسلسل، يقوم System.Text.Json بإعادة تجميع أكثر من 95% من NewtonSoft.Json. لا يوجد سوى عدد قليل من الحالات الطرفية لهياكل POCO المعقدة التي لا يستطيع System.Text.Json التعامل معها.

يدعم WebApiClientGen كلا من جانب الخادم وجانب العميل C#. بالنسبة لعملاء C#، يمكنك استخدام "UseSystemTextJson" في إعدادات إنشاء التعليمات البرمجية.

ومع ذلك، إذا كان تطبيقك يتضمن هياكل POCO معقدة، فإن استخدام NewtonSoft.Json يعد رهانًا آمنًا اعتبارًا من .NET 7.

جانب عميل TypeScript:

1. مترجم تايب سكريبت
2. مسج
3. الزاوي 2-17
4. أوريليا
5. أكسيوس
6. جلب واجهة برمجة التطبيقات

لمزيد من التفاصيل، يرجى مراجعة:

1. ويكي
2. وأوضح الإعدادات
3. إنشاء C# .NET Client API لـ ASP.NET Web API
4. إنشاء واجهة برمجة تطبيقات عميل TypeScript لـ ASP.NET Web API
5. ASP.NET Web API وAngular2 وTypeScript وWebApiClientGen
6. إنشاء C# Client API لـ ASP.NET Core Web API
7. الحلول المقصودة للقيود المتعمدة لمولدات عملاء OpenAPI المكتوبة بقوة. تستخدم المقالة OpenApiClientGen كمثال فقط، بينما يمكن تطبيق المبادئ والحلول على الأكواد التي تم إنشاؤها بواسطة WebApiClientGen لتطبيقات العميل لديك.
8. التاريخ فقط في ASP.NET Core 6

التطبيقات التجريبية

التطبيقات التجريبية الموجودة في هذا المستودع مخصصة بشكل أساسي لاختبار WebApiClientGen أثناء التطوير. وهناك تطبيقات تجريبية أخرى في المستودعات التالية، مما يوضح كيف يمكن لتطبيقات العالم الحقيقي استخدام WebApiClientGen:

1. أمثلة WebApiClientGen لـ .NET Framework و.NET Standard وXamarin وvue TS.
2. عرض .NET Core لـ ASP.NET Core MVC وWeb API وASP.NET Core + Angular وMAUI وfetchAPI وvue TS وReact TS.
3. WebApiClientGen مقابل Swagger

تتم صيانة هذه التطبيقات التجريبية بشكل نشط ويتم تحديثها بأحدث أطر العمل. إذا كنت لا تزال تستخدم بعض الأطر القديمة مثل Angular 4 أو 5 أو .NET Core 2.0، فيمكنك الانتقال إلى العلامات الخاصة بالمستودعات والخروج.

جولة الأبطال

Tour of Heroes هو التطبيق التجريبي التعليمي الرسمي لـ Angular.

لتوضيح تجربة المبرمج في استخدام WebApiClientGen، تم تصميم التطبيقات التجريبية التالية بتصميم معماري مماثل لنفس الميزات الوظيفية في أطر التطوير أو المكتبات المختلفة، ومع ذلك، فإنها تتحدث إلى واجهة خلفية حقيقية.

1. Angular 2+، والنماذج التفاعلية المكتوبة
2. زامارين
3. ماوي. هاجر من أبطال Xamarin.
4. أوريليا. وشملت مجموعة اختبار التكامل.
5. رد فعل. وشملت مجموعة اختبار التكامل.
6. بليزر مستقل

NewtonSoft.Json أو System.Text.Json

بينما يدعم WebApiClientGen كليهما، فقد تحول الدعم الأساسي إلى System.Text.Json منذ عام 2024.

لا يزال لدى NewtonSoft.Json بعض المزايا في سيناريوهات وسياقات معينة:

1. إذا كان لديك الكثير من فئات POCO المزينة بواسطة DataContractAttributes، بسبب دعم التطبيقات القديمة، أو دعم تسلسل XML وJSON، فإن NewtonSoft.Json يمنحك دعمًا متأصلًا، بينما يوفر System.Text.Json بعض الدعم المزعج وغير المباشر منذ .NET 7.
2. بالنسبة لبعض أنواع المصفوفات والديناميكية، لا يزال NewtonSoft.Json أفضل.