NClient
v0.13.0
NCLIENT: عميل HTTP الآمن من النوع التلقائيNCLIENT هو عميل .NET HTTP التلقائي الآمن من النوع والذي يمكنه استدعاء أساليب واجهة برمجة تطبيقات الويب باستخدام واجهات مشروحة. الفرق الرئيسي بين NCLIENT ونظائره هو أن NCLIENT يتيح لك التعليق على وحدات التحكم ASP.NET عبر واجهات ثم استخدام هذه الواجهات لإنشاء العملاء. يتيح لك ذلك التخلص من التبعيات غير المرغوب فيها على جانب العميل وإعادة استخدام وصف واجهة برمجة التطبيقات في العملاء دون رمز Boilerplate.
// WebService.dll:
public class WeatherController : ControllerBase , IWeatherFacade {
public Task < Weather > GetAsync ( string city , DateTime date ) => .. . ;
}
// WebService.Facade.dll:
[ HttpFacade , Path ( "api/[facade]" ) ]
public interface IWeatherFacade {
[ GetMethod ( "{city}" ) ]
Task < Weather > GetAsync ( [ RouteParam ] string city , [ QueryParam ] DateTime date ) ;
}
// Client.dll:
IWeatherFacade weatherFacade = NClientGallery . Clients . GetRest ( )
. For < IWeatherFacade > ( host : "http://localhost:5000" )
. WithSafeResilience ( maxRetries : 3 )
. Build ( ) ;
Weather todaysWeather = await weatherFacade . GetAsync ( city : "Chelyabinsk" , date : DateTime . Today ) ; هل أحببت ذلك؟ دعم تطوير هذا المشروع ونجم هذا الريبو!
يمكن أن يمثل إنشاء عملاء لخدمات الويب تحديًا كبيرًا لأنه ، بالإضافة إلى نقل البيانات ، تحتاج إلى تنفيذ بناء الاستعلام ، والتسلسل ، وسياسات إعادة المحاولة ، والتعيين ، ومعالجة الأخطاء ، وتسجيلها - ناهيك عن الصيانة التي تأتي مع كل تحديث لواجهة برمجة التطبيقات. ماذا لو كان بإمكانك إنشاء عملاء مع جزء صغير من الجهد؟ هذا هو بالضبط ما يهدف NCLIENT إلى تحقيقه من خلال السماح لك بإنشاء العملاء بشكل إعلاني.
بالمناسبة ، يمكنك المساهمة في nclient ، وليس فقط استخدامه؟
الميزات: التوجيه الديناميكي المقدر ؛ توجيه ثابت معلمات الاستعلام الديناميكية ؛ مجموعات كمعلمات الاستعلام ؛ الرؤوس الديناميكية الرؤوس الثابتة الجسم الديناميكي التسلسل التلقائي وفرس ؛ HTTP/سياق النقل ؛ المصادقة طلبات غير متزامنة ؛ مهلة طلبات الإلغاء ؛ سياسة المرونة ؛ التحقق من الاستجابة تعيين الاستجابة تحميل الملف/التنزيل ؛ واجهات عامة. وراثة الواجهة. مصنع العميل ؛ الإصدار التعامل تسجيل منظم ؛ دعم حقن التبعية.
أسهل طريقة لتثبيت حزمة nclient باستخدام Nuget:
dotnet add package NClient
يتطلب استخدام مكتبة NCLIENT .NET Standard 2.0 أو أعلى. يمكن استخدام وحدات التحكم NCLIENT مع ASP.NET CORE و .NET CORE 3.1 الهدف أو أعلى.
أولاً ، يجب عليك إنشاء واجهة تصف نقاط النهاية المتاحة وبيانات الإدخال/الإخراج للخدمة عبر التعليقات التوضيحية. بعد ذلك ، يمكنك تحديد النوع المطلوب من العميل في NClientGallery ثم تعيين إعدادات إضافية لذلك إذا لزم الأمر.
إذا كنت ترغب في إرسال طلبات إلى خدمة تابعة لجهة خارجية ، فيجب عليك إنشاء واجهة تصف الخدمة التي تريد تقديم طلبات إليها. اتبع الخطوات أدناه:
NClient في مشروع العميل dotnet add package NClient
dotnet-nclient dotnet tool install --global dotnet-nclient
dotnet nclient generate facade --api path/to/product-service-swagger.json --output MyProject/Client.cs
سيقوم هذا الأمر بإنشاء واجهة لـ API باستخدام مواصفات OpenAPI (Swagger):
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
} إذا لزم الأمر ، يمكن تغيير الواجهة. من السهل القيام بذلك لأن شرح الواجهة يشبه إلى حد كبير التعليق التوضيحي لوحدات التحكم في ASP.NET. يحدد PathAttribute المسار الأساسي لجميع طرق الواجهة. يحدد PostMethodAttribute نوع طريقة HTTP والمسار إلى نقطة النهاية. علاوة على ذلك ، تعمل التعليقات التوضيحية الضمنية كما في وحدات التحكم ASP.NET ؛ على سبيل المثال ، سيتم تعيين سمة BodyParamAttribute ضمنيًا على معلمة المنتج في طريقة CreateAsync. وبالتأكيد ، يتم دعم قوالب الطريق أيضًا. اقرأ عن جميع الميزات في أقسام التعليقات التوضيحية والتوجيه.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; تقوم طريقة GetRest بإنشاء عميل REST مع System.Text.Json Serialization وبدون سياسة مرونة.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. WithNewtonsoftJsonSerialization ( )
. WithResilience ( x => x
. ForMethod ( client => ( Func < Product , Task < Product > > ) client . CreateAsync )
. Use ( maxRetries : 2 , attempt => TimeSpan . FromSeconds ( Math . Pow ( 2 , attempt ) ) ) )
.. .
. Build ( ) ; بعد الاتصال بالطريقة For ، يمكنك تكوين العميل حسب الحاجة. على سبيل المثال ، يمكنك استبدال Serializer بـ Newtonsoft.Json ، وإضافة سياسة إعادة المحاولة ، وما إلى ذلك. انظر الوثائق الكاملة.
// Equivalent to the following request:
// curl -X POST -H "Content-type: application/json" --data "{ id: 1 }" http://localhost:8080/api/products
Product product = await client . CreateAsync ( new Product ( name : "MyProduct" ) ) ;إذا كنت ترغب في إنشاء عميل لخدمة ويب ASP.NET الخاصة بك ، فأنت بحاجة إلى استخراج واجهة لوحدة التحكم الخاصة بك والتعليق عليها بسمات nclient. هذه السمات تشبه إلى حد كبير تلك المستخدمة لوحدات التحكم ASP.NET. اتبع الخطوات أدناه:
NClient.AspNetCore على جانب الخادم dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}لا تشرح توضيح وحدة التحكم الخاصة بك بسمات ASP.NET التي قد تتسبب في تعارضات دلالية مع سمات nclient التي تنوي استخدامها. ومع ذلك ، يمكن استخدام سمات أخرى (بما في ذلك الخاصة بك) دون قيود.
[ HttpFacade , Path ( "[controller]" ) ] // equivalent to [ApiController, Route("[controller]")]
public interface IWeatherForecastController
{
[ GetMethod ] // equivalent to [HttpGet]
Task < WeatherForecast > GetAsync ( [ QueryParam ] DateTime date ) ; // equivalent to [FromQuery]
}
public class WeatherForecastController : ControllerBase , IWeatherForecastController { .. . }يتيح لك التعليق التوضيحي في الواجهة بدلاً من وحدة التحكم وضع الواجهة في مجموعة منفصلة. وبالتالي ، لا يعتمد العميل الذي يستخدم هذه الواجهة على تطبيق ASP.NET.
public interface IWeatherForecastClient : IWeatherForecastController { } يجب عليك القيام بذلك إذا كنت تريد أن يكون نوع العميل الخاص بك لا يحتوي على "وحدة تحكم" في الاسم أو إذا كنت ترغب في تجاوز بعض الطرق للعميل (انظر OverrideAttribute في قسم التعليقات التوضيحية). ليست هناك حاجة لتكرار سمات الواجهة ، لأنها موروثة.
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} يمكن استخدام طريقة AddNClientControllers مع طريقة AddControllers . يتيح لك ذلك استخدام وحدات تحكم ASP.NET القياسية مع وحدات التحكم NCLIENT في نفس التطبيق.
NClient على جانب العميل dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; إذا قررت اتباع الخطوة الرابعة ، فاستخدم واجهة IWeatherForecastClient بدلاً من IWeatherForecastController .
// Equivalent to the following request:
// curl -X GET -H "Content-type: application/json" http://localhost:8080/WeatherForecast?date=2021-03-13T00:15Z
WeatherForecast forecast = await client . GetAsync ( DateTime . Now ) ; يمكنك العثور على وثائق nclient على الويكي.
راجع عينات من التطبيقات في مشروع NCLIENT.Samples.
هل تفكر في المساهمة في NCLIENT؟ عظيم! نحن نحب تلقي مساهمات من المجتمع! أبسط مساهمة هي إعطاء هذا المشروع نجم.
المساعدة في الوثائق أو طلبات السحب أو المشكلات أو التعليق أو أي شيء آخر مرحب به أيضًا. يرجى مراجعة دليل المساهمة لدينا.
يجدر الاتصال بنا لمناقشة التغييرات في حالة وجود أي أسئلة. يمكننا أيضًا تقديم المشورة بشأن أسهل طريقة للقيام بالأشياء.
يرغب NCLIENT في أن يشكر JetBrains لدعمه للمشروع بتراخيص مجانية مفتوحة المصدر.
